RST: Best Practices
Note: RST is no longer used at DP. Information on this page may be out of date.
This page is a reference for post-processors using RST. Here, suggested best practices will be presented. These are the suggested ways of semantic and presentational markup compatible with epubmaker.
Poetry
Poetry is marked using the pipe symbol "|". Three spaces, the pipe symbol, and one space should precede each line of poetry that is left-adjusted in the original poem.
Written in a stiff little hand I read:
| "Your lips are lined with roses,
| Your eyes they shine like gold
| If you call me from the sunlight,
| I'll answer from the cold.
| But I wonder why, Oh, why,
| You stay so far from me?
| If you whisper from the prairie,
| I'll call from Calgary."
“Won't it be wonderful,” said Lossie as I sat pondering over those
foolish little lines, “won't it be wonderful, if Dinkie grows up to be
a great poet?”
Note that after the pipe symbol, the PPer can indicate relative indentation.
Epigraphs
Epigraphs typically come immediately after a chapter heading. They may contain prose:
.. epigraph::
The historical development of a particular branch of
science, such as radio telegraphy, in order to be complete and of
instructive value should, if possible, be traced thru the personal
connection therewith of all of its pioneers.
—Donald McNicol, in `Early Wireless Magazine`, Oct. 1917
The ship stole through the darkness with extremest caution...
or even poetry:
.. epigraph::
| `When you are old and grey and full of sleep,`
| `And nodding by the fire, take down this book,`
| `And slowly read, and dream of the soft look`
| `Your eyes had once, and of their shadows deep;`
—W. B. Yeats
In the dim, humid basement of his Maryland home...
Note the use of the back-tick on each line to cause it to render as italic. The attribution in each example is optional.
Chapters and Sections
Chapters should be marked with a single underline using equal signs exactly the same length as the title.
CHAPTER I: BETTY LEE’S MOST MOVING ADVENTURE ============================================ Betty Lee, aged almost fourteen, was dressing for travel. She both dreaded and anticipated the day...
The title of the book, included once at the start of the text, also uses the equal sign. However, the title must have a row of equal signs above and below:
=========================================================
BETTY LEE, FRESHMAN
=========================================================
For subsections, underline the subsection title with a row of dashes ("-") exactly as long as the subsection text. If subsections are used and if you want them to show up in the autogenerated Table of Contents, change the depth to 2:
.. contents:: Table of Contents
:backlinks: entry
:depth: 1
Block Quotes
Block quotes can be indicated by indenting the left margin at least three spaces.
Further, evidence suggests that Milton understood exactly what
it meant to retreat, Ignatian-style, into the inner self for private
imaginings:
It is better therefore to contemplate the Deity, and to conceive of him,
not with reference to human passions, that is, after the manner of men,
who are never weary of forming subtle imaginations respecting him, but
after the manner of Scripture, that is, in the way wherein God has
offered himself to our contemplation; . . . (`CE` xiv. 33)
Who are these ambiguous men who “never weary of forming subtle
imaginations”?
Block quotes may be nested.
A block quote may end with an attribution: a text block beginning with "--", "---", or a true em-dash, flush left within the block quote. If the attribution consists of multiple lines, the left edges of the second and subsequent lines must align.
Footnotes
Footnotes are typically indicated by a space, left bracket, a number, a right bracket, and an underscore.
Only an American—and I am not one except by long association [1]_—can speak [2]_ for the heart of America.
Note that the space before the bracket is required and is handled by each rendering back-end. For example, in text it is removed. You can also auto-number footnotes using "[#]_" instead of a specific number. Or you can use auto-symbols using "[*]_" designators. Footnote marks, starting with an asterisk, will be automatically be generated in the order defined by the The Chicago Manual of Style, 14th edition.
The footnote targets are straightforward and included here for completeness:
.. [1] Perhaps I should add that I have not been in the United
States since January 1912. My observations stretched, with
some intervals, through the forty years preceding that date.
.. [2] Another footnote.
Epubmaker also has a footnote directive for more control over footnote placements. To use, put the footnotes themselves after the paragraphs that reference them. Then, at the end of the document, add this (class is optional):
.. footnotes:: Footnotes
:class: smaller
For the html and epub versions, the footnotes will be collected at this "anchor." For the text versions, this directive will be ignored. See PG etext 181's footnote example for more information.
Italics
Italics are usually the result of markup using an asterisk for emphasis.
That was *not* a good reason.
will generate the word "not" in "italics" usually.
However, there are times when only part of a word is to be in italics. The asterisk needs a separator so to have only the "As" in aspiration be in italics, set the asterisk marking emphasis off with a backslash+space:
“‘Inspiration,’ then,” said Carolyn. “What’ll I hitch up with? I couldn’t play a violin.” “\ *As*\ piration,” chuckled Betty. “Pick out your brightest dream, ‘Caro,’ and put on the harness!”
The backslash+space does not show up in the output when used in this way.
Small Caps
Small caps are not part of the base RST specification, however they are easily added using methods provided for such extensions. If you have small caps in your book and want to retain them, first put these two lines near the start of the book, typically after the encoding directive:
.. role:: small-caps
:class: small-caps
Then, in text, use
:small-caps:`The rain` wouldn't stop.
The two words "The rain" will be presented in small caps. Note: EpubMaker has a class for small-caps built in. The complete list of built-in classes for epubmaker is shown in PG etext 181.
TOC/LOI
RST can generate a Table of Contents with links and backlinks to each chapter with the simple directive:
.. contents:: Table of Contents
:backlinks: entry
:depth: 1
However, the PPer does not have to use that directive. The Table of Contents or a List of Illustrations can be marked-up manually as well, using internal links to the chapters. Here's how to do that for the TOC and LOI.
For the Table of Contents, this construction works well:
.. class: larger **CONTENTS** I. `Swickey Shoots a Bear`_ II. `Lost Farm Folk`_ III. `Much Ado about Beelzebub`_ IV. `The Compact`_
Then, the target for the first chapter is
.. _`Swickey Shoots a Bear`: CHAPTER I—SWICKEY SHOOTS A BEAR =============================== Old man Avery hurried from the woods...
Each chapter is marked as an explicit internal hyperlink as shown.
For a List of Illustrations, this construction works well:
.. class: larger **ILLUSTRATIONS** | `"Where be they?" she whispered`_ | `"Here's your game," he said hoarsely`_ | `"I didn't know, Swickey—I thought—there was someone else"`_
The target for the first illustration is then:
.. _`"Where be they?" she whispered`:
.. figure:: images/camp-076.jpg
:align: center
"WHERE BE THEY?" SHE WHISPERED
Tables
There are two syntaxes for tables in reStructuredText. Grid tables are complete but cumbersome to create. Simple tables are easy to create but limited. Here are examples of each for reference. First a simple table.
===== ===== ======
Inputs Output
------------ ------
A B A or B
===== ===== ======
False False False
True False True
False True True
True True True
===== ===== ======
Note the pattern of the "=====" to indicate the rows. Now a grid table:
+------------+------------+-----------+ | Header 1 | Header 2 | Header 3 | +============+============+===========+ | body row 1 | column 2 | column 3 | +------------+------------+-----------+ | body row 2 | Cells may span columns.| +------------+------------+-----------+ | body row 3 | Cells may | - Cells | +------------+ span rows. | - contain | | body row 4 | | - blocks. | +------------+------------+-----------+
RST markup is not appropriate for books containing tables with more advanced requirements.
Escaping
Sometimes a line of text entered as presented in the original book will trigger RST into thinking it is markup.
A. Einstein
should be written with a leading backslash:
\A. Einstein
so the parser doesn't think it is the start of a list (A., B, C. etc.)
Superscripts, subscripts
These are used infrequently:
For superscript. E = mc\ :superscript:`2` For subscript. H\ :subscript:`2`\ O For references to titles of works, eg. :title-reference:`Hamlet`. For code blocks. :literal:`print 'Hello, World!'`
Vertical Space
Vertical space can be produced in two ways. One is as recommended in standard RST. The other is to use a non-standard presentation markup extension defined in EpubMaker. Considering only the first method, here is an example of the front matter of a book using vertical spacing between original pages:
.. class:: align-center
|
|
BETTY LEE, FRESHMAN
By
HARRIET PYNE GROVE
.. image:: images/illus-emb.jpg
:align: center
.. class:: align-center
THE WORLD SYNDICATE PUBLISHING CO.
Cleveland, Ohio — New York City
|
|
Copyright, 1931
by
THE WORLD SYNDICATE PUBLISHING CO.
.. image:: images/illus-em2.jpg
:align: center
.. class:: align-center italics
Printed in the United States of America
Note the vertical "pipe" symbols with three spaces to the left. Each of these will generate a single blank line at that point in the output. The result is shown on the title page here.
There is no need to provide vertical space where markup implies the spacing already. For example, if a chapter header is indicated the appropriate spacing before and after will be applied automatically. Typically, PPers will use the "|" symbol to create a vertical space only in front matter, like the title page, and in back matter, typically advertisement pages.
UTF-8
You should use UTF-8 for RST markup. The standard header for a RST file submitted to PG has this as the first line:
.. -*- encoding: utf-8 -*-
The tools used by the WWer's to produce the book start with the UTF-8 file as submitted and generate the Latin-1 and plain ASCII files from that. Note that GuiGuts was written to handle UTF-8 characters. PPers who use GG will save their RST source file as UTF-8 by default if any UTF-8 characters are in the file.
Roles
Roles allow limited styling to RST markup. For example to have some words in small caps:
.. role:: small-caps
:class: small-caps
This text is in :small-caps:`Small Caps`.
You can attach more than one class to a role:
.. role:: big-and-bold
:class: larger bold
This text is :big-and-bold:`big and bold`.
PPers using Epubmaker are limited to classes that are part of EpubMaker as listed http://www.gutenberg.org/cache/epub/181/pg181.html here].
Meta Information
Every RST file submitted to Project Gutenberg must have a meta-information block near the top of the file, below the title block. The meta information is not required during early stages of post-processing, but it is not harmful.
Here is the start of an example file as submitted to the WW:
.. -*- encoding: utf-8 -*-
===================
BETTY LEE, FRESHMAN
===================
.. meta::
:PG.Id:
:PG.Title: Betty Lee, Freshman
:PG.Released:
:PG.Rights: Public Domain
:PG.Producer: Roger Frank
:PG.Producer: the Online Distributed Proofreading Team at http://www.pgdp.net
:DC.Creator: Harriet Pyne Grove
:DC.Title: Betty Lee, Freshman
:DC.Language: en
:DC.Created: 1931
:coverpage: images/cover.jpg
The post-processor has this information readily available. Note The PG.Id and PG.Released fields can be left blank for the WWers to fill in when an etext number is assigned and the book is posted. Post-processors should make sure the PG.Producer line(s), the two Title fields and the Creator field should all agree with the upload info.
The submitted file must also include the .. pgheader:: and .. pgfooter:: directives as shown in the examples.
Finally, if the post-processor has provided a cover image, include the last line indicating the filename to use, else omit the last line entirely.
link to RST Index Page