Html rendering of the manual
Currently the only way to consult the Menhir manual is the PDF. It is a nice manual, whenever I want to look at it in depth I find the format appropriate, but most of the time it is actually fairly inconvenient:
- Opening another browser/viewer (or running the horrible in-browser PDF viewers) disrupts my flow.
- I find looking for things in the manual or quickly glancing through it less convenient than for HTML.
- I cannot refer other people to specific parts of the manual with a URL, I have to give a section number, and it is inconvenient for them to navigate there.
As part of the May OCaml DocJam, I decided to work on producing a HTML version of the Menhir manual.
The Menhir manual is written in LaTeX. I evaluated several LaTeX-to-HTML producers (pandoc, which just crashes on some unicode character it doesn't like for some reason, latex2html, which produces terrible output, and tex4ht which doesn't even produce valid HTML), and Hevea was by far the best option. With only moderate tweaking, I could get the manual to build, and with some more tweaking I got a result that actually looks quite decent (maybe not quite as good as the PDF version, but something I'm not ashamed of) -- I reused bits of the trunk ocaml-manual style files which are a good start.
I uploaded a live preview: menhir-manual/main.html. It is one HTML file, plus one PNG picture for each
tikzpicture in the document (that is, three, all representing derivation trees). See the Why shifting is legal subsection for an example of embedded picture.
The only change to the LaTeX that might affect the rendering of the PDF version is the move from
\hspace. I'm no TeX expert, but my understanding is that
\hskip is a low-level TeX command with some magic behavior in some corner cases (when it is already surrounded by space) that Hevea doesn't support, while
\hspace is the recommend LaTeX-alternative. I couldn't observe any difference in the rendering, but someone might want to compare the places that changed (see 6a51ce74).
The other changes are
.hva versions of
.sty files to make the build work, importing Hevea's
hevea.sty file that defines, on the
pdflatex side, some hevea-specific macros as no-ops, and using those hevea-specific macros to build the Tikz pictures as separate PNG files when used from Hevea -- hevea's trick for this which works surprisingly well.
I added a
main.html target in
doc/Makefile, but no other integration in the overall build system and installation pipeline. I thought that @fpottier, if interested in the patch, would know better than me how to proceed with this. I think it would be very nice if a HTML version of the manual was hosted on the website, with the link given alongside the PDF link for the documentation.