Katex: Idea: top-level environment option

[edemaine]

KaTeX currently essentially only supports $...$ and $$...$$ for entering math mode. It doesn't support:

• \begin{equation}...\end{equation} (#445, which includes automatic equation numbering #350)
• \begin{eqnarray}...\end{eqnarray} (requested once in #1931)
• \begin{align}...\end{align} (similar effect to $$\begin{aligned}...\end{aligned}$$, as described in one of our common issues, but the effect is actually very different with equation numbering, so this will be more relevant with #350, and it's even an issue with \tag, see also #2004)
• \begin{alignat}{n}...\end{alignat} (but, having an argument, this one isn't addressed by this proposal)
• \begin{gather}...\end{gather}
• \begin{multline}...\end{multline}
• \begin{flalign}...\end{flalign} (#1990, though we have the related option fleqn)

I propose a new render option with a name like mathEnv or topEnv or env or something, or else a redefinition of displayMode to allow values other than false (meaning $...$) and true (meaning $$...$$). Either way, I'd like to allow values like equation, eqnarray, eqnarray*, align, align*, split, split*, gather, gather*, flalign, flalign*, multline, multline*, as well as math (equivalent of inline $...$) and displaymath or equation* (equivalent of display $$...$$). Then we could add a matching option to auto-render's delimiters (or replacing the existing display option) so that \begin\s*{equation}...\end\s*{equation} would end up calling render with the top-level environment set to equation.

This would finally let us support other top-level math environments in what I believe is a natural way. Assuming you like the idea, I'd appreciate some suggestions on the name for the option, or whether to overload displayMode, or whether to deprecate displayMode (as it's effectively redundant with this option).

[ronkok]

@edemaine Good stuff. I wholly agree with what you propose.

As to the details, I think that deprecating displayMode would be too drastic. It would break too many existing documents. And for that reason my inclination would be to overload the existing displayMode option. When the system is fully built out, displayMode would be settable to:

true | false | equation | equation* | align | align* | gather | gather* | flalign | flalign*| multline | multline*| alignat | alignat*

That list comes from section 3.1 of the AMS Users Guide. I did not include split because split occurs inside the equation environment.

displayMode would continue to be optional, with a default of false.

When this system is in place, the auto-render extension could be upgraded so that it would trap, for example, \begin{equation} and call KaTeX with displayMode: equation.

[ronkok]

Now a question: Should the auto-render extension allow nesting of a top-level environment inside $$…$$?

LaTeX does not allow it. MathJax does, and I suspect that many Markdown environments will depend on it. Because of the Markdown aspect, my initial answer is "yes, we should allow it".

[edemaine]

@ronkok Agreed on the list; mine had typos, sorry! There are also some base LaTeX options, like math, displaymath, eqnarray, and eqnarray*.

I personally find it weird, and possibly impossible, to support something like $\begin{equation}...\end{equation}$. But to the extent it's possible, we could try to MathJax behavior, when strict is false or "warn".

This raises the question of how the new option will be implemented. I had assumed that top-level environments were being treated differently, which is necessary in some sense because it will interact with \tag that is handled with special code at the top level (because of layout). Will/can they still be processed via defineEnvironment, or are they something new? I'll have to think about this and/or try implementing it to see. This will impact the extent to which we can achieve "outer environments inside math mode instead of outside".

[ronkok]

Yes, \tag has layout implications at the top level. But I think we'll also want to support things like \notag and \shoveright, so the values of leqno and fleqn will need to be available and locally changeable from inside parseArray() which is currently not the case.

Like you, I have not yet worked out any way to implement this. I think it will involve something like what you did for persistent macros with Namespace. Some sort of data structure that persists between KaTeX fields and gets incremented when the parser hits the appropriate environment. The data structure can no doubt be much simpler than Namespace.

[kevinbarabash]

So the issue is that there are a number of environments that can only be entered from text mode but we're already in math mode from the get go which makes using \begin{align} weird and undefined behavior in LaTeX.

Another approach might be to introduce a new delimiter that only accepts a text environment. Assuming the new delimiter is && then people could write the following in their HTML and have it work with the auto-render extension: &&\begin{align} ... \end{align}&&.

&& would essentially be limited top-level text mode. It would also be available via an option to render.

[edemaine]

@kevinbarabash That's a neat idea (though a little ugly). But beyond how to notate entering KaTeX in text mode (that's an auto-render issue), there's no way to enter the main KaTeX engine starting in text mode. I guess we could add an option to render/renderToString which specifies an initial mode of text or math (defaulting to math)... but I fear that this would be much harder to implement, because parsing LaTeX in text mode is a much taller order than our current support of \text, because that only required supporting TeX horizontal mode. Whereas \begin{align} ... \end{align} only makes sense in TeX vertical mode, which we are really far away from supporting.

So I think it's best to stick to fixing "how do I specify the top-level math environment". I guess life would be easier if the argument to render/renderToString already included the wrapping $s or \(...\) or \[...\] -- then the user could just specify a different wrapping environment. So another way would be to add an option like wrapped that specifies whether the argument has the wrapper. But the outer wrapping environment really does behave differently from everything else that we support. Hmm, now I see that this might be exactly what @kevinbarabash meant by "limited top-level text mode".

[ylemkimon]

Related: #604.

[kevinbarabash]

@edemaine I was thinking that "limited top-level text mode" would essentially be as if we wrapped the entire expression in \text{}.

[edemaine]

@kevinbarabash But \begin{align} etc. don't work within \text, I believe because \text enters horizontal text mode while \begin{align} only works in vertical mode.

[kevinbarabash]

I see what you're saying now.