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 <hvrie...@gmail.com> wrote: > 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 > _______________________________________________ > 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/ _______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://www.haskell.org/mailman/listinfo/ghc-devs
