[RFC] Moving user's guide to ReStructuredText
eir at cis.upenn.edu
Wed Sep 23 12:03:08 UTC 2015
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.
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  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 
> 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
> column 0).
> 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
> of DocBook.
> 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
> - Ben
>  https://mail.haskell.org/pipermail/ghc-devs/2014-October/006599.html
>  https://ghc.haskell.org/trac/ghc/ticket/10416
>  https://github.com/bgamari/ghc/blob/asciidoc/docs/users_guide/
>  https://github.com/bgamari/ghc/blame/asciidoc/docs/users_guide/ghci.asciidoc#L2162
>  http://trac.edgewall.org/wiki/WikiRestructuredText
> ghc-devs mailing list
> ghc-devs at haskell.org
More information about the ghc-devs