Skip to content

Guidebook should not be written in LaTeX

Note: This issue is really low-importance. Do not continue reading if you care about your time.

The guidebook is currently written in LaTeX, with a primary focus on printing and much efforts put into aligning figures and styling texts. IMHO this is the wrong focus. Instead, the guidebook should focus on content, not on layout. It should be written in some simple markup language which allows rendering to a web page and a PDF similarly. This is useful for easier deep-linking and reading on screen. It also encourages a more uniform style accross the book.

There are several instances of such language. One very common in the Python world is Shinx, it is very widespread due to its simple syntax in Markdown. I recently stumbled over the Visit documentation which was rewritten with Sphinx and renders at the same time to a comprehensive website and a 400 page book/pdf with a table of contents, numbered images and all that. An example page is http://visit-sphinx-user-manual.readthedocs.io/en/latest/Quantitative/Expressions.html which is generated by the very readable restructuredtext source http://visit-sphinx-user-manual.readthedocs.io/en/latest/_sources/Quantitative/Expressions.rst.txt

Translating our current LaTeX guidebook to something like Restructuredtext or Markdown is a <1h job, therefore switching the publication system is not a mammoth task at all. It is more something people have to agree on. I wonder if Tobias will?