New-format User Guide in cylc-7.8.1

[Hilary Oliver]

Hi all,

In cylc-7.8.1 we say a fond farewell to the LaTeX document mark-up language, which we've used since the beginning of the Cylc project to generate the User Guide in the PDF and HTML formats.

The User Guide (which includes the formerly-separate Suite Design Guide) is now generated by Sphinx

• https://cylc.github.io/cylc/doc/built-sphinx/index.html
• (This direct URL may change in the near future)
• Note the search interface
  
• You can generate one locally with "cylc make-docs"
• Other formats and improvements to come later
  

Finally, as a long-time LaTeX fan I'd like to point out that this change was largely about getting good HTML copy, which is appropriate for a software user guide in the modern world. If you are writing a book or an article for hard copy, particularly one with any math in it, LaTeX (a set of easy-to-use macros for the typesetting system TeX, created by the great computer scientist Donald Knuth) still blows everything else out of the water. Unfortunately though, it seems no one has come up with a decent TeX-to-HTML converter (much of the  problem is just ugly stylesheets and thus fixable, but an expert once suggested to me that proper typesetting is not really compatible with variable-width web pages).

From a recent New York Times article on Donald Knuth:

"Horrified by what his beloved book looked like on the page with the advent of digital publishing, Dr. Knuth had gone on a mission to create the TeX computer typesetting system, which remains the gold standard for all forms of scientific communication and publication. Some consider it Dr. Knuth’s greatest contribution to the world, and the greatest contribution to typography since Gutenberg."

So: long live TeX!  (But not in the Cylc User Guide!).

Hilary