Just for the record - I'm very much in favor of this. +1 from me.
I think the one-time cost is very low for the most part, if the end
result is a significantly more readable users guide to hack on.
IMO, I don't particularly care whether we use Sphinx or AsciiDoc. The
nice thing about AsciiDoc is it has a DocBook backend, so in theory we
could make the end results seem pretty similar. Sphinx on the other
hand generates its own documentation directly, I believe.
The more annoying bit is it will incur an extra dependency for GHC
documentation - which, remember, is part of ./validate - but that's
life, perhaps.
On Tue, Oct 7, 2014 at 10:20 AM, 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
-- Regards, Austin Seipp, Haskell Consultant Well-Typed LLP, http://www.well-typed.com/