search

sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.49k stars 2.11k forks source link

MathML default output for Math #6092

Open ocket8888 opened 5 years ago

ocket8888 commented 5 years ago

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 commented 5 years ago

+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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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

ocket8888 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

Good to know!

NeroBurner commented 4 years ago

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

gmilde commented 2 years ago

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

Docutils' latex2mathml.py got a major upgrade in version 0.18. See https://docutils.sourceforge.io/docs/ref/rst/mathematics.html for supported LaTeX constructs (this link shows rendering with the HTML+CSS math output format provided by Docutils as an alternative) and https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/test/functional/expected/math_output_mathml.html (a shorter example compiled with the "--math-output=mathml" setting).

It is still provisional/in active development and there are plans to move the math format conversion to a transform in Docutils 1.0.

bertini97 commented 1 year ago

Chrome is planned to support mathML soon: https://chromestatus.com/feature/5240822173794304

BenjaminAster commented 1 year ago

@bertini97 Chromium actually already supports MathML, so all modern browsers support it now! With the help of tools such as latex2mathml or LaTeXML I guess it should be possible to implement a sphinx.ext.mathml extension for MathML output in Sphinx. Note that Chromium only supports MathML Core, a subset of MathML that should be enough for most MathML use cases. cc @TimKam

gmilde commented 1 year ago

Docutils supports MathML with its own latexmath2mathml module since 'ages'.

Just set 'math-output=mathml' in the config file: https://docutils.sourceforge.io/docs/user/config.html#math-output

Unless the "math" implementation is overwritten by Sphinx, this should work out of the box. sphinx-doc/sphinx