On Tue, Oct 7, 2014 at 6:25 PM, Edward Z. Yang
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
Why would this be a problem with asciidoc? All asciidoc maps directly into DocBook markup, and for cases that the simple asciidoc markup is insufficient, you can always embed full-blown DocBook (though I've ever done that in practice). Michael
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
_______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://www.haskell.org/mailman/listinfo/ghc-devs