Katex: mhchem extension support

[bartolsthoorn]

I'm switching from _MathJax_ to _KaTeX_, but support for TeX extensions is currently missing. More specifically, I'd really like to use the mhchem extension: http://www.ctan.org/pkg/mhchem

For the record, this is how _MathJax_ supports it: http://docs.mathjax.org/en/latest/tex.html#mhchem

[xymostech]

Unfortunately, adding something like mhchem is a lot of work. We want to support it in the future, but it's not going to be a short-term goal.

If anyone wants to try, this mostly involves adding an extension to the parser, so that things inside \ce are parsed a different way. The output routines are almost good enough (e.g. \ce{CrO4^2-} is the same output as \text{CrO}{}_4{}^{2-}; all that's needed is some text-align: right for something like \ce{^{227}_{90}Th+, which is almost {}^{277}_{90}\text{Th}^+ but the 277 and 90 should be right aligned)

[mhchem]

This is the author of the original mhchem LaTeX package. I will create a JavaScript parser for mhchem syntax in 2016 that probably also could be used for KaTeX, if you are interested.

[xymostech]

@mhchem that sounds awesome! I think we would definitely be interested, if that gets done! Thanks!

[brunovcosta]

I had to make an fast adaptation of mchem code to work with KaTeX:
https://github.com/brunovcosta/mchem4katex

I can fork the katex in order to create the parser extension

[mhchem]

@brunovcosta could you get in touch with me via e-mail? I am interested in what you changed. A lot of time and effort went into fine-tuning the spacing (and this might continue), so that I am not too excited to hear you got rid of all of these spacing details. I'd like to hear your reasons and learn from that (and maybe vice versa).

[brunovcosta]

@mhchem, i can't find your email. Can you send me one? [email protected]

I made this adaptation because i needed mchem suport quickly. I understand the importance of the spacing details and i'm adapting my katex fork to support the required functions (\vphantom, \hphantom, \mathrel,\mkern and \mskip).

It's not intended to be an official pull request, neither an mchem replacement. Sorry about any mistake, i'll be happy to receive your email and help appropriately port mchem for katex

[arjun810]

Is there still a chance that this'll get ported over to KaTeX? Would be really useful! We might be able to help out too, depending on how much knowledge of the underlying package is involved.

[mhchem]

Yes, of course. mhchem's processing can be described as a 4-step process.

1. The LaTeX parser recognizes the \ce command and passes its argument on.
2. The mhchem parser parses the argument into an internal format
3. The mhchem texifier converts the internal format into a LaTeX expression
4. The LaTeX parser handles the output of step 3.

Step 1 can be done, proven by brunovcosta.

Step 2 is mhchem internal, no problem.

Step 3 depends on step 4. Currently, the output of step 3 cannot be handled by KaTeX on step 4.

I care about fine details of typography, but KaTeX is missing some functionality to achieve it. As I see, there is no \phantom, \vphantom, \smash, llap and maybe other commands I used. Most output can be created and looks acceptable without these commands (this is what brunovcosta did). But I wished these commands were available.

Furthermore, there are a few extra LaTeX commands available in step 4 so that mhchem can render things like non-standard stretchable arrows and special kinds of bonds.

The design was chosen so that I can be responsible for steps 2 and 3. And MathJax/KaTeX/... can be responsible for steps 1 and 4. While brunovcosta came a long way be modifying step 3, I'd favour if step 3 could be identical for KaTeX and for MathJax.

[gagern]

I wonder where to best place this in the KaTeX world of things. The Parser in KaTeX mostly deals with basic things after all macro expansion has been done. The macro expander, on the other hand, performs macro expansions. But so far that's for pretty dumb macros only; it doesn't do any conditional processing and the likes.

So one way to deal with this would be introducing a separate layer into the token stream, between macro expander and parser, where mhchem could do its conversions. In that case it would read input tokens from the macro expander, and write transformed tokens to the parser.

Currently we don't have a public API for the token stream interface. And we don't have a hook how a plugin might get included in that chain, wrapping the macro expander in its own object. But both of these might be very desirable to have. Should we add them, @xymostech?

[edemaine]

@mhchem FWIW, KaTeX currently supports \phantom and \llap (not sure exactly when they were added). \vphantom and \smash might be possible, though in general KaTeX isn't an expert at vertical mode, so it'd help to see an example of what you need.

@gagern Maybe we could extend function support to specify that an argument should be parsed and the parse tree gets passed into the function, to do with what you will? (This is similar to \expandafter, which I assume is how \ce is implemented in LaTeX.)

[ronkok]

Current Status:

| Item | Status in KaTeX |
|:-----------------------------------|:-----------------------------------------------------------------------------|
| Plugin architecture | KaTeX exposes __defineMacro(). It turns out that __defineMacro() is sufficiently powerful to enable an mhchem extension. |
| mhchem module | released as part of KaTeX v0.10.1. Yay! |
| \raise.1em
\lower7mu | \raisebox{0.1em} is supported. |
| \mskip2mu
\mkern3mu | Supported. |
| \smash
\hphantom
\vphantom | Supported |
| \llap \rlap | Supported. \mathllap and \mathrlap fit better. |
| \xrightarrow
\xleftarrow
\xleftrightarrow
\xrightleftharpoons | Supported |
| \xrightleftarrows
\xrightequilibrium
\xleftequilibrium | Supported. |
| ^{\circ} | Both ^{\circ} and \degree are supported. |
| \mathchoice | Supported |
| Upright Greek letters | Incomplete. Issue #564.

[mhchem]

Great to see this advancing.
Yes, of course, I can do the mhchem module. Ping me once you have an empty plugin that I can fill with code.
\color will be removed. That is part of experimental, undocumented code. I don't know where you saw \Rule. \hline is not needed by the package. It is in the code just to pass through, in case people make use of \ce inside table-like environments.

[ronkok]

@mhchem Thank you for your comment. I'll remove \color, \Rule, and \hline from the status table in my earlier comment.

[kevinbarabash]

@mhchem we don't have a plugin architecture yet. LaTeX functions are defined in src/functions, e.g. https://github.com/Khan/KaTeX/blob/master/src/functions/lap.js. Usually we only have a single call to defineFunction per file in src/functions, but a person could have more if that makes sense for implementing mhchem. The thought was eventually we'd expose the defineFunction command so that people could extend KaTeX without having to update KaTeX itself.

[sidvenu]

@mhchem Could you please tell me what is the status of the extension? And if it is not yet completed, could you please tell me when you will complete it approximately?

[mhchem]

@sidvenu As an active GitHub user, you should know that an open issue means "not completed yet". Also, please take a minute to read the last messages on this page. You'll see that there is no plugin architecture yet. So I cannot make any estimation.

[danielhollas]

I think this can be closed, mhchem is now supported in the new 0.10.1 release. :-)

[ronkok]

@danielhollas. Agreed. Yay!