Handle Math_span and Math_block constructs

[gpetiot]

This PR is based on #811 (I don't have the rights to push to it)

• rebased on top of main branch of odoc-parser to handle Math_span and Math_block
• vendored the katex files similarly to what is done for highlight.js (no need to check for the integrity of the files once they are vendored)

[jonludlam]

Looking good so far! I think there are a few things we still need to do on this:

1. We need some tests
2. I think we're missing the fonts in the vendored files
3. There's no distinction between display and inline maths
4. It'd be nice to only add the scripts to the html if the page actually contains some math content.

[jonludlam]

I've released odoc-parser 2.0.0 with math support, so the CI should be a little happier now!

[Julow]

Nice! Some comments:

• Katex complains with

  downloadable font: download failed (font-family: "KaTeX_Size1" style:normal weight:400 stretch:100 src index:0): status=2152857618 source: file:///home/juloo/w/odoc/test/generators/html/fonts/KaTeX_Size1-Regular.woff2
  downloadable font: download failed (font-family: "KaTeX_Main" style:normal weight:400 stretch:100 src index:0): status=2152857618 source: file:///home/juloo/w/odoc/test/generators/html/fonts/KaTeX_Main-Regular.woff2
  downloadable font: download failed (font-family: "KaTeX_Size1" style:normal weight:400 stretch:100 src index:1): status=2152857618 source: file:///home/juloo/w/odoc/test/generators/html/fonts/KaTeX_Size1-Regular.woff
  downloadable font: download failed (font-family: "KaTeX_Main" style:normal weight:400 stretch:100 src index:1): status=2152857618 source: file:///home/juloo/w/odoc/test/generators/html/fonts/KaTeX_Main-Regular.woff
  downloadable font: download failed (font-family: "KaTeX_Size1" style:normal weight:400 stretch:100 src index:2): status=2152857618 source: file:///home/juloo/w/odoc/test/generators/html/fonts/KaTeX_Size1-Regular.ttf
  downloadable font: download failed (font-family: "KaTeX_Main" style:normal weight:400 stretch:100 src index:2): status=2152857618 source: file:///home/juloo/w/odoc/test/generators/html/fonts/KaTeX_Main-Regular.ttf 
  

  There should be a way to specify a font family to use/not use. Otherwise, we'll need to vendor it too.

• Create symlinks inside the generator tests output directory, to be able to open the browser on the test results:

  ln -s ../../../src/vendor/katex.min.css test/generators/html/katex.min.css
  ln -s ../../../src/vendor/katex.min.js test/generators/html/katex.min.js
  

• When a block doesn't render (for whatever reason), the result is unreadable. The example in the tests renders to this:

  % \f is defined as #1f(#2) using the macro \f\relax{x} = \int_{-\infty}^\infty \f\hat\xi\,e^{2 \pi i \xi x} \,d\xi
  

  I suggest wrapping math in a <code> element until they are rendered.

• In the test, the second math element doesn't render, perhaps due to the font issue ?

[Julow]

• When a block fails to render, the result is still a mess. Intermediate elements should be <code> for inline elements and <pre> for blocks instead of <span> for both currently.

• Are all these font files necessary ? Can we get away with shipping just the .ttfs or fetching them from the internet ?

[gpetiot]

• Are all these font files necessary ? Can we get away with shipping just the .ttfs or fetching them from the internet ?

Based on https://katex.org/docs/font.html I would be more tempted to only keep the .woff files (and they're smaller than ttf).

[dbuenzli]

Based on https://katex.org/docs/font.html I would be more tempted to only keep the .woff files (and they're smaller than ttf).

Just keep the .woff2 fonts, browser support is widespread enough.

[jonludlam]

The block math example is a bit broken - in the original katex example it relies on a macro declared as an option to the katex renderer (which can be seen by clicking the cog in the example):

{
    "\\f": "#1f(#2)"
}

Since I don't think we want a way to provide out-of-band macros like this we could just use \newcommand which appears to be supported - so the example becomes:

% \f is defined as #1f(#2) using the macro
\newcommand{\f}[2]{#1f(#2)}
\f\relax{x} = \int_{-\infty}^\infty
\f\hat\xi\,e^{2 \pi i \xi x}
\,d\xi

then it renders as it does on the katex home page.

[giltho]

PR lgtm (although I'm not an odoc expert at all).
Thank you so much for taking over my half-baked work!

Curious @jonludlam why are you unhappy with out-of-band macros?
I'd actually be happy to be able to provide a macro file on the side, in whichever format, which would be injected everywhere

[jonludlam]

Curious @jonludlam why are you unhappy with out-of-band macros? I'd actually be happy to be able to provide a macro file on the side, in whichever format, which would be injected everywhere

Let's just say I'm happy not to have to support this until we've got an extremely compelling use case :-)

[giltho]

I think that's fair yes :)

[jonludlam]

I think this is good now, thanks!