RFC: Source-markup language for GHC User's Guide

[Michael Snoyman]

On Tue, Oct 7, 2014 at 6:20 PM, Herbert Valerio Riedel <hvriedel at gmail.com>
wrote:

> Hello GHC Developers & GHC User's Guide writers,
>
> I assume it is common knowledge to everyone here, that the GHC User's
> Guide is written in Docbook XML markup.
>
> However, it's a bit tedious to write Docbook-XML by hand, and the XML
> markup is not as lightweight as modern state-of-the-art markup languages
> designed for being edited in a simple text-editor are.
>
> Therefore I'd like to hear your opinion on migrating away from the
> current Docbook XML markup to some other similarly expressive but yet
> more lightweight markup documentation system such as Asciidoc[1] or
> ReST/Sphinx[2].
>
> There's obviously some cost involved upfront for a (semi-automatic)
> conversion[3].  So one important question is obviously whether the
> long-term benefits outweight the cost/investment that we'd incur for the
> initial conversion.
>
> All suggestions/comments/worries welcome; please commence brainstorming :)
>
>
>
>  [1]: http://www.methods.co.nz/asciidoc/
>
>  [2]: http://sphinx-doc.org/
>
>  [3]: There's automatic conversion tools to aid (though manual cleanup
>       is still needed) the initial conversion, such as
>
>          https://github.com/oreillymedia/docbook2asciidoc
>
>       As an example, here's the conversion of
>
>
> http://git.haskell.org/ghc.git/blob/HEAD:/docs/users_guide/extending_ghc.xml
>
>       to Asciidoc:
>
>          https://phabricator.haskell.org/P24
>
>       to give an idea how XML compares to Asciidoc
> _______________________________________________
> ghc-devs mailing list
> ghc-devs at haskell.org
> http://www.haskell.org/mailman/listinfo/ghc-devs
>

My $0.02: I originally wrote the Yesod book in XML[1], and through
automated tools converted it to asciidoc. The conversion was mostly
painless, and it's a *huge* improvement to be able to edit in asciidoc
instead. One of the nice things is you should be able to do the transition
incrementally, since you can generally mix asciidoc and DocBook.

Michael

[1] DITA which I converted into DocBook
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.haskell.org/pipermail/ghc-devs/attachments/20141007/9fde4acd/attachment.html>