=================================
 reST (reSTructured Text) basics
=================================

.. Author:  Fernando Perez
.. Contact: Fernando.Perez@colorado.edu
.. Time-stamp: "2007-01-28 19:21:37 fperez"

.. contents::
..
    1  What is reST?
    2  Markup summary
    3  Emacs cheat sheet
    4  Tests
    5  Things I don't like
..


What is reST?
-------------

It's a simple text markup format which can be converted easily into other
formats (html, latex, pdf) while being easily readable in its plaintext
version.  This document is a little example of reST basics for my own
reference.

As shown above, it's good practice to start any reST document with a title and
simple metadata.  The two leading dots indicate a comment or special markup
directive in reST.  The time stamp can be updated with the emacs command
``time-stamp`` (these two back-quotes mean 'inline literal', which is normally
rendered as monospace font).

The metadata above was enclosed inside comment fields, so it won't be visible
in the generated document.  You can instead use reST fields if you want these
values to be automatically formatted in produced documents:

:Author:  Fernando Perez
:Contact: Fernando.Perez@colorado.edu
:Date: January  4, 2007

The table of contents is auto-updated by Emacs with 'C-c p u', and it is also
rendered in HTML by the rst2html compiler.  This can be invoked from Emacs via
the ``rst-compile`` command.  Additionally, Emacs makes each entry in the TOC
an internal clickable link, which is great for navigation.

This_ link is a quick reference to the reST markup (links are made by an
underscore at the end of the word, and the same word following shortly with the
underscore preceding it instead, and its target indicated after a colon).

.. _This: http://docutils.sourceforge.net/docs/user/rst/quickref.html


Markup summary
--------------

These are taken from the quickref mentioned above, and are just a small subset
of the more common markup options.  See that document for more details.

- *emphasis*: Normally rendered as italics.
  
- **strong emphasis**: Normally rendered as boldface.
  
- ``inline literal``: Normally rendered as monospaced text. Spaces should be
  preserved, but line breaks will not be.  For multiline literal blocks, use
  ``::`` preceding the literal block (if it's at the end of a sentence, it gets
  converted into a single ':').
  
- reference_: A simple, one-word hyperlink reference.
  
- `phrase reference`_: A reference with spaces or punctuation.
  
- footnote reference [1]_: See quickref for details.
  
- citation reference [CIT2002]_: See quickref for details.

Note: the above are listed using bullet list markup. reST also has markup for
enumerated, options, definitions and fields lists.


Emacs cheat sheet
-----------------

These are a few useful Emacs bindings, copied from the help and support source
code.  C-= is by far the most common and useful one::

    C-c p a (also C-=): rst-adjust

       Updates or rotates the section title around point or promotes/demotes
       the decorations within the region (see full details below).

       Note that C-= is a good binding, since it allows you to specify a
       negative arg easily with C-- C-= (easy to type), as well as ordinary
       prefix arg with C-u C-=.

    C-c p h: rst-display-decorations-hierarchy

       Displays the level decorations that are available in the file.

    C-c p t: rst-toc

       Displays the hierarchical table-of-contents of the document and allows
       you to jump to any section from it.

    C-c p i: rst-toc-insert

       Inserts a table-of-contents in the document at the column where the
       cursor is.

    C-c p u: rst-toc-insert-update

       Find an existing inserted table-of-contents in the document an
       updates it.

    C-c p p, C-c p n (C-c C-p, C-c C-n): rst-backward-section,
    rst-forward-section

       Navigate between section titles.

    C-c p l, C-c p r (C-c C-l, C-c C-r): rst-shift-region-left,
    rst-shift-region-right

       Shift the region left or right by two-char increments, which is perfect
       for bulleted lists.

    M-S		center-paragraph

    M-s		center-line


Tests
-----

some text

- a bulleted
- list
- without indentation

more text

  - and another bullet list
  - but indented in the plaintext source

and more text.


Trying block quotes::

  foo bar

  baz

normal text


Things I don't like
-------------------

- The fact that indented bulleted lists in the source end up double-indented in
  the rendered doc.  Since the default rendering of bullet lists indents (in
  html), then the source should be the same.

- Requiring indentation for block literals.  This sucks for pasting code in and
  out of reST docs.