rust-lang/rust — pull request #17390 by huonw (2014-09-19 12:56:48+00:00)
Title: Add mathematics support to rustdoc

Revival of #16991, fixes #16300.

This uses the new support in hoedown for parsing mathematics. Current supported delimiters are `\\( ... \\)` (text), `\\[ ... \\]` (display), `$$...$$` (inferred). Hoedown currently requires that the first two have spaces between the delimiters and the mathematics, and that all of them have space after the delimiters (https://github.com/hoedown/hoedown/issues/120).

[The KaTeX library](https://github.com/Khan/KaTeX) is packaged without modifications with the distribution, so this should work without an internet connection. It consists of ~150 KB of JS/CSS and nearly 850 KB of fonts, the latter can be cut to 200KB if we only include the WOFF files (i.e. remove the EOT and TTF ones). This would require editing the files slightly. KaTeX does not have nearly the same support as MathJax, but it is significantly faster and smaller (it would not be nearly as reasonable to package MathJax).

This also uses this support in a few selected places in the standard libraries.

General comments:

- inlined documentation with mathematics requires a `enable_math` on the crates in which it is inlined for the maths to be rendered
- I added basic support for standalone markdown files, but I'm not sure if we want that in this iteration. Standalone markdown files currently include nothing else by default, and this is inserting JS and CSS. Furthermore, this requires but doesn't enforce that a katex installation exists as a sibling of the rendered file (which is true if the markdown file is rendered into a directory with other crates, e.g. like the main docs).
- I'm a sick at the moment, so the code could be nonsense.
- I am preserving @Gankro's work; if they're ok with it, I will compress the history.