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

[Michael Snoyman]

On Tue, Oct 7, 2014 at 6:25 PM, Edward Z. Yang <ezyang at mit.edu> wrote:

> 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/
> >
> >  [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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.haskell.org/pipermail/ghc-devs/attachments/20141007/9d1d0f5d/attachment.html>