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... [5] http://trac.edgewall.org/wiki/WikiRestructuredText