I personally don't have a problem writing Docbook, and one problem with moving to lightweight markup is it becomes a bit harder to keep your markup semantic. Edward Excerpts from Herbert Valerio Riedel's message of 2014-10-07 09:20:43 -0600:
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/
[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