Switching users guide to ReStructuredText
Simon Peyton Jones
simonpj at microsoft.com
Fri Oct 2 13:52:38 UTC 2015
It looks lovely.
Please please can we have section numbers?! It is so helpful to be able to say "see section 3.2.42 in the user manual". And the numbers give a clearer indication of sub-nesting than does the font in which the heading is rendered. It's a big manual to navigate!
| -----Original Message-----
| From: ghc-devs [mailto:ghc-devs-bounces at haskell.org] On Behalf Of Ben
| Sent: 02 October 2015 14:15
| To: GHC developers
| Subject: Switching users guide to ReStructuredText
| 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,
| 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
| - Ben
More information about the ghc-devs