Example reStructuredText Article

Author:	Cezary Sobaniec
Version:	1.5
Date:	2008-05-06
Contact:	Cezary.Sobaniec at put.edu.pl

Abstract

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Keywords: structured text, markup language, Python

Table of contents

1 Introduction
2 Formatting
- 2.1 Images
- 2.2 Sidebars
- 2.3 Other features
3 Listings
4 Tables
5 Conclusions
6 Bibliography

1 Introduction

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 [Goo06]. You can read more on RST in [Jon06].

2 Formatting

2.1 Images

There is an image put just before this paragraph, which is floating to the right. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

More important images may be presented with captions using figure directive. For example:

Fig. 1:. Example figure with a caption. The caption may be quite long. So long that it will not fit into a single line.

There may be references between sections and subsections. See for example introduction, or conclusions. Sed ut perspiciatis, unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam eaque ipsa, quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt, explicabo. Nemo enim ipsam voluptatem, quia voluptas sit, aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos, qui ratione voluptatem sequi nesciunt, neque porro quisquam est, qui dolorem ipsum, quia dolor sit, amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt, ut labore et dolore magnam aliquam quaerat voluptatem. Ut enim ad minima veniam, quis nostrum exercitationem ullam corporis suscipit laboriosam, nisi ut aliquid ex ea commodi consequatur? Quis autem vel eum iure reprehenderit, qui in ea voluptate velit esse, quam nihil molestiae consequatur, vel illum, qui dolorem eum fugiat, quo voluptas nulla pariatur?

2.2 Sidebars

This paragraph will have a sidebar note. At vero eos et accusamus et iusto odio dignissimos ducimus, qui blanditiis praesentium voluptatum deleniti atque corrupti, quos dolores et quas molestias excepturi sint, obcaecati cupiditate non provident, similique sunt in culpa, qui officia deserunt mollitia animi, id est laborum et dolorum fuga. Et harum quidem rerum facilis est et expedita distinctio. Nam libero tempore, cum soluta nobis est eligendi optio, cumque nihil impedit, quo minus id, quod maxime placeat, facere possimus, omnis voluptas assumenda est, omnis dolor repellendus. Temporibus autem quibusdam et aut officiis debitis aut rerum necessitatibus saepe eveniet, ut et voluptates repudiandae sint et molestiae non recusandae. Itaque earum rerum hic tenetur a sapiente delectus, ut aut reiciendis voluptatibus maiores alias consequatur aut perferendis doloribus asperiores repellat.

2.3 Other features

Footnotes — like this¹ or that one².
Comments can be ignored or transformed into HTML comments. There is an example comment below this list.
External hyperlinks can be encoded inline. For example this article is available at my home page.

3 Listings

Source code can be included verbatim like this:

class String
{
public:
    char *txt;
    String()
    {
        txt = new char[1];
        strcpy(txt, "");
    }
    String(char* t)
    {
        txt = new char[strlen(t)+1];
        strcpy(txt, t);
    }
    ~String()
    {
        delete [] txt;
    }
};

The code may be also parsed for inline formatting:

class String
{
public:
    char *txt;
    String()
    {
        txt = new char [1];
        strcpy(txt, "");
    }
    String(char *t)
    {
        txt = new char [strlen(t)+1];
        strcpy(txt, t);
    }
    ~String()
    {
        delete [] txt;
    }
};

It is also possible to include the contents of an external file using the following directive:

.. include:: in.txt
   :literal:

4 Tables

How about tables? Here you are:

Symbol	Meaning
Monday	Campground
Tuesday	Lake
Wednesday	Mountain

Table contents may be loaded from an external file:

**Tab. 1.** Example CSV table with a very long caption that will not fit into a single line
Who	Has	What
Ala	ma	kota
Ola	nie ma	psa

5 Conclusions

IMHO the main advantages of reStructuredText are the following:

Plain text — the documents are stored in plain text files. Using UTF-8 encoding you can embed quite a few special characters without using any macros. I mean non-breaking spaces, dashes, national characters.
Preview — it is easier to imagine the final presentation using reStructuredText rather than using LaTeX or HTML. The source code can be printed verbatim.
Lightweight solution — LaTeX or HTML require substantially more markup to achieve comparable formatting.

[1]	This is the the first footnote.

[2]

6 Bibliography

All documents below are available also in plain text format. To access them just replace the ending html extension with txt extension.

[Goo06]

David Goodger. An Introduction to reStructuredText. Available at http://docutils.sourceforge.net/docs/ref/rst/introduction.html.

[Jon06]

Richard Jones. A ReStructuredText Primer. Available at http://docutils.sourceforge.net/docs/user/rst/quickstart.html.

[Qrst]

Quick reStructuredText. Available at http://docutils.sourceforge.net/docs/user/rst/quickref.html.

[Goo07]

David Goodger. reStructuredText Directives. Available at http://docutils.sourceforge.net/docs/ref/rst/directives.html.

[Goo08]

David Goodger. eStructuredText Markup Specification. Available at http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html.