Switching users guide to ReStructuredText

[Ben Gamari]

Simon Peyton Jones <simonpj at microsoft.com> writes:

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

-------------- 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/c63533be/attachment.sig>