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, http://smart-cactus.org/~ben/ghc-users-guide/html/index.html http://smart-cactus.org/~ben/ghc-users-guide/users_guide.pdf 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
Ben Gamari
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,
http://smart-cactus.org/~ben/ghc-users-guide/html/index.html http://smart-cactus.org/~ben/ghc-users-guide/users_guide.pdf
I should also point out that our documentation now has documentation, http://smart-cactus.org/~ben/ghc-users-guide/html/editing-guide.html Anyone edits the Users Guide should at least glance as this document as it contains a few notes that are otherwise not terribly discoverable. Cheers, - Ben
| I should also point out that our documentation now has documentation, | | | https://na01.safelinks.protection.outlook.com/?url=http:%2f%2fsmart- | cactus.org%2f~ben%2fghc-users-guide%2fhtml%2fediting- | guide.html&data=01%7C01%7Csimonpj%40064d.mgd.microsoft.com%7Cad191576d | 71949b1486708d2cb2dd891%7C72f988bf86f141af91ab2d7cd011db47%7C1&sdata=i | IDVdqchctelJGtliVXp3rprcA5ErWrvMyBJZ2Kfacw%3d | | Anyone edits the Users Guide should at least glance as this document | as it contains a few notes that are otherwise not terribly | discoverable. Very good. But in each case can there be, side by side - here is what you write - here is how it looks ? What about lists with bullets/numbers, including multi-level lists? | | Cheers, | | - Ben
Simon Peyton Jones
| I should also point out that our documentation now has documentation, | | | https://na01.safelinks.protection.outlook.com/?url=http:%2f%2fsmart- | cactus.org%2f~ben%2fghc-users-guide%2fhtml%2fediting- | guide.html&data=01%7C01%7Csimonpj%40064d.mgd.microsoft.com%7Cad191576d | 71949b1486708d2cb2dd891%7C72f988bf86f141af91ab2d7cd011db47%7C1&sdata=i | IDVdqchctelJGtliVXp3rprcA5ErWrvMyBJZ2Kfacw%3d | | Anyone edits the Users Guide should at least glance as this document | as it contains a few notes that are otherwise not terribly | discoverable.
Very good. But in each case can there be, side by side - here is what you write - here is how it looks ?
I originally included renderings for each of the examples in the document but decided to cut out some of them to shorten things up. I would love to be able to show the code and rendering literally side-by-side, although I don't believe Sphinx natively supports this degree of layout control (although it may be possible to write a custom directive for this).
What about lists with bullets/numbers, including multi-level lists?
ReST of course supports these although I didn't describe them to avoid making the document a complete guide to ReST; perhaps I was too conservative here. I'll add a bit more description of the list syntax. I originally wanted to focus primarily on GHC-specific conventions, leaving the most of ReST to the documentation I cite in the Resources section. That being said, I would be willing to add more language describing ReST itself if this would be helpful. Cheers, - Ben
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
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!
Ahh, that's a good point. Indeed we can. I've uploaded an updated build with section numbers. Cheers, - Ben
Hi, Am Freitag, den 02.10.2015, 15:14 +0200 schrieb Ben Gamari:
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.
when you say you ripped out the system for building the manpage, do you mean that you have replaced it by a different system? The manpage is important, and I would hate to see it got. (I don’t think you implied that, but I want to check nevertheless.) Greetings, Joachim -- Joachim “nomeata” Breitner mail@joachim-breitner.de • http://www.joachim-breitner.de/ Jabber: nomeata@joachim-breitner.de • GPG-Key: 0xF0FBF51F Debian Developer: nomeata@debian.org
Joachim Breitner
Hi,
Am Freitag, den 02.10.2015, 15:14 +0200 schrieb Ben Gamari:
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.
when you say you ripped out the system for building the manpage, do you mean that you have replaced it by a different system? The manpage is important, and I would hate to see it got. (I don’t think you implied that, but I want to check nevertheless.)
Of course; I should have been more clear. The manpage is now generated by Sphinx from ReST source like the user guide. Hopefully the fact that it's written in ReST will mean that it will be updated more frequently than it has been in the past. Cheers, - Ben
participants (5)
-
Alexey Vagarenko -
Ben Gamari -
Ben Gamari -
Joachim Breitner -
Simon Peyton Jones