Katex: Strict mode proposal

[edemaine]

• We currently have the (wordy) unicodeTextInMathMode option to switch between what you might call "strict LaTeX behavior" (no Unicode text symbols in math mode) and "flexible/permissive behavior" (which aligns with MathJax and is probably more convenient to use, especially if you don't want to export to regular LaTeX/XeTeX later).
• Another example of this is #1167, which wants to allow non-boxes as arguments to \raise/\lower. Again we have a natural "strict LaTeX compatibility" vs. "flexible/convenient behavior". I imagine a recurring theme here.
• src/functions/kern.js warns about mu units used by a spacing command not starting with m, and warns about non-mu units used by a spacing command starting with m. This seemed like a reasonable compromise between strict LaTeX compatibility (let users know that they're breaking the rules) and flexibility (annoying to keep track of LaTeX's many different spacing functions).

I propose that we define a global setting strict which controls this dichotomy. strict: true or strict: "error" (allow one or both forms?) can force strict LaTeX behavior as much as possible, and raise an error upon violation. strict: "warn" can check for LaTeX compatibility, but just print a warning upon misuse. Maybe strict: (msg) => ... can provide a callback for custom handling / warning. strict: false can be the default permissive mode where violations are ignored. We could implement this with a helper, maybe a Parser.checkStrict method where Settings are readily available, that implements the appropriate behavior.

Let me know your thoughts! I think this will help us avoid making repeatedly difficult (and possibly inconsistent) decisions about this dichotomy, though there are probably multiple ways to resolve it.

[ronkok]

Terrific idea. Many people migrate to KaTeX from MathJax, not LaTeX. We want to avoid difficult barriers for them.

[ronkok]

Another candidate for strict: false would be our environments. As long as MathJax exists, some authors will wish to write {align}, {gather}, and {alignat} instead of {aligned}, {gathered}, and {alignedat}.

[edemaine]

@ronkok Great idea. In general, we can somewhat (but not officially) think of strict: false as being like a MathJax compatibility mode, given their more lax choices.

[ylemkimon]

How about providing a settings preset? This way we don't have to add an extra setting which may be override others and an user can know and control what it does.

[edemaine]

@ylemkimon I'm OK with this in principle, though I do think it'd be slightly less convenient to use... something like:

const options = katex.strictOptions(); // make copy of strict options preset
options.displayMode = true;
katex(..., options)

Or maybe we could make a helper...

katex(..., katex.strictOptions({displayMode: true}))

But I wonder if the complexity is necessary. Can you imagine a use case where we'd want to require strict behavior on one feature (e.g. Unicode) but not on another (e.g. \mskip)? I can only imagine wanting strict LaTeX compatibility or allowing whatever is most convenient...

[kevinbarabash]

I think having separate settings for the changes we're making is useful for keeping track of what changes in behavior from LaTeX exist outside of strict mode. It's probably worth allowing access to each setting in cases some users get use to a particular flavor of non-strict mode.

[kevinbarabash]

think of strict: false as being like a MathJax compatibility mode, given their more lax choices

We may also want to have a mathjax compatibility mode that is separate from non-strict mode.

@edemaine were you thinking that non-strict mode would be the default and that people would opt-in to strict mode?

[edemaine]

@kevinbarabash Yes, either no strictness or maybe warning level. My guess is that most people don't care about strict vs. not, and they'd rather have the most things just work. But I'm not certain.

I do worry about a proliferation of options... so I still like the single option. Note that the callback idea in the original post could let someone still customize some aspects and not others. For example:

strict: (thing, message) => thing === 'unicodeTextInMathMode' ? 'error' : 'warn'

API still to be nailed down...

In some sense this still exposes all the options, but it also makes it easy to just set everything to 'warn' or 'error' or off.

[ronkok]

so I still like the single option.

Me too.

[kevinbarabash]

Sorry for not getting back to y'all on this sooner. We could do a poll about this, but I'm pretty sure that the vast majority of our user base care more about sane defaults and having more flexibility in how they code their TeX than they do about strict adherence to LaTeX's behavior. That being said, providing a strict mode is important, but I think have it be off by default is probably the way to go. Also, a single option is probably the way to go. It would be nice in the long run to all certain things like the distance between rows in a matrix to be configurable from within the LaTeX code using \setlength. There will be of course certain behaviors such as what's allow inside \raise and \lower that can't easily be controlled by TeX code and we shouldn't worry about making those configurable.

TL;DR: let's go with a single strict mode option that is off by default.