[RFC] Moving user's guide to ReStructuredText

[Richard Eisenberg]

I know nothing about these different formats. But I dislike what we have now, and I have confidence that you *do* know something about these formats. So I'm very happy to take your recommendation on this.

+1

Thanks!
Richard

On Sep 23, 2015, at 4:02 AM, Ben Gamari <ben at well-typed.com> wrote:

> 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
> _______________________________________________
> ghc-devs mailing list
> ghc-devs at haskell.org
> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs