<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Tue, Oct 7, 2014 at 6:25 PM, Edward Z. Yang <span dir="ltr"><<a href="mailto:ezyang@mit.edu" target="_blank">ezyang@mit.edu</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">I personally don't have a problem writing Docbook, and one problem<br>
with moving to lightweight markup is it becomes a bit harder to<br>
keep your markup semantic.<br>
<br>
Edward<br>
<br></blockquote><div><br></div><div>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).<br><br></div><div>Michael<br></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Excerpts from Herbert Valerio Riedel's message of 2014-10-07 09:20:43 -0600:<br>
<div class="HOEnZb"><div class="h5">> Hello GHC Developers & GHC User's Guide writers,<br>
><br>
> I assume it is common knowledge to everyone here, that the GHC User's<br>
> Guide is written in Docbook XML markup.<br>
><br>
> However, it's a bit tedious to write Docbook-XML by hand, and the XML<br>
> markup is not as lightweight as modern state-of-the-art markup languages<br>
> designed for being edited in a simple text-editor are.<br>
><br>
> Therefore I'd like to hear your opinion on migrating away from the<br>
> current Docbook XML markup to some other similarly expressive but yet<br>
> more lightweight markup documentation system such as Asciidoc[1] or<br>
> ReST/Sphinx[2].<br>
><br>
> There's obviously some cost involved upfront for a (semi-automatic)<br>
> conversion[3].  So one important question is obviously whether the<br>
> long-term benefits outweight the cost/investment that we'd incur for the<br>
> initial conversion.<br>
><br>
> All suggestions/comments/worries welcome; please commence brainstorming :)<br>
><br>
><br>
><br>
>  [1]: <a href="http://www.methods.co.nz/asciidoc/" target="_blank">http://www.methods.co.nz/asciidoc/</a><br>
><br>
>  [2]: <a href="http://sphinx-doc.org/" target="_blank">http://sphinx-doc.org/</a><br>
><br>
>  [3]: There's automatic conversion tools to aid (though manual cleanup<br>
>       is still needed) the initial conversion, such as<br>
><br>
>          <a href="https://github.com/oreillymedia/docbook2asciidoc" target="_blank">https://github.com/oreillymedia/docbook2asciidoc</a><br>
><br>
>       As an example, here's the conversion of<br>
><br>
>          <a href="http://git.haskell.org/ghc.git/blob/HEAD:/docs/users_guide/extending_ghc.xml" target="_blank">http://git.haskell.org/ghc.git/blob/HEAD:/docs/users_guide/extending_ghc.xml</a><br>
><br>
>       to Asciidoc:<br>
><br>
>          <a href="https://phabricator.haskell.org/P24" target="_blank">https://phabricator.haskell.org/P24</a><br>
><br>
>       to give an idea how XML compares to Asciidoc<br>
_______________________________________________<br>
ghc-devs mailing list<br>
<a href="mailto:ghc-devs@haskell.org">ghc-devs@haskell.org</a><br>
<a href="http://www.haskell.org/mailman/listinfo/ghc-devs" target="_blank">http://www.haskell.org/mailman/listinfo/ghc-devs</a><br>
</div></div></blockquote></div><br></div></div>