Switching users guide to ReStructuredText

[Simon Peyton Jones]

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 at 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