reStructuredText for Fiction

reStructuredText is a great thing. It is plain, readable text that can be converted to every useful format, and something else. I've moved to reST for most of my writing, and I'm not going back.

Learning reST is easy, but most of its tutorials are geared towards documentation writer or at most website generation, and reST is versatile enough to be used for many other kinds of writing. As an example, reST is an excellent choice for fiction: this is a field where less is better and prose in reST looks just like that, lines and lines of prose.

reStructuredText Primer for Fiction Writers

reStructuredText is just plain text that can be written with any text editor, and includes some easily readable markup.

Paragraphs

The main structure of reST is the paragraph, a chunk of text separated by a blank line and kept on a constant level of indentation, i.e. aligned on the left edge.

Paragraph don't have to start from the first character of the line: an indented paragraph is often used for quoted text.
A paragraph where every line starts
with a vertical bar
preserves line breaks and initial intents
and can be useful for poetry.
Longer lines can be included by starting a continuation line with a space.

In reST source, these paragraphs would be written as:

The main structure of reST is the paragraph, a chunk of text separated
by a blank line and kept on a constant level of indentation, i.e.
aligned on the left edge.

   Paragraph don't have to start from the first character of the
   line: an indented paragraph is often used for quoted text.

| A paragraph where every line starts
| with a vertical bar
| preserves line breaks and initial indents;
|    it can be useful for verse.
| Longer lines can be included
  by starting a *continuation* line
  with a space.

Inline markup

Text inside a paragraph can be marked for emphasis by enclosing it with asterisks *like this*. A second level of emphasis is available, using **double asterisks**, but most writers won't ever need it.

Sections and structure

Titles and other section headers are written as a single line of text with an adornment: an underline (or an underline and an overline) in one of the following characters: = - ` : ' " ~ ^ _ * + # < >. Headers marked with the same characters are considered to be at the same section level. An unique marking at the beginning of the document is used for the document title, and another unique marking just after can be used for a document subtitle.

For example:

==============
My Great Title
==============

-------------------------------------
So great, that it requires a subtitle
-------------------------------------

Chapter 1: The Beginning
========================

Chapter 2: Something Else
=========================

Note that underline-only and underline-and-overline adornements are considered different even if they use the same character.

Another structure-giving markup is the transition marker: an horizontal line of 4 or more repeated characters from the list above such as:

------

or:

^^^^^^

Both of which would be rendered in HTML as an horizontal line, or as a gap of one or more lines in other formats.


Transition markers can't be at the begin or end of a section, and they can't be adiacent.

Footnotes

Footnotes are referenced in a paragraph [1] and then written on a line that starts with two points, the footnote mark and their text.

[1]in this case, manual numbered footnotes.

This style of footnote would be written in reST as:

Footnotes are referenced in a paragraph [1]_ and then written on a line
that starts with two points, the footnote mark and their text.

.. [1] in this case, manual numbered footnotes.

Footnote references can also be autonumbered [2], or autonumbered with a label [3], for ease of referencing.

[2]Using just a # sign.
[3]Using a # sign followed by a label name.

It is also possible to reference a footnote using a set [*] of automatically [†] choosen symbols.

[*]Using a *.
[†]Using another star.

The source for this example is:

Footnote references can also be autonumbered [#]_, or autonumbered
with a label [#mylabel]_, for ease of referencing.

.. [#] Using just a ``#`` sign.

.. [#mylabel] Using a ``#`` sign followed by a label name.

It is also possible to reference a footnote using a set [*]_
of automatically [*]_ choosen symbols.

.. [*] Using a ``*``.

.. [*] Using another star.

Footnotes inside other footnotes? [4]

[4]Of course [5]
[5]And numbering is kept.
Footnotes inside other footnotes? [#]_

.. [#] Of course [#]_

.. [#] And numbering is kept.

Note the space between the footnote reference and the previous word; it is required, but it can be suppressed from the rendering in most target formats. Renderers may also move footnotes somewhere else, usually on the bottom of the page. An example of this is available as source, HTML and PDF as generated by the docutils tools.

Directives

Directives are used to give special semantics to certain part of text and they are written with two periods, a space, the directive name, two colons and the text, with further lines indented.

A simple example of directive is used to write an epigraph; for example:

.. epigraph:: Some wise text

   – an Old Sage

may become

Some wise text

– an Old Sage

A more complex example of directive is used to include a figure, with a file name and possibly a list of options such as:

.. image:: filename.png
   :height: 100px
   :width: 100px
   :scale: 90%
   :alt: a short description of the image
   :align: center

Where height, width and scale are used to control the desired size of the image, the alt is used when an image can't be displayed, such as in applications for visually impaired users and align allows to give an hint for image positioning.

And Much More

This is just a selection of the parts of reStructuredText that I believe are most useful for non-technical writing; for further informations I recommend the reStructuredText documentation, starting with A ReStructuredText Primer. Such documentation, somewhat targeted to the tecnhical writers, explain for example how to do hyperlinks in reST, and many other omissions of this article.

Further readings

Tadhg O'Higgins wrote on his blog about his move from word processors to reStructuredText for fiction: Moving From Word Processors to reStructuredText and also about automatical conversion from WP file formats: RTF/Word–reStructuredText Toolchain

This thread on the python mailing list discusses the feasibility of using reST for things that are not documentation.

Somebody is using reStructuredText to write screenplays.

There is a nice editor for reStructuredText called retext which offers a live preview beside your source; while I don't use it (I already have an editor of choice: vim) it can be a good idea as a learning tool.

Send a comment: unless requested otherwise I may add it, or some extract, to this page.

Return to Top