RST: An Introduction for Post-Processors

Note: RST is no longer used at DP. Information on this page may be out of date.

Overview

reStructuredText, or RST, is an easy-to-read plaintext markup syntax available to post-processors to produce books. It's easiest to understand when compared to the traditional post-processing methods.

Traditionally, a project comes into post-processing and is edited with GuiGuts. After checks have been made, two versions of the text are saved out of GuiGuts: a text version and an HTML version. Then each of these files is edited as necessary to produce the final versions. Both are sent to the PPV or are uploaded. When these files are being processed at PG, an epub is generated.

With RST, the process starts the same. After checks have been made only one file is saved, the plain text one. It need not even have been rewrapped, because it will be marked up with RST syntax. Once marked up, that single file (and any images) goes forward. Once reaching the whitewasher, the marked-up source file is used to generate all outputs posted by DP, including text, HTML, and Epub. The user doesn't need to know anything about HTML or Epub and doesn't have to worry about line lengths and rewrapping. All of that is done automatically during the generation process. The user only has to get one file right; the PPVer only has to check one file; the WWer deals with one file for production and errata.

So what is this "markup" for RST? It's very simple. For example, for a chapter header traditionally the PPer needed to ensure there were four spaces before and two after in text and that all the code was in place, including links, in HTML. With RST, the PPer simply underlines the chapter title with a series of equal signs. That's it. RST knows it's a chapter header, displays it correctly in text and HTML, build a Table of Contents entry for it, and creates a <div> there for Epub segmentation.

RST is described as a what-you-see-is-what-you-get markup syntax and parser system. Most markup is as straightforward as the chapter header example. A quick look here shows common markup examples. A more detailed manual is here. Guiguts (guiguts-win-epub-1.0.0.zip) comes bundled with the ePubmaker software to convert RST files to various formats; see here.

Applicability

Though RST is compelling for many books, it is not for every book and it is not for every post-processor. It does have support for paragraphs, subdivisions and headers; italics, small-cap, bold; poetry; images; footnotes; lists and tables and other common constructions. However there are some constructions, such as sidenotes and visible page numbers, that are not currently available in RST. If a book requires semantic markup not in RST, that book should be processed with traditional post-processing methods. For many books, it's all there.

RST is also not for every post-processor. If a PPer wants to maintain full control over all the presentational aspects of the book, they will not be happy with RST. The RST parser makes decisions about how a blockquote will look, or how a footnote will be rendered, or what a table of contents looks like. RST is primarily semantic markup describing what something is instead of presentational markup describing what something looks like. That is by design and is at the heart of why a single markup source file can generate so many different output formats. Each generator interprets what an element is and renders it according to the format: text, HTML, Epub, PDF, etc.

Process

Anyone can use RST to post-process a suitable book, from the experienced to the brand-new PPer, and anywhere in between. If you are new, or still working towards DU status, working within GuiGuts will ensure that you have a bin file for the PPVer. If you have DU status, using GuiGuts is optional.

Follow regular procedures for checking the file for questionable hyphenation, proofers' notes, checking poetry and block quotes, removing visible page markers, moving illustrations, footnotes, etc.

If you use any of the GuiGuts text checks (Gutcheck, Word Frequency, Jeebies, spell-check routines) run through them prior to converting the file to the RST coding. In Gutcheck, I turn off certain flags, such as, short and long lines; and HTML tags and symbols. The text is not rewrapped and most of the HTML tags will be converted to RST markup.

The major difference between the "traditional" PPer and a RST PPer, is that the RST PPer works with a single-source file and doesn't have to know HTML coding to post-process a book--but the end result is the same, with both producing text and HTML versions. The bonus for the RST PPers is creating the epub at the same time.

link to RST Index Page