RFC: Source-markup language for GHC User's Guide

[Austin Seipp]

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
<hvriedel at 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 at haskell.org
> http://www.haskell.org/mailman/listinfo/ghc-devs
>



-- 
Regards,

Austin Seipp, Haskell Consultant
Well-Typed LLP, http://www.well-typed.com/