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! Simon | -----Original Message----- | From: ghc-devs [mailto:ghc-devs-bounces@haskell.org] On Behalf Of Ben | Gamari | 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, | | | https://na01.safelinks.protection.outlook.com/?url=http:%2f%2fsmart- | cactus.org%2f~ben%2fghc-users- | guide%2fhtml%2findex.html&data=01%7C01%7Csimonpj%40064d.mgd.microsoft. | com%7Ce2f529a35e3345f36f3908d2cb2b7b65%7C72f988bf86f141af91ab2d7cd011d | b47%7C1&sdata=YZmhxdubnVPtHZhDN2in%2fRkgf9qvOrvjZVDe7gIDr%2f4%3d | | https://na01.safelinks.protection.outlook.com/?url=http:%2f%2fsmart- | cactus.org%2f~ben%2fghc-users- | guide%2fusers_guide.pdf&data=01%7C01%7Csimonpj%40064d.mgd.microsoft.co | m%7Ce2f529a35e3345f36f3908d2cb2b7b65%7C72f988bf86f141af91ab2d7cd011db4 | 7%7C1&sdata=gwQMm9GqhwbjcSqZImB%2fru5EEStL%2bBHAykGXf1Tr9YI%3d | | 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 | | | Cheers, | | - Ben