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

    1. italics

    2. bold

    3. monospace font

    4. 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!