New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document examples of math rendering use cases #923

Closed
asmaier opened this Issue Jan 7, 2018 · 6 comments

Comments

Projects
None yet
3 participants
@asmaier

asmaier commented Jan 7, 2018

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

This comment has been minimized.

Collaborator

dginev commented Jan 7, 2018

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

@dginev dginev added this to the LaTeXML-0.8.4 milestone Jan 7, 2018

@brucemiller

This comment has been minimized.

Owner

brucemiller commented Jan 7, 2018

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

This comment has been minimized.

Collaborator

dginev commented Jan 8, 2018

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 dginev self-assigned this Jan 8, 2018

@dginev dginev changed the title from Offer an option to not render math to MathML to Document examples of math rendering use cases Feb 24, 2018

@dginev

This comment has been minimized.

Collaborator

dginev commented Feb 25, 2018

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

This comment has been minimized.

Collaborator

dginev commented Mar 1, 2018

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!

@dginev dginev closed this Mar 1, 2018

@brucemiller

This comment has been minimized.

Owner

brucemiller commented Mar 1, 2018

Or add your own interesting scenarios! :>

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment