Sphinx: MathML default output for Math

[ocket8888]

From the docs:

_"Since mathematical notation isn’t natively supported by HTML in any way..."_

That's not _totally_ true. MathML is a part of the HTML5 spec, though browser support is spotty to say the least. Since the alternative without installing plugins is just math not working, maybe a good default would be to follow the spec for the output format?

[tk0miya]

+0; I'm not good at MathML. So I can't say anything about default. But it will become standard of web (in future).

[TimKam]

Considering the lack of MathML support in many browsers, I don't think it makes any sense to set a MathML builder as the default option now. It would be poor design from the side of Sphinx to have a default output option that doesn't work for most users (i.e. people using Google Chrome/Chromium). I suggest updating the docs no and keeping this issue for the time MathML support has made it to Chrome.

[ocket8888]

What kills me is that support _was_ in Chrom(ium) but they removed it, citing "security issues" iirc. Apparently as of 2019 there is a team working on slowly re-introducing the support, starting with a core set of features.

[TimKam]

Thanks for the info. I'll link to the official Chrome/Chromium trackers here:

• Issue in Chromium bug tracker: https://bugs.chromium.org/p/chromium/issues/detail?id=152430
• Chrome platform status: https://www.chromestatus.com/feature/5240822173794304

[ocket8888]

FWIW, the links you posted make mention of support in Firefox, Opera, Safari, and (skeptically) Edge. I know Google has a pretty huge market share, but according to Google itself most other big browsers have MathML support.

[tk0miya]

Either way, we have to implement MathML renderer. An extension like sphinx.ext.mathml is needed to add mathml support. I marked this as "help wanted". So it would be nice if somebody sends us a PR.

[ocket8888]

I like to consider myself pretty familiar with MathML itself. If I wasn't such trash at writing parsers, I'd offer to write it.

Unless that's not necessary? Is there any chance Sphinx already creates ASTs for :math: and .. math contents?

[tk0miya]

I like to consider myself pretty familiar with MathML itself. If I wasn't such trash at writing parsers, I'd offer to write it.

Of course yes!

Is there any chance Sphinx already creates ASTs for :math: and .. math contents?

No, it is not parsed. docutils' spec says:

The math_block element contains a block of text in LaTeX math format [1] that is typeset as mathematical notation (display formula). The math_block element is generated during the initial parse from a "math" directive.

So we have user input text in LaTeX math format simply. So we need to write a code for converting LaTeX to MathML.

[ocket8888]

That could be very hard/expensive. LaTeX lets you nest basically arbitrary content in a math block with things like \textnormal. I don't think you can do sectioning inside an equation, but afaik that's it. You can embed images or include external files, and most troublingly you can create and use your own macros. To be totally compliant with valid math block LaTeX, I think you'd need to implement a full LaTeX parser.

It'd be easier to support a limited subset like KaTeX, or to allow multiple representations of a single equation based on output type. Of course, that limits the kinds of complex things people sometimes do with math blocks. IMO they shouldn't be done in an equation, but it would be a breaking change.

For my money, I think maybe it'd be better/easier to make a MathML parser - since it's a far simpler language - and translate that into LaTeX equations at build time for LaTeX output. That's a major, breaking change to the directive/role so idk if that's preferable to implementing a LaTeX parser.

[mitya57]

So we need to write a code for converting LaTeX to MathML.

Docutils already contains some kind of a converter, however I am not sure how complete it is.

[tk0miya]

Good to know!

[NeroBurner]

related python project: https://github.com/roniemartinez/latex2mathml