[RFC] Moving user's guide to ReStructuredText

[Ben Gamari]

Hello all!

Last year there was a brief thread [1] 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
    non-Linux platforms

  * Getting even a simple image displayed consistently in the PDF and
    HTML output is an exercise in futility [2]

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 [1]. 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
    column 0).

    Despite this I did manage to get much of the way through an
    asciidoc-ification of the users guide [2] 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 [3].

  * 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),

        http://smart-cactus.org/~ben/ghc-user-manual/html/index.html

      * PDF produced by xetex (used to get convenient Unicode support),

        http://smart-cactus.org/~ben/ghc-user-manual/xetex/GHCUsersGuide.pdf

      * ePub (I know nothing about this format)

        http://smart-cactus.org/~ben/ghc-user-manual/epub/GHCUsersGuide.epub

      * Even Github's rendering of the source looks reasonable good,

        https://github.com/bgamari/ghc/blob/doc-rst/docs/users_guide/ghci.rst

    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
    of DocBook.

    Another nice advantage here is that Trac has native support [5] for
    rendering RST which could come in handy when pasting between
    documents.

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
unmodified.

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
necessary.

Cheers,

- Ben


[1] https://mail.haskell.org/pipermail/ghc-devs/2014-October/006599.html
[2] https://ghc.haskell.org/trac/ghc/ticket/10416
[3] https://github.com/bgamari/ghc/blob/asciidoc/docs/users_guide/
[4] https://github.com/bgamari/ghc/blame/asciidoc/docs/users_guide/ghci.asciidoc#L2162
[5] http://trac.edgewall.org/wiki/WikiRestructuredText
-------------- 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/ghc-devs/attachments/20150923/8a39c88d/attachment.sig>