Handle Math_span and Math_block constructs#886
Handle Math_span and Math_block constructs#886jonludlam merged 1 commit intoocaml:masterfrom gpetiot:katex-support-2
Conversation
|
Looking good so far! I think there are a few things we still need to do on this:
|
|
I've released odoc-parser 2.0.0 with math support, so the CI should be a little happier now! |
Julow
left a comment
There was a problem hiding this comment.
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.ttfThere 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\xiI 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
left a comment
There was a problem hiding this comment.
-
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 ?
Based on https://katex.org/docs/font.html I would be more tempted to only keep the |
Just keep the |
|
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 % \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\xithen it renders as it does on the katex home page. |
|
PR lgtm (although I'm not an odoc expert at all). Curious @jonludlam why are you unhappy with out-of-band macros? |
Let's just say I'm happy not to have to support this until we've got an extremely compelling use case :-) |
|
I think that's fair yes :) |
|
I think this is good now, thanks! |
CHANGES: Additions - New unstable option `--as-json` for the HTML renderer that emits HTML fragments (preamble, content) together with metadata (table of contents, breadcrumbs, whether katex is used) in JSON format. (@sabine, ocaml/odoc#908) - New maths support via `{m ... }` and `{math ... }` tags. (@giltho, @gpetiot, ocaml/odoc#886) - Various optimisations (@jonludlam, ocaml/odoc#870, ocaml/odoc#883) - Better handling of alerts and deprecation notices. (@panglesd, ocaml/odoc#828) - Handle language tags on code blocks (@Julow, ocaml/odoc#848) Bugfixes - Shadowing issues (@jonludlam, ocaml/odoc#853) - Layout fixes and improvements (@panglesd, ocaml/odoc#832, ocaml/odoc#839, ocaml/odoc#847) - Handle comments on class constraints and inherit (@Julow, ocaml/odoc#844) - Disable the missing root warning (@jonludlam, ocaml/odoc#881)
This PR is based on #811 (I don't have the rights to push to it)
mainbranch ofodoc-parserto handleMath_spanandMath_block