Switching users guide to ReStructuredText

Ben Gamari ben at smart-cactus.org
Fri Oct 2 13:14:53 UTC 2015

Hello friendly GHCers,

Last week I sent out poll asking opinions on moving the Users' Guide
From Docbook to ReStructuredText. While the response wasn't particularly
large in volume, those that did reply were quite supportive of the idea.

This week I took the time to clean up my hacked prototype. After quite
some build system wrangling, it's finally in a merge-worthy state as
D1294. You can see the output at,


In addition to converting the DocBook to ReST, this also involved
ripping out the previously rather fragile system for building the `ghc`
manpage and describing GHC's flags in utils/mkUserGuidePart.

Feel free to look over the output. If there are no objections I'll
merge this tomorrow.

Future Work

 * Verify the flag description in mkUserGuidePart against DynFlags
   (checking for missing or invalid flags)
 * Perhaps incorporate make flags representation a bit richer, encoding,
   for instance, implication relationships between flags
 * Generate flag descriptions for bash_completion and other shells
 * Improve manpage content
 * Be more precise about which code samples should be syntax highlighted


- Ben
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 472 bytes
Desc: not available
URL: <http://mail.haskell.org/pipermail/ghc-devs/attachments/20151002/8588d629/attachment.sig>

More information about the ghc-devs mailing list