Document examples of math rendering use cases

[asmaier]

MathJax can render mathematical formulas directly from LaTeX (see http://docs.mathjax.org/en/latest/tex.html). So in principle it would not be necessary for Latexml to render mathematical formulas from LaTeX to MathML. Instead Latexml could simply hand them over to the output HTML and let MathJax do the rendering of the mathematical formulas.
For that Latexml would need an option to skip the rendering of mathematical formulas. This could also speed up the processing of LaTeX files by Latexml considerably.

[dginev]

Thanks for the request, and I am happy to say we have (most) of that! Latexml has been used in production with a follow-up mathjax/katex render for some time now at Authorea, so it is definitely workable.

For not parsing math specifically, all you need is adding --nomathparse to the invocation, and the formulas will be left unparsed. To make them available to mahtjax directly you may still need to do some post-processing to fish out the original TeX of the formulas from the HTML, as latexml isn't optimized for passing tex to mathjax.

Instead, what we have optimized for, is using MathJaX on the parsed MathML, which can - especially for documents with complex macros in formulas - be a lot more robust. For that we have the maybeMathjax.js script which you can use by adding to latexmlpost --javascript=LaTeXML-maybeMathJax.js and leaving everything else with the usual HTML output (which generates presentation MathML).

And lastly, you can also generate SVG mathematics from latexml directly via --mathsvg , which recently got through a production test as well, see #883 for details.

Writing this, I feel like we are missing a dedicated Wiki page (or manual page?) on math rendering scenarios, since this information looks like the type of concern that will be frequently asked by users. Tagging the issue as a "documentation enhancement" for that part.

Maybe it would be optimal to add a list of 5-6 common formula workflows and examples how to enable each of them? I can contribute some/all of that if agreeable cc @brucemiller

[brucemiller]

That'd be a good idea. Originally, I'd intended to have more of that in the manual. I don't know if it's the nature of the beast or just Perl infection, but once I get into There's More Than One Way To Do It mode, the readability of my prose takes a nose dive! Probably the wiki'd be a better place to catalog the various options.

[dginev]

I hear you. My experience is that especially for new-comers, or casual users that are exploring a new usage scenario, the key enhancer are examples of both the specific invocations, and the expected output / use case. Really helps to get one's foot in the door, and can be a lot more convenient than reading through the full option set, 90% of which won't be needed for casual use.

The pandoc demo page may be a minimal skeleton to borrow, though I would also add brief descriptions for some of the more advanced usages (e.g. the math output varieties)

[dginev]

I have started a sample Demos page in the Wiki, and am running low on ideas for invocations.

Feel free to improve on it, and to close the issue if it seems like a good start that covers our current discussion.

[dginev]

Please reopen if more is required, and/or give suggestions for extending the Wiki page. Obviously latexml can do a lot more, so the Demo page is only to grow further!