On Tue, Oct 7, 2014 at 6:20 PM, 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/
[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@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