Add Mathjax (KaTeX?) Support to Rustdoc

[Gankra]

$[stuff]$ in markdown should be interpreted by mathjax on the client-side to get pretty maths. NoScript fallback plan for the moment is to simply allow the raw latex to display. Having server-side generated images for fallback would involve substantial dependencies.

[steveklabnik]

This would also fix #15285

[Gankra]

Presumably since rustdoc is expected to work locally, we can't just use Mathjax's recommended process of just requesting the files from their CDN.

Holy shit mathjax is a 30,000 file 60MB monstrosity. Let's see what we can hack off here...

[Gankra]

I'm gonna go ahead and make the call that correct local rendering in Firefox is not worth including, quote, "29,000 files and 12.5MB" of png fonts.

[Gankra]

Okay so I sliced Mathjax down to 400 files clocking in at 2MB. There could be more to cut out, like all their context-menu localization stuff, but I'm rubbing up against some limits. It's a hardcore asynchronous library with a ton of modules that I lack a dependency graph for. Shouldn't (can't) be min-concated together, since it seems to lean pretty heavily on directory structure.

Still, this magnitude of a dependency is spooking some people. MathJax's docs actually pretty aggressively push "Just link to our CDN", which would make this literally like, a 2-line change to Rustdoc (pull in the file, configure the latex delimeters). It fails gracefully enough in the sense that you just end up with a bunch of raw latex, which IMO is pretty legible most of the time, e.g. $O(n^2)$. This failstate would happen anyway with noscript.

Is depending on an external CDN to fully render parts of the docs (on the client-side) acceptable, or is that a non-starter?

CC @cmr Any opinion?

[emberian]

I think depending on a CDN is fine.

On Wed, Aug 6, 2014 at 8:52 PM, Alexis Beingessner <notifications@github.com

wrote:

Okay so I sliced Mathjax down to 400 files clocking in at 2MB. There could
be more to cut out, like all their context-menu localization stuff, but I'm
rubbing up against some limits. It's a hardcore asynchronous library with a
ton of modules that I lack a dependency graph for. Shouldn't (can't) be
min-concated together, since it seems to lean pretty heavily on directory
structure.

Still, this magnitude of a dependency is spooking some people. MathJax's
docs actually pretty aggressively push "Just link to our CDN", which would
make this literally like, a 2-line change to Rustdoc (pull in the file,
configure the latex delimeters). It fails gracefully enough in the sense
that you just end up with a bunch of raw latex, which IMO is pretty legible
most of the time, e.g. $O(n^2)$. This failstate would happen anyway with
noscript.

Is depending on an external CDN to fully render parts of the docs (on the
client-side) acceptable, or is that a non-starter?

CC @cmr https://github.com/cmr Any opinion?

—
Reply to this email directly or view it on GitHub
#16300 (comment).

http://octayn.net/

[steveklabnik]

For something this non-essential, I agree.

[adrientetar]

How much math do we have?

[killercup]

(First off, I don't care about loading Mathjax from a CDN, so just ignore me if Mathjax is what you want.)

Some time ago I came across a small JS library that could convert some TeX math to unicode and HTML (depending on just a font IIRC), but I can't remember the name. Something like that might solve 99% of all cases of math in rust docs.

[huonw]

General remarks:

• I think we would need special handling for $...$ segments since they should effectively be a verbatim environment like ..., that is, $x < a, y > b$ should not be turned into an HTML <a> tag. AFAICT, hoedown doesn't support this natively (although presumably it would be able to be hacked in by just handling $ as a synonym for a backtick, with the appropriate matching). Also, I think this implies that this is required to be (somewhat) built-in to rustdoc; just inserting the mathjax JS into each page via --html-after-content won't work fully (i.e. @adrientetar's question applies to all libraries that wish to use rustdoc, e.g. scientific ones, physics/gamedev ones).
• if we were doing this, it would be nice to ensure we have display math support too (example where it would be nice).
• on that note, LaTeX-style delimiters \(...\) (inline) and \[...\] (display) are better matched than TeX $...$ and $$...$$ (and avoid the problem of people casually writing a $ for money)
• we should do something purposefully for instances of $...$ in the comments in code blocks (i.e. make some explicit decision about how to handle it, I don't care much); $ outside comments would need to be excluded from MathJaX (since it's an important part of macros).

[Gankra]

@huonw thanks for the detailed response!

• You're probably right that we'll need special handling on the server side. I didn't get very far last night due to weird compilation caching issues, so I didn't get a chance to run into that. Good catch.
• MathJax also supports display math. Their defaults are \(...\) for inline and both \[...\] and $$...$$ for display mode. I had opted to override this to $$...$$ for inline and \[...\] for display ($...$, as you note would be a nightmare with Rust's current grammar, and I guess financial references). I picked those because the match closely to the LaTeX I've seen, but am fine with your suggestion. I basically just like $$ because it's easy to type and looks less noisy than \(...\) to me, which seems desirable for an in-line notation.
• With either of our proposed settings, I don't think individual $'s need to be addressed. As far as I can tell, you wouldn't reasonably end up with $$ appearing in any code outside of a string literal. Maybe a weird regex or something...?

[huonw]

hoedown/hoedown#114 "MathJax support, second attempt"

[Gankra]

:O

!!!

I'm not sure what our policy on dependencies is. Can we depend on this snapshot of master, or should we wait for a stable release?

[alexcrichton]

It's ok to depend on non-master versions of dependencies, we already do it all the time for libuv and llvm anyway!