GitLab

Andreas and I had a discussion and mail exchange about the manual format. As a background, in my previous job I worked on a project where we converted our LaTeX manual (http://www.pp.rhul.ac.uk/bdsim/manual/). Posting some of the findings here for discussion.

Since the OPAL manual is quite extensive it will be quite some work to do it all by hand, so I did a search for a LaTeX conversion tool. Since LaTeX can define macros and there are many possible packages this is definitely not an easy conversion, there are only few options. I think our best bet is pandoc (pandoc.org).

I gave it a try on an individual chapter with many equations converting it to markdown (opalt.md). However, the current PSI gitlab wiki does not seem to support LaTeX. The latest versions do support a fairly large subset (called KaTeX) though: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#math and https://github.com/Khan/KaTeX/wiki/Function-Support-in-KaTeX. Andreas has contacted the PSI gitlab contact person.

I also converted to ReStructured Text (opalt.rst), which can do maths and is used for the Python documentation online (sphinx-doc.org), and then to plain html without a fancy theme that can be easily added (opalt_rst.html). It doesn't run particularly well with quite a few warnings.. Still it did some equations correctly, so not hopeless either.

Then I fixed the simple error messages in around 5-10 minutes and the result is also attached (opalt_mod.rst and opalt_rst_mod.html). Figures are still missing (pdfs are not liked in html very much, so probably need to be converted) and some LaTeX macros are not seen (since I disabled header.tex and footer.tex), but these are issues that can be fixed.

I think this gives a sort of idea of what it could become and the work that is needed (I reckon 10-20 hours).