Writing text

There are many ways to markup plain text. There is SGML and its off-shoot HTML. Later came XML, a replacement for SGML, a general-purpose way of making markup languages, one of which is XHTML, which is what you are using to view this page now.

There is also LaTeX, which is a markup used for typesetting in various contexts, especially in academic fields where complex mathematical equations are used.

With all these formats, the marked up document is plain text, and then rendered into its final form, that form may be paper, or it may be a browser window. The downside to these formats is that the marked up plain text document is ugly - full of random angle brackets and letters and words entered into the text that you are trying to read. While after using HTML for a decade I can more or less block it out, the plain text form is far less readable because of the markup.

Enter reStructuredText

reStructuredText is a markup language that does things differently. It uses more natural looking markup with a focus on readability so reStructuredText can be easily read and shared in its plain text form. You can then automatically processes the document into XML (called Docutils XML), and from there it can go into XHTML, LaTeX, OpenDocument, Docbook, or any other format that you can get to from XML. So readable, yet maps to XML in a well thought out way.

If you are going to abbreviate reStructuredText, then use 'rst', don't use 'rest' because that gets confusing with Representational State Transfer, a completely different thing altogether.

I have jumped in the deep-end and I am using reStructuredText to write my posts in this new version of the site, and it is an optional markup format for people leaving their opinions in the discussion/comments section (you don't need to use it to leave a comment).

While I have just got into it, reStructuredText has been around for several years, and has been most prominently used for creating Python documentation, however, it is a general purpose and extensible markup language that can be used in many different contexts.

Some people use it to create text for the web or for standalone documents. It can also be used wherever you might have made a one-off markup format, such as on a web forum, wiki or comments section.

reStructuredText everywhere

The reference implementation of a reStructuredText parser is called Docutils which is written in Python (but this can be used from many languages). Docutils is very easy to use in your application to process reStructuredText.

If you do not have docutils on your system already then it is available from all Linux/BSD package managers. For Windows, follow the installation-instructions.

There are also third-party parsers in Perl, Java, Haskell and probably more that I have not heard of. There are also plugins for text editors and plugins for lots of web frameworks, content management systems and web log software.

As explained in the last post, Django comes with reStructuredText support (bindings to docutils) out of the box. Lastly, there are also lots of cute reStructuredText website generators that allow you generate a website from a set of reStructuredText files. For example, Michael's rest2web, Sphinx,which is used to create the new Python 2.6/Python 3000 documentation, and Damien Baty's Soho.

Very quick reStructuredText (permalink to markup)

Okay, enough blab, lets get into it. There is very comprehensive set of markup available, but I will just cover a few basic ones that are always useful.

There is no need for paragraph tags or linebreak tags; to make a paragraph, you just make a paragraph, to break a line you just break a line.

To mark something with emphasis (i.e. italic), you use a star around the word or pharse: *emphasised text* becomes emphasised text.

Two stars are for strong emphasis (i.e. bold). Like so:

Hyperlinks

To make a hyperlink, you just start the text with http:// . So http://commandline.org.uk/ becomes: http://commandline.org.uk/

If you want to do a named hyperlink, then you need two parts. First, you put an underscore after the name, for example Zeth_ will become Zeth

Then you need a target to go with that name. You specify the target with two dots, a space and an underscore:

.. _Zeth: http://commandline.org.uk/

The line with the target can go anywhere in the document. For example, some people put the target line straight after the paragraph that has the name in. However, in a long document, it is often tidier to put all the targets at the end.

Lists

To make an unordered list (i.e. a bullet list), just start the line with a star, plus or hyphen, for example:

* Green eggs
* Ham

Becomes:

• Green eggs
• Ham

For a numerated list, just start the line with the number and a dot, for example:

1. Green eggs
2. Ham

Becomes:

1. Green eggs
2. Ham

I could go on, but I think you get the idea. By default, the core of reStructuredText is broadly feature equivalent to HTML. However, reStructuredText is very flexible and allows you to go beyond that core, as we shall look at next.

Directives

To markup a piece of more advanced functionality, you use a 'directive'. Directives are where reStructuredText shines over similar markup languages. Directives are extensions to the main markup, some directives are included by default (analogous to a standard library), others can be added by yourself or from getting them from the web or wherever. I will give an example of a standard directive, then an example of a third-party directive.

A directive has four parts. First you have some markup declaring the directive itself (two dots), second comes the directive name, third is some markup that says here is the content (two colons), lastly there is the content.

Two dots, the name, two colons, the content.

.. name :: content

So to display an image, you use the image directive.

You write two dots, a space, the word "image", two colons and then the URL:

.. image:: \http://commandline.org.uk/images/whokilledtux.png

Becomes:

To share source code, firstly you start with the source code directive, this is two dots, the directive name (source code), followed by two dots; secondly, we have the name of the language the source code is in. Then we leave a blank line, then we write the source code indented (preferably with four spaces ;-)

So for example:

.. sourcecode:: python

    import os
    for i in os.uname():
        print i

Will become:

import os
for i in os.uname():
    print i

Here is the list of supported languages on this site.

There you go, if you made it this far then you can use ReStructuredText, give it a go! You can start by leaving a comment in ReStructuredText format!