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

[Herbert Valerio Riedel]

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