Index of Experiments
Design

We'll convert odoc HTML into reStructuredText (rST), and then from rST back to HTML.

Basically: Odoc.html mli |> Pandoc.rst |> Pandoc.html

Typically we may just stop at reStructuredText since reStructuredText is the content format used by the (hugely) popular Sphinx documentation tool. reStructuredText is also the typical content format for Read the Docs which is in use by 80,000 open source projects.

Converting again to HTML lets us visually inspect how much information has disappeared in the conversion to reStructuredText using pandoc.

With native odoc support for reStructuredText (see Issue #890) there should be no lossiness.

Results
markup.mli
test the Experiment Design rendering of comment markup in a .mli file. Compare to the original (100-plain) rendering
Conclusion

Using pandoc to produce reStructuredText results in poor rendering.

  1. The header level structure (ex. {1 Section} vs {2 Subsection}) is lost
  2. The implicit and explicit anchors for each title (ex. {2 Subsection} appears in the reStructuredText results. They should be invisible.
  3. Several types of links do not render as links
  4. Raw HTML is lost completely