Skip to content

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

Open
wants to merge 4 commits into
base: master
Choose a base branch
from

Conversation

alecloudenback
Copy link
Contributor

Two changes:

  1. Cross reference the two separate LaTeX sections.
  2. Note the $ and $$ ways of creating LaTeX formatting.

Question for reviewer, should the added line be

md"$$H = - \sum p(x) \log p(x)$$"

or

$$H = - \sum p(x) \log p(x)$$

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.

@fredrikekre
Copy link
Member

IIRC, $ is soft deprecated and is deliberately not documented because there are cases where it doesn't work. cc @mortenpi

@mortenpi
Copy link
Contributor

mortenpi commented Aug 24, 2023

IIRC, $ is soft deprecated and is deliberately not documented because there are cases where it doesn't work.

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.

@alecloudenback
Copy link
Contributor Author

Is this a good note?

!!! 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 
    whereas it will alert the user to an unmatched ``` `` ```.

@mortenpi
Copy link
Contributor

Yeah, I think something like that is quite fine. We should also mentioned $$ vs ```math while we're at it though.

@alecloudenback
Copy link
Contributor Author

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 ``` `` ```.
Copy link
Contributor

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
Copy link
Contributor

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).

Copy link
Member

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" ?

@@ -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:
Copy link
Contributor

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]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

5 participants