reStructuredText
================

**reStructuredText** is an easy-to-read, what-you-see-is-what-you-get plaintext
markup syntax and parser system.  It is useful for in-line program
documentation, for quickly creating simple web pages, and for standalone
documents. reStructuredText is designed for extensibility for specific
application domains.  The reStructuredText parser is a component of Docutils.
reStructuredText is a revision and reinterpretation of the StructuredText and
Setext lightweight markup systems.

Documentation
-------------

A reStructuredText Primer
  Just to touch it:
  http://docutils.sourceforge.net/docs/user/rst/quickstart.html

Quick reStructuredText
  Can be found at http://docutils.sourceforge.net/docs/user/rst/quickref.html.
  Very handy.

reStructuredText Markup Specification
  This is the most important document describing all formatting options.
  Available at http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html

Lists
-----
 
Now, let us take a look at some basic formatting possibilities:

1. This is a simple list.

   * List items
   * can be
   * nested.

2. Enumerated lists can use different forms of numbering, e.g.:

   a) *italics*

   b) **bold**

   c) ``monospace`` font

   d) This paragraph contains

      another paragraph.  Just watch the indentation!

Now let us cite someone:

  Niechaj to narodowe wżdy postronni znają, iż Polacy nie gęsi, iż swój język
  mają.

  -- Mikołaj Rej

In case of poems use this form:

  | Beatus vir
  | qui non abiit in consilio impiorum
  | et in via peccatorum non stetit
  | et in cathedra pestilentiae non sedit.

In case of computer programs use this form::

  #include <stdio.h>

  int main()
  {
    printf("Hello world!\n");
  }

Notice the double colons ``::`` at the end of the line proceeding the code.  The
colons may be placed also in a separate line:

::

  The code starts here.

There are many more formatting features of reStructuredText like footnotes,
citations (bibliography), hyperlinks, sidebar notes, images, tables, etc.

Docutils
--------

Install the Docutils_ package and convert the file into HTML or LaTeX::

  # rst2html.py first.txt first.html
  # rst2latex.py first.txt first.tex
  # pdflatex first.tex

And obviously use a `good editor`_ to edit the source files.  Do not forget to
add::

  autocmd BufRead *.txt set filetype=rst

somewhere in your ``.vimrc`` configuration file.  This example file and
associated CSS stylesheet are available at:

  http://www.cs.put.poznan.pl/csobaniec/examples/rst/

Enjoy!

.. _Docutils:    http://docutils.sourceforge.net
.. _good editor: http://www.vim.org