Math formulas in odoc comment blocks

Trying to write math formulas in my comments without success :

(** {m \forall k in [0;n], 0 <= i_k < n_k} *)

as explained in odoc documentation but it does not render properly :

\forall k in [0;n-1], 0 <= i_k < n_k 

katex javascript lib seems missing :

PS H:\OCaml\GenArrayIter\_build\default> tree /F _doc
H:\OCAML\GENARRAYITER\_BUILD\DEFAULT\_DOC
├───_html
│   │   highlight.pack.js
│   │   index.html
│   │   odoc.css
│   │
│   ├───fonts
│   │       KaTeX_AMS-Regular.woff2
│   │       KaTeX_Caligraphic-Bold.woff2
│   │       KaTeX_Caligraphic-Regular.woff2
│   │       KaTeX_Fraktur-Bold.woff2
│   │       KaTeX_Fraktur-Regular.woff2
│   │       KaTeX_Main-Bold.woff2
│   │       KaTeX_Main-BoldItalic.woff2
│   │       KaTeX_Main-Italic.woff2
│   │       KaTeX_Main-Regular.woff2
│   │       KaTeX_Math-BoldItalic.woff2
│   │       KaTeX_Math-Italic.woff2
│   │       KaTeX_SansSerif-Bold.woff2
│   │       KaTeX_SansSerif-Italic.woff2
│   │       KaTeX_SansSerif-Regular.woff2
│   │       KaTeX_Script-Regular.woff2
│   │       KaTeX_Size1-Regular.woff2
│   │       KaTeX_Size2-Regular.woff2
│   │       KaTeX_Size3-Regular.woff2
│   │       KaTeX_Size4-Regular.woff2
│   │       KaTeX_Typewriter-Regular.woff2
│   │
│   └───GenArrayIter
│       │   index.html
│       │
│       └───GenArrayIter
│           │   .dummy
│           │   index.html
│           │
│           └───Iter
│                   index.html
│
├───_mlds
│   └───GenArrayIter
│           index.mld
│
├───_odoc
│   └───pkg
│       └───GenArrayIter
│               page-index.odoc
│
└───_odocls
    └───GenArrayIter
            genArrayIter.odocl
            page-index.odocl
1 Like

Can you run the following:

$ odoc --version

and

$ odoc support-files -o __test
$ tree __test

and report the output?

The first command to know the version of odoc you are using, the second one is the command (usually called by dune) to generate the support files (in this case in the __test directory), which should normally include katex.min.js.
You can remove the __test directory after that!

Could you also confirm that the file that should render the math includes the (missing apparently) katex lib? For instance, for me:

$ grep katex _build/default/_doc/_html/test_m/Test_m/index.html   
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Test_m (test_m.Test_m)</title><meta charset="utf-8"/><link rel="stylesheet" href="../../odoc.support/odoc.css"/><meta name="generator" content="odoc %%VERSION%%"/><meta name="viewport" content="width=device-width,initial-scale=1.0"/><script src="../../odoc.support/highlight.pack.js"></script><script>hljs.initHighlightingOnLoad();</script><link rel="stylesheet" href="../../odoc.support/katex.min.css"/><script src="../../odoc.support/katex.min.js"></script><script>
            var elements = Array.from(document.getElementsByClassName("odoc-katex-math"));
              new_el.setAttribute("class", "odoc-katex-math-rendered");
              katex.render(content, new_el, { throwOnError: false, displayMode: display });
</script></head><body class="odoc"><nav class="odoc-nav"><a href="../index.html">Up</a> – <a href="../index.html">test_m</a> &#x00BB; Test_m</nav><header class="odoc-preamble"><h1>Module <code><span>Test_m</span></code></h1><p><code class="odoc-katex-math">\forall k \in [0;n], 0 \leq i_k &lt; n_k</code></p></header><div class="odoc-content"></div></body></html>

Hello @panglesd

Sorry for the delay. I have odoc version 2.2.0 and for your test, please find the results below. I must say that I run all of this on a windows box (Diskml distrib) which has had some tricks with odoc…:

PS H:\OCaml\GenArrayIter> tree /F __TEST
Structure du dossier pour le volume Corsair 2
Le numéro de série du volume est 000000FF 0634:1600
H:\OCAML\GENARRAYITER\__TEST
│   highlight.pack.js
│   katex.min.css
│   katex.min.js
│   odoc.css
│
└───fonts
        KaTeX_AMS-Regular.woff2
        KaTeX_Caligraphic-Regular.woff2
        KaTeX_Fraktur-Bold.woff2
        KaTeX_Fraktur-Regular.woff2
        KaTeX_Main-Bold.woff2
        KaTeX_Main-BoldItalic.woff2
        KaTeX_Main-Italic.woff2
        KaTeX_Main-Regular.woff2
        KaTeX_Math-BoldItalic.woff2
        KaTeX_Math-Italic.woff2
        KaTeX_SansSerif-Bold.woff2
        KaTeX_SansSerif-Italic.woff2
        KaTeX_SansSerif-Regular.woff2
        KaTeX_Script-Regular.woff2
        KaTeX_Size1-Regular.woff2
        KaTeX_Size2-Regular.woff2
        KaTeX_Size3-Regular.woff2
        KaTeX_Size4-Regular.woff2
        KaTeX_Typewriter-Regular.woff2

PS H:\OCaml\GenArrayIter> odoc --version
2.2.0

As for the file presumably missing katex lib, here is the content of the HTML header supposed to render the formulas :

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">

<head>
  <title>Iter (GenArrayIter.GenArrayIter.Iter)</title>
  <link rel="stylesheet" href="../../../odoc.css" />
  <meta charset="utf-8" />
  <meta name="generator" content="odoc 2.2.0" />
  <meta name="viewport" content="width=device-width,initial-scale=1.0" />
  <script src="../../../highlight.pack.js"></script>
  <script>hljs.initHighlightingOnLoad();</script>
  <link rel="stylesheet" href="../../../katex.min.css" />
  <script src="../../../katex.min.js"></script>
  <script>
    //<![CDATA[

    document.addEventListener("DOMContentLoaded", function () {
      var elements = Array.from(document.getElementsByClassName("odoc-katex-math"));
      for (var i = 0; i < elements.length; i++) {
        var el = elements[i];
        var content = el.textContent;
        var new_el = document.createElement("span");
        new_el.setAttribute("class", "odoc-katex-math-rendered");
        var display = el.classList.contains("display");
        katex.render(content, new_el, { throwOnError: false, displayMode: display });
        el.replaceWith(new_el);
      }
    });

    //]]>
  </script>
</head>

<body class="odoc">
  <nav class="odoc-nav"><a href="../index.html">Up</a> – <a href="../../index.html">GenArrayIter</a> &#x00BB; <a
      href="../index.html">GenArrayIter</a> &#x00BB; Iter</nav>
  <header class="odoc-preamble">
    <h1>Module <code><span>GenArrayIter.Iter</span></code></h1>
  </header>
  <div class="odoc-content">
    <div class="odoc-spec">
      <div class="spec value anchored" id="val-incr"><a href="#val-incr"
          class="anchor"></a><code><span><span class="keyword">val</span> incr : <span><span>int array</span> <span class="arrow">&#45;&gt;</span></span> <span><span>int array</span> <span class="arrow">&#45;&gt;</span></span> bool</span></code>
      </div>
      <div class="spec-doc">
        <p>Given an index <code class="odoc-katex-math">i(i_0,i_1, ..., i_{n-1})</code> of dimension dims(d_0, d_1, ...,
          d_<code>n-1</code>) such that ∀ k in [0;n-1] 0 &lt;= i_k &lt; n_k, the function increment the index
          <code>i</code> according to the following recursive algorithm:</p>
// cut

That is very strange: the odoc support-files command does create the katex.min.js and katex.min.css files, but it seems they are not present when the command is called by dune

Since this is a Diskuv distrib, maybe this is due to some trick you mentioned? Any insight @jbeckford?

Also, which version of dune do you have? It seems, from what I understand from this PR, that dune below 3.7 won’t support math?

Yes I think that this version of dune will not build these support assets.

dune 3.6.2 … too bad then.

A workaround is to copy katex.min.js and katex.min.css “by hand” alongside the odoc.css file (eg by running the odoc support-files -o _build/default/_doc/_html command yourself).

It is only a partial workaround. It did work, but each time I change the source file, the documentation is not/wrongly updated. So the issue is more profond than just a file which is not copied at the right place in my opinion.

In summary, the issue is with Diskuv’s old version of dune, right?

that’s my assesment. I believe that a new version of diskuv is being prepared with dune 3.15.

The latest DkML 2.1.0 should be fine; follow the upgrading instructions at DkML 2.1.0 · DkML / Distributions / DkML · GitLab.

If you have problems upgrading please file an issue.

2 Likes

You could also try embedding MathML inside the odoc comment: Is it possible to include inline html in ocaml documentation (odoc)? - #2 by patricoferris

EDIT: here’s a tool which converts LaTeX markup to MathML: Temml - Convert TeX to MathML