Joachim Durchholz
Am 10.12.2015 um 09:26 schrieb Ben Gamari:
We have moved the users guide to ReStructuredText, which is built with Sphinx. I'm quite pleased with how the transition has gone.
Heh. I can imagine; Sphinx seems to be the doc toolchain tool du jour, I was just curious about the reasons and how the differences work out.
I wrote up a brief description of the motivations and the options we evaluated on the Wiki [1]. In short, I found there weren't too many options which had flexible enough markup, could scale to something the size of the Users Guide, and didn't impose onerous dependencies. Ultimately the two realistic options were asciidoc and ReST. While an initial poll of ghc-devs found a slight preference for asciidoc, my preliminary attempts to port the users guide quickly encountered resistance from asciidoc's syntax. In short, asciidoc constructs just don't compose very well: while all lightweight markup languages have their limitations, I found that I ran into asciidoc's very quickly, particularly when nesting block items (e.g. a code block inside a list item). Due to how asciidoc's continuation syntax works I found that the local structure of the document would have wide-spread effects on how the rest of the document would need to be marked-up. After seeing asciidoc fail so badly, I was reluctant to even try ReST, assuming it would meet a similar fate. Thankfully I decided to try running a couple chapters through Pandoc and was pleasantly surprised by the output. While Pandoc's output wasn't perfect (e.g. there is no support of index terms), it was obvious that ReST was capable of conveniently representing most of the document and did not exhibit the same syntactic papercuts I saw with Asciidoc. In the end I was able to modify Pandoc to mechanically produce reasonable ReST output for the majority of the user's guide. ReST does have its limitations however and we ended up sacrificing in some areas in the name of more readable markup. Most notably, inline objects cannot be nested in ReST. This means that constructions like, <screen> :module <optional>+|-</optional> <optional>*</optional><replaceable>mod<subscript>1</subscript></replaceable> ... <optional>*</optional><replaceable>mod<subscript>n</subscript></replaceable> </screen> become impossible to express. In the end I settled for an approximation representing <replacable> tags with ⟨ ⟩ symbols. Anyways, on the whole I think the trade-off was well worthwhile. The syntax is substantially more readable, the output is more appealing, and the tooling is orders of magnitude better. Cheers, - Ben [1] https://ghc.haskell.org/trac/ghc/wiki/UsersGuide/MoveFromDocBook