[Haskell-cafe] [ANNOUNCE] Glasgow Haskell Compiler version 7.10.3

[Ben Gamari]

Joachim Durchholz <jo at durchholz.org> writes:

> 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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 472 bytes
Desc: not available
URL: <http://mail.haskell.org/pipermail/haskell-cafe/attachments/20151210/f792bbed/attachment.sig>