- Sponsor
-
Notifications
You must be signed in to change notification settings - Fork 5.6k
Markdown LaTeX doc enhancments #51032
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: master
Are you sure you want to change the base?
Conversation
IIRC, |
I think the "doesn't work" part is mainly just that it's very easy to run into issues with it conflicting with the interpolation syntax. But yes, it's deprecated and should not be used. What I would suggest is that we actually do document it, but in a big warning note that this is deprecated syntax and should not be used. |
Is this a good note?
|
Yeah, I think something like that is quite fine. We should also mentioned |
I tried to address the discussion here about the depreciation status and avoid redundancy except to the extent necessary to cross-reference the LaTeX sections. |
Inline ``\LaTeX`` may also be created within a set of single of `$` characters, though this is | ||
depreciated. The ``` `` ``` syntax is preferred as `$` is also used for string interpolation - | ||
the parser will interpret an accidentally unmatched `$` as an intented string interpolation | ||
whereas it will alert the user to an unmatched ``` `` ```. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
it will alert the user to an unmatched
I don't think this is true? Any sequence of characters should get parsed as Markdown without errors.
!!! note | ||
Inline ``\LaTeX`` may also be created within a set of single of `$` characters, though this is | ||
depreciated. The ``` `` ``` syntax is preferred as `$` is also used for string interpolation - | ||
the parser will interpret an accidentally unmatched `$` as an intented string interpolation |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If it's inline, it can't really be indented? I think this sentence should be rephrased (see also the note below).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think "intented" was meant to be "intended" not as "indented", which makes some sense, but still should be changed.
But is this all even true? I thought $
is always parsed as string interpolation because Julia does this before any documentation code ever sees the docstring?
Maybe that's a feature of the (undocumented) md_str
? In any case, it seems misleading to discuss this here. Maybe better to say something to the effect of "Don't use $
as it is interpreted as string interpolation; if you really want to use it, use a raw
string" ?
stdlib/Markdown/docs/src/index.md
Outdated
@@ -285,6 +293,14 @@ f(a) = \frac{1}{2\pi}\int_{0}^{2\pi} (\alpha+R\cos(\theta))d\theta | |||
``` | |||
```` | |||
|
|||
Note that the `\$\$` version is available but depreciated: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We should probably put this is a !!! note
admonition too.
Co-authored-by: Morten Piibeleht <[email protected]>
Two changes:
$
and$$
ways of creating LaTeX formatting.Question for reviewer, should the added line be
md"$$H = - \sum p(x) \log p(x)$$"
or
The latter seems more consistent with the omission of the markdown string macro elsewhere but I'm also not sure that it's clear that it has to be done within a markdown string without it.