[RFC] Moving user's guide to ReStructuredText
ben at well-typed.com
Wed Sep 23 08:02:56 UTC 2015
Last year there was a brief thread  on this list discussing the
choice of markup language used for GHC's users guide. At this point
DocBook is showing signs of age,
* The format's documentation is ancient and isn't terribly approachable.
* Writing XML by hand is a terrible, terrible experience. For this
reason a shocking fraction of the users' guide isn't even valid
DocBook (although is still accepted by the tools)
* The tooling surrounding the format is challenging to bring up on
* Getting even a simple image displayed consistently in the PDF and
HTML output is an exercise in futility 
There are a few alternatives that we could switch to,
* Markdown: While ubiquitous, its syntax isn't nearly expressive
enough to accomodate the users guide.
* asciidoc: This was the front-runner in . Unfortunately, when I
tried to use it in anger on the users guide things pretty quickly
fell apart start to come apart. The syntax is sadly not very
composable: tasks like nesting a code block inside a list becomes
fragile and quite unreadable due to the need for continuation
characters (as delimited blocks like code blocks must begin at
Despite this I did manage to get much of the way through an
asciidoc-ification of the users guide  but only through a great
deal of manual fixing. While asciidoc does strive to map one-to-one
onto DocBook, my experience is that the converse is not true; a
conversion to asciidoc require that we drop some of the finer
distinctions between code-like inline elements. For an example of
the continuation character issue, see .
* ReStructuredText: this was a close second-place in the thread and
has a fairly wide user base. The primary implementation, Sphinx, is
used by Python, MathJAX, LLVM, Ubuntu, Ceph, Blender, and others.
The syntax is fairly similar to Markdown and is at least as
expressive as asciidoc.
I have converted the entire users guide to ReStructuredText with a
modified Pandoc. While some tweaking is still certainly necessary
the output from the most-mechanical conversion looks quite good,
* HTML (using a modified version of LLVM's theme),
* PDF produced by xetex (used to get convenient Unicode support),
* ePub (I know nothing about this format)
* Even Github's rendering of the source looks reasonable good,
Of course, there are a few annoyances: the doctree construct doesn't
quite work how one might expect, requiring one to split up files a
bit more than one might like. Like asciidoc, there is no good way to
express nested inlines, so we still lose some of the expressiveness
Another nice advantage here is that Trac has native support  for
rendering RST which could come in handy when pasting between
At this point we are leaning towards going with ReStructuredText: the
tooling is much better the DocBook, the format reasonably easy to grok
and expressive enough to accomodate the majority of the users guide
However, we would love to hear what others think. Are there any formats
we have overlooked? Are there any objections to going ahead with this?
If we want to move forward with ReStructuredText I think we will want to
move quickly. While the conversion is mostly automated, there is some
amount of manual fiddling necessary to get things formatted nicely.
There are a few open Differentials that would need to be amended after
the change but I would be happy to help authors through this if
-------------- next part --------------
A non-text attachment was scrubbed...
Size: 472 bytes
Desc: not available
More information about the ghc-devs