docs(authoring): document backslash math delimiters

[mcanouil]

Add a note to the Equations section of the Markdown Basics page documenting that \(...\) and \[...\] math delimiters are supported via Pandoc's tex_math_single_backslash extension.

Closes quarto-dev/quarto-cli#12263

[cderv]

/deploy-preview

[github-actions]

📝 Preview Deployment

🔍 Full site preview: https://deploy-preview-2088.quarto.org

🔄 Modified Documents

• docs/authoring/markdown-basics.html

[cderv]

This from option is tricky because it is kind of hidden (probably a bit on purpose as not sure every option works well - thinking this because of our custom lua reader).

I wonder if somehow this means that we should expose this type of options differently... 🤔

To avoid users to set from but use another option. Like math-delimiter ?

Other related thinking:

This syntax Pandoc extension syntax can also be confusing because (1) this is pandoc feature, (2) we don't explain it anywhere I think - except through our issue replies when needed. So just doing it for this specific +tex_math_single_backslash is maybe too out of the box. I would try see if we can add context about this is being pandoc (https://pandoc.org/MANUAL.html#math-input) and think on how to explain it.

@cwickham did you have something in mind when opening quarto-dev/quarto-cli#12263 ? Any thought on this ?

[mcanouil]

That's true it's kind of hidden, but in plain sight as it's suggested by the YAML schema, so you can see it in auto-complete, etc.

And it's already mentioned in the documentation for the visual editor section for emoji support: https://quarto.org/docs/visual-editor/content.html#emojis

We could add a from callout/section in markdown-basics.qmd to explain the from reader option. Maybe something about variants as well, as it's a recurring thing we talk about in issues/discussion, it might deserve more space in the documentation, but this is a separate task/PR I believe.

[cderv]

yes visual editor doc has been 'copied' into quarto.org without much adaptation from https://rstudio.github.io/visual-markdown-editing/

Maybe something about variants as well, as it's a recurring thing we talk about in issues/discussion

yes i know - it 'kinda' works but we know it is not full proof. Being undocumenting help reduce the surface of possible problem :)

it might deserve more space in the documentation, but this is a separate task/PR I believe.

Agreed this is another PR. I wondered about the order. We could document reader and writer logic, and from + to and variant and be able to link from other part like this one.

🤷 I don't know really - maybe this is fine to put this +tex_math_single_backslash out there without doing more, but I feel this should be simpler if user's needs that. We try to hide most Pandoc logic, expecially when complex, so we could do that here with a new math config.

[cwickham]

In regards to quarto-dev/quarto-cli#12263, I was just splitting an issue in two. I wasn't sure how much we want to expose Pandoc extensions. Will q2 be a bit more opinionated on this?

[cderv]

Will q2 be a bit more opinionated on this?

Oh I think it will. We don't use Pandoc binary so I don't know if we are really supporting all pandoc feature like this. non default quarto one.

So another way to maybe not document this that much if we don't support all.

I need to verify, but possible this Math syntax won't be supported. @cscheid did you already decide on how q2 will behave related to pandoc format extensions ?

[cscheid]

I need to verify, but possible this Math syntax won't be supported. @cscheid did you already decide on how q2 will behave related to pandoc format extensions ?

Yes. We support only what our dialect does and won't have extensions at all (yes, this will upset some users). If there are sufficiently large gaps in user expectations and what we can parse, we will change the qmd parser and everyone gets it. We can't afford to compile a large number of tree-sitter-qmd variants and switch between them arbitrarily, and we need a high-performance parser for the LSP (source diagnostics) and incremental-writer applications (quarto-hub).

[cscheid]

I actually would propose to not document this here, because it's likely going away for q2...

[cderv]

I actually would propose to not document this here, because it's likely going away for q2...

That is what I thought. I agree with it.

Users who want this in quarto 1 can find info searching issues today. Not great, but our replies to issues are still documentation in a way.