auto-render default delimiters missing some environments

[edemaine]

auto-render's current default delimiters:

• $$...$$
• \(...\)
• \begin{equation}...\end{equation}
• \begin{align}...\end{align}
• \begin{alignat}...\end{alignat}
• \begin{gather}...\end{gather}
• \begin{CD}...\end{CD}
• \[...\]

Missing:

• \begin{equation*}...\end{equation*}
• \begin{align*}...\end{align*}
• \begin{alignat*}...\end{alignat*}
• \begin{gather*}...\end{gather*}
• $...$ — shall we discuss adding this in, maybe together with [auto-render] add an option to ignore \$ outside of latex expressions #437? The code says:
  

  KaTeX/contrib/auto-render/auto-render.js

  Lines 97 to 99 in 9164a15

  	// LaTeX uses $…$, but it ruins the display of normal `$` in text:
  	// {left: "$", right: "$", display: false},
  	// $ must come after $$

@mbourne Let me know if there are others you know that are missing.

Discussed in #3659

^{Originally posted by mbourne June 15, 2022}
I set up an auto render page from scratch recently and couldn't figure out why some of the environments worked, and others didn't.

Then I found this page https://katex.org/docs/autorender.html which lists the default delimiters for the API. To get all the math on the page to render, I needed to include the default delimiters as listed plus the ones I was using on the page.

I thought this created some confusion that could have been avoided if all the supported environments were included in the the default list. I'm assuming KaTeX goes looking for math within each delimiter pair one by one, but I expect there would be a negligible performance hit if it wasn't to find some (even most) of the delimiters.

Or am I missing something?

[mbourne]

How about all the matrix, bmatrix and cases and so on?

Seems to me that all supported environments (as in https://katex.org/docs/support_table.html) should be included in the default list. It must be rather troublesome for users to have to dig around in their code to add new delimiters each time they have a new environment they want to add to their document.

So maybe each time there's a new build with a new environment that's newly supported, it should be automatically added to the default delimiter list.

I'm assuming there's no performance hit from such an arrangement - is that so?

As for $...$, since it hasn't been a default all along, I don't think it should become so now - it will break a lot of people's pages. It's actually the only one that should need to be added in the options object, I feel. \end{2c}

[edemaine]

The environments I listed are all special because they enter math mode from text mode in LaTeX. \begin{matrix} etc do not, and need to be wrapped in $ or $$ in LaTeX. Generally we want KaTeX to behave like LaTeX.

I agree adding $ would be a breaking change. But as the list of delimiters get long, I feel like it's harder to add (or keep the user's override list up-to-date). Maybe what I want is an easy option to add it (in the right place), which maybe is related to the \$ issue. Or for v1.0.0, we could make it on by default and make an option to turn it off.

Out of curiosity, do you use $? I do all the time, but I also don't use auto-render.

[mbourne]

The environments I listed are all special...

I see - I wasn't aware of that (being an ASCIIMath input person). Is it documented? (I know your job isn't to teach people LaTeX, but for those of us who don't use it regularly, it's quite confusing why some things work without $$...$$ while others don't.

How about something like the following:

1. Leave the default "non-special" list as is
2. Give an option to allow all the "special" ones as well, something like "delimitersAll: true"

Then users won't have long lists to juggle. They'd either get the current defaults, or the lot. If it was me, I'd set the lot.

Maybe what I want is an easier option (for $)

Actually, that thought occurred to me as well. It would be nice to have some kind of parameter on the render call, something like:

onload="renderMathInElement(document.body, 'delimiter$: true' );"

Or, given the above, allow another parameter, like:

onload="renderMathInElement(document.body, 'delimiter$: true',  delimitersAll: true);"

Given the Other Library requires the user to specify $ as a delimiter, my feel is still to leave it be.

I certainly do use $ with $ and would never use \( ... \).

Final idea. If the above ideas don't wash, how about a simpler way of entering delimiters, rather than the current way which is error-prone.

Rather than

  {left: "\\begin{align}", right: "\\end{align}", display: true},
  {left: "\\begin{align*}", right: "\\end{align*}", display: true},
  {left: "\\begin{alignat}", right: "\\end{alignat}", display: true},

How about

  environments: {'align', 'align*', 'alignat', 'CD', ...}

The longer version would be available for those wanting wacko left and right delimiters, or who want non-standard display mode, but the above would suit 99% of users, I imagine.

The two that don't fit into the \begin{x} ... \end{x} pattern (that is, \( ... \) and \[ ... \]) would still need to be written out in long form.