Katex: Improve documentation of missing features and workarounds

[bb010g]

KaTeX is optimized for rendering a subset of LaTeX fast—which is great! What's not so great, though, is when you don't know quite what that subset is and run into issues. Right now, KaTeX's main documentation doesn't cover well what it's missing. There's a listing of what is present, but not what isn't. CONTRIBUTING.md tells you how to add a new symbol, but doesn't tell you where you should start. Aside from paging through the issue tracker, there's no clear way to know what's missing or where you should help out first.

I believe a central source of missing features would greatly help with both directing contributors at what's missing and with making sure people considering KaTeX for LaTeX rendering on the web know what they're setting up. If a user needs more intense LaTeX rendering, KaTeX's documentation should direct them to MathJax, perhaps with a guide to set it up as a fallback. For the features that are partially supported, this would be a great place to put or link workarounds so that they're easy to find. If a user wants to update their site's math after a few months of KaTeX improvements, they could just scroll through for what they used and see if there are better workarounds (or if they've been eliminated entirely) without having to subscribe to or bookmark a (potentially large) set of issues.

[edemaine]

It sounds like you're looking for an index of the feature requests (say, "regular LaTeX features") that are in the issues? (Unless you have in mind a way to also find LaTeX features we're missing that are not yet issues...) I worry about keeping such a list up-to-date... Maybe if there was a tag on issues for "missing LaTeX feature", we could link to the list of them (as opposed to the entire list of issues, which has many other KaTeX-specific things on it).

Could you walk through a use-case where you want a list of missing features? My impression is that most users who are considering KaTeX just try it out and see if it's missing anything they need, and if so, they search for that feature in the issues (it's usually clear that some \command is not supported), follow it, and/or report it as a new issue. Then we try to add it when possible... Personally, KaTeX has basically all the features I want, and the many users seem to agree...

Personally I'd be more interested in some way to automatically detect (and list) features supported by MathJax (say) but not KaTeX. Not sure how difficult this would be.

[kevinbarabash]

The list of what isn't in KaTeX could be very large. LaTeX supports lots of packages. I guess we could list some popular packages that we don't support at all, and then for packages where we do have partial support list those things from those packages which we don't support. This would take a big effort though so I'd want to have some way to automate this.

[ylemkimon]

There is an Alphabetical List of TeX Commands available in MathJax. Maybe we can use it to build a list of missing features and compare with MathJax.

[ronkok]

This page makes a pretty good attempt at documenting which MathJax commands are not yet in KaTeX. The KaTeX Contributing page already alludes to it.

[ronkok]

Several of those MathJax features are not present in any LaTeX package. And some of them are duplicates of LaTeX functionality. Like \cases in addition to \begin{cases}. Such features may never make it into KaTeX.

[ronkok]

As to a fallback, I used to have a site in which, after calling renderMathInElement, I would make the following call ;

(function () {
  var script = document.createElement("script");
  script.type = "text/javascript";
  script.src  = "http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_HTML";
  document.getElementsByTagName("head")[0].appendChild(script);
})();

That code is now out of date. MathJax has changed their CDN and they now have version numbers, not "latest", in the address.

But I stopped calling a fallback because there was no longer any point. KaTeX renders all that I need.

[ErikMcClure]

Given @ronkok's suggestion, linking this page prominently in the main KaTeX documentation instead of in the contributing page would be enormously helpful if someone installs KaTeX only to later find out that something they want to use for a new document isn't supported yet.

[ronkok]

@kevinbarabash Query: Should I put this page into the list of links on the function support page?

Keep in mind that that page has some errors. And a couple of them are silly, like saying that KaTeX does not support \begin or \end.

[ronkok]

I can't think of a title short enough to fit onto the list. Maybe I'll just add the link to the introductory paragraph at the top of the page.

[kevinbarabash]

@blackhole12 thank you for reminding me about that page.

Interestingly % fails b/c we require a new line at the end of comments. The test for \left and \right fail b/c we require those to be balanced as does LaTeX (MathJax appears to be more liberal with what it accepts). We should probably file issues with https://github.com/utensil-site/available-in-katex/issues for the \left and \right at least.

The list appears to be out of date a bit, e.g. \S and varGamma etc were added recently. It's use the version from khan.github.io/KaTeX which explains why. I need to update that.

Some of the tests should fail, e.g. \end on its own. Some are easy to add, e.g. \cal is the implicit group style version of \mathcal which we already support. I think \unicode would be pretty easy to add too.

The list is also highlighting some bug, e.g. the \llap test. We aren't allowing \, in text mode but we should. Same thing with \rlap except it's \;.

[kevinbarabash]

I've also opened https://github.com/utensil-site/available-in-katex/issues/2 to find a way to run the tests in node so that we can use the data to update our README.md at publish time.

[kevinbarabash]

I think \brace and \brack wouldn't be too hard to support as we already support \over, \choose, and \atop. They're all very similar.

[ronkok]

Yeah, \llap and\rlap are difficult. In LaTeX, they work in math mode, but only sometimes, depending on what's in the argument. And I have not found a robust rule that tells me exactly when they work and when they don't. I'll work on it this weekend.

[ronkok]

The list of what isn't in KaTeX could be very large.

Yes, but we can focus on a subset taken from two sources:

1. KaTeX's GitHub issues page.
2. http://utensil-site.github.io/available-in-katex/

Those are items that somebody either cared about enough to program them or at least to sit down and write a request.

That subset is much smaller, with fewer items to manage than the KaTeX function support page. So I've written it up. It's a KaTeX wiki page.

Please feel free to edit it and improve it.

[ronkok]

I think \brace and \brack wouldn't be too hard to support

Technical notes on the amsmath package deprecates the whole family of functions that use the infix syntax similar to \atop. It suggests using genfrac instead. I can write a PR that will add \genfrac to KaTeX.

Once we have \genfrac, do we still want to include \above, \brace, \brack, and \atopwithdelims ? \genfrac can be used as an alternate for any of those functions.

The AMS Tech Notes says that they deprecated those functions because the infix syntax causes problems for macros. Maybe @edemaine can weigh in here?

[edemaine]

I'd say we should ideally support both. We already support \over and \atop (which I'm very happy about, as I use those myself day-to-day -- I find they are more intuitive than say \frac). It also shouldn't be hard to support one given the other (and I'd be happy to work on that aspect of it, as I've added these kinds of implicit-argument commands before). But \genfrac sounds like a good starting point!

[ronkok]

@edemaine Say that we add the other infix functions. Should the function support page then include a disclaimer saying that they might coexist poorly with macros?

Or are those problems just the sort of thing that a macro writer is expected to know?

[kevinbarabash]

I think a warning to not use infix functions inside macros is a good note as lots of people will probably be writing macros even though they don't know some of these issues.

[edemaine]

Personally, I find the AMS's deprecation of a standard TeX/LaTeX feature kind of obnoxious, even if it is well-intentioned. Many users don't \usepackage{amsmath}, so they don't even have a choice here. I believe KaTeX should be agnostic on these points (we shouldn't deprecate them), in particular because it's unlikely that KaTeX-level macros will get into the issues mentioned. But it certainly wouldn't hurt to link to the AMS document for reference.

[ronkok]

it's unlikely that KaTeX-level macros will get into the issues mentioned.

That's a key point, I think. Things like the \genfrac that I am about to write are done with macros inside AMS. So they run into control issues that KaTeX-level macros do not. @edemaine has convinced me. I'll get started on \genfrac and I don't plan to add any disclaimers for infix functions.