RST: PG Extensions to RST

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

EpubMaker generates all the outputs from RST source files at Project Gutenberg (PG). It includes non-standard extensions to RST that are included here for post-processors who want to use them. Using these features assures that the resulting RST source file is only usable at Project Gutenberg and in particular, with EpubMaker. The "in the wild" tools, like rst2html, rst2latex, etc. will not work with RST source files that have added these extensions.

There is an effort to get at least some of these features into the standard RST specification. For many, once that happens these currently non-standard extensions will become viable. For others, these extensions are part of EpubMaker now.

Page Numbers

The sequence "[pg n]" will convert into a page number marker of n. n can be any arabic or roman numeral. The sequence itself will be removed from the text flow leaving a page anchor. There *must* be spaces around the sequence. If the page break is in the middle of a word, join the word and put the sequence at the beginning of the word instead. Example:

  Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam
  nonumy eirmod tempor invidunt [pg 42] ut labore et dolore magna
  aliquyam erat, sed diam voluptua. At vero eos et accusam et justo
  duo dolores [pg xviii] et ea rebum. 

A reference to a page number can be inserted with the sequence "[pg n]_". This will generate a link to the page anchor.

  See page [pg 42]_.

An invisible page number can be inserted with the sequence "[pg!n]".

  Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam
  nonumy eirmod tempor invidunt [pg!43] ut labore et dolore magna
  aliquyam erat, sed diam voluptua. At vero eos et accusam et justo
  duo dolores et ea rebum.

Dropcaps

The first argument is required. It is the character(s) to replace. This argument must match the beginning of the next paragraph.

  .. dropcap:: L

  Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam
  nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam
  erat, sed diam voluptua.

The second argument is optional. It is an image url. If this argument is present, the image will replace the character.

  .. dropcap:: G images/G.png

  Gorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam
  nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam
  erat, sed diam voluptua.

Line Break

Line breaks are for when you absolutely need it.

The instructions are:

define a role:

 .. role:: lb(line-break)
    :before:     

then apply it to a run of text:

 .. figure:: images/image2.jpg
   :align: center
 
   DRUCILLA AND RICHARD MARTIN.
   :lb:`Richard Martin was a slave in Memphis, Tennessee.`
   :lb:`Drucilla Martin was a slave in Giles County, Tennessee.`

--EastEriq 14:29, 9 October 2011 (PDT) This worked until epubmaker 0.3.16, as of now (0.3.17 and 18) gives an error. The recommended construct now is:

 .. role:: lb
     :class: white-space-pre-line

and then

 :lb:`These
 are
 multiple
 lines.`

I've seen that this doesn't work anymore in titles as it did once, e.g. like

   Chapter :lb:`I`
   ===============

TOC entry

Sometimes the TOC entry for a chapter is different that the words used in the chapter heading itself.

 .. toc-entry:: Section III — Beyond the Frontier

 BEYOND THE FRONTIER
 ===================

link to RST Index Page