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