Chapter 1 of 2 · 3998 words · ~20 min read

Part 1

[pg!i]

The

Project Gutenberg

RST Manual

[pg!iii]

Contents

Installing EpubMaker Windows Debian PG-RST Classes Classes For Inline Text Classes For Block Text Classes For Front Matter Markup PG-RST Extensions Styles Pagination Table of Contents List of Figures List of Tables Toc-Entry Footnotes Page Numbers Dropcaps Tables PG Metadata Top Boilerplate Metadata Directive Bottom Boilerplate PG-RST Best Practices Examples and Tests Section 3.1 Section 3.2 Section 3.3

[pg!v]

List of Tables

Classes For Inline Text I Classes For Inline Text II Classes For Inline Text III Classes For Block Text Classes For Front Matter Markup Directives For Pagination Footnote Positions Support for dropcaps in output formats Demo Table Truth table for “and” Fields In the PG Scheme Fields In the DC Scheme Fields In the MARCREL Scheme Fields Without Scheme _TABLE 8_ Types of Computers Used in the Systems Reported

[pg!vii]

List of Figures

Richard and Drucilla Martin

[pg!1]

Installing EpubMaker

EpubMaker is Project Gutenberg’s file converter. It can convert from PG-RST to HTML, EPUB, PDF and plain text.

Windows

Prerequisites

1. Install Python.

Assuming you don’t have python yet. If you have either version 2.6 or 2.7 already installed, skip this.

From http://www.python.org/download/releases/2.7/ download the Windows x86 MSI Installer (2.7) and run it.

Select all the default options and install.

2. Install Python Setuptools.

From http://pypi.python.org/pypi/setuptools download setuptools-0.6c11.win32-py2.7.exe (or any newer version) and run it.

If you are using python 2.6 get the setuptools for 2.6.

3. Install Groff. (You can skip this step if you don’t want to generate plain text files.)

From http://gnuwin32.sourceforge.net/packages/groff.htm download _Complete package, except sources - Setup_ (groff-1.20.1-setup.exe) and run it.

Select all the default options and install.

4. Install TexLive. (You can skip this step if you don’t want to generate PDF files.)

Go to http://mirror.ctan.org/systems/texlive/tlnet and download the file install-tl.zip. Then say:

> unzip install−tl.zip > cd install−tl* > install−tl

This will open the TeX Live installation wizard. Follow the instructions. When in doubt use the defaults.

This will take quite a while. (3 hours on an old Dell Vostro 1000 laptop. It installs about 2.5 GB in 93,000 files.) If you experience download problems, restart the wizard: it will resume the download where it left off.

Long installation instructions can be found at http://www.tug.org/texlive/doc/texlive-en/texlive-en.html#x1-150003

5. Install HTML Tidy. (You can skip this step if you only want to process RST files and don’t want to build EPUBs from HTML input.)

If you are a post-processor you already have this.

http://tidy.sourceforge.net/

6. Update your PATH.

Start | Control Panel | System | Advanced | Environment Variables. Click "Path" in the User variables at the top. Click "Edit"

If the field is empty just enter (all in one line):

C:\Python27; C:\Python27\Scripts; C:\Program Files\GnuWin32\bin;

If the field contains data, go to the end of that data and add a semicolon if there isn’t one already and then add the string above.

Click Ok three times.

EpubMaker

1. At the command prompt run:

> easy_install epubmaker

2. Test your installation:

> epubmaker −−help > epubmaker https://www.gutenberg.org/masters/rst/181/181.rst

Debian

Prerequisites

(Does not work with python 3 yet. If your distribution uses python 3 as default (not likely!), you’ll have to parallel install python 2.6 or 2.7.)

# apt−get install python python−setuptools python−lxml # apt−get install groff tidy # apt−get install libpng−dev libjpeg−dev libfreetype6−dev

Note: To get PDF generation to work, you have to use TeX Live version 2009-11 or newer. You can get those from debian testing or unstable. If don’t want to switch from debian stable, you have to install TeX Live manually.

If you are on testing or unstable:

# apt−get install texlive texlive−latex−extra texlive−xetex # apt−get install ttf−linux−libertine ttf−dejavu

Else, to install TeX Live manually, go to http://mirror.ctan.org/systems/texlive/tlnet and download the file install-tl-unx.tar.gz. Unpack it. Then:

# cd /path/where/unpacked # perl install−tl −gui

Long installation instructions can be found at http://www.tug.org/texlive/doc/texlive-en/texlive-en.html#x1-150003

EpubMaker

# easy_install epubmaker

Kindlegen

(Optional: Used only to make Kindle files):

$ wget http://s3.amazonaws.com/kindlegen/kindlegen_linux_2.6_i386_v1.2.tar.gz $ tar −xzf kindlegen_linux_2.6_i386_v1.2.tar.gz

PG-RST Classes

A list of classes you can use in PG-RST.

Classes For Inline Text

These classes have an effect on inline text. If you put them on a block, all inline contents of the block will be rendered accordingly.

Classes For Inline Text I

──────────────────────────────────────────────── Class Explanation ──────────────────────────────────────────────── italics Switch to italic font. ──────────────────────────────────────────────── bold Switch to boldface. ──────────────────────────────────────────────── small-caps Switch to small capitals. ──────────────────────────────────────────────── gesperrt Switch to gesperrt (extended letter spacing). ──────────────────────────────────────────────── antiqua Switch to antiqua. ──────────────────────────────────────────────── monospaced Switch to monospaced font. ────────────────────────────────────────────────

Classes For Inline Text II

──────────────────────────────────────────────── Class Explanation ──────────────────────────────────────────────── smaller Switch to smaller font. ──────────────────────────────────────────────── larger Switch to larger font. ──────────────────────────────────────────────── xx-small Switch to smallest font. ──────────────────────────────────────────────── x-small Switch to very small font. ──────────────────────────────────────────────── small Switch to small font. ──────────────────────────────────────────────── medium Switch to normal font size. ──────────────────────────────────────────────── large Switch to large font. ──────────────────────────────────────────────── x-large Switch to very large font. ──────────────────────────────────────────────── xx-large Switch to largest font. ────────────────────────────────────────────────

Classes For Inline Text III

──────────────────────────────────────────────── Class Explanation ──────────────────────────────────────────────── red Switch to red font. ──────────────────────────────────────────────── green Switch to green font. ──────────────────────────────────────────────── blue Switch to blue font. ──────────────────────────────────────────────── yellow Switch to yellow font. ──────────────────────────────────────────────── white Switch to white font. ──────────────────────────────────────────────── gray Switch to gray font. ──────────────────────────────────────────────── black Switch to black font. ────────────────────────────────────────────────

Classes For Block Text

These classes have an effect on block text. Please do not confuse the alignment of the block with the alignment of the text in the block. Eg. a table can be centered, while the text inside the table is left-aligned. The alignment of the block is set with the align option.

Classes For Block Text

───────────────────────────────────────────────────────── Class Explanation ───────────────────────────────────────────────────────── left Left-aligns the text in the block. ───────────────────────────────────────────────────────── center Centers the text in the block. ───────────────────────────────────────────────────────── right Right-aligns the text in the block. ───────────────────────────────────────────────────────── justify Justifies the text in the block. ───────────────────────────────────────────────────────── white-space-pre-line Preserves newlines. ─────────────────────────────────────────────────────────

Classes For Front Matter Markup

EpubMaker includes a few classes to markup front matter. While it is not necessary to do this, it adds value. In future the PG catalog might automatically extract not only the cover page but also the title page, verso, etc.

Classes For Front Matter Markup

───────────────────────────────────────────────── Class Explanation ───────────────────────────────────────────────── coverpage The cover page. ───────────────────────────────────────────────── frontispiece The frontispiece. ───────────────────────────────────────────────── titlepage The title page. ───────────────────────────────────────────────── verso The title page verso. ───────────────────────────────────────────────── dedication The dedication page. ───────────────────────────────────────────────── plainpage A general class for page. ─────────────────────────────────────────────────

Use these classes on a container. These classes already insert page breaks before the container so you need not insert page breaks on your own.

.. container:: titlepage

| Pride and Prejudice | | Written by Jane Austen.

PG-RST Extensions

You can create custom roles based on the existing ones. This is how you create and then use custom roles.

.. role:: small−caps :class: small−caps

This text is in :small−caps:`Small Caps`.

This text is in _Small Caps_.

You can attach more than one class to a role:

.. role:: big−and−bold :class: x−large bold

This text is :big−and−bold:`big and bold`.

This text is *big and bold*.

Styles

You can redefine the rendering of elements:

.. style:: emphasis :class: gesperrt

Now *emphasis* will be rendered as gesperrt.

Now emphasis__ will be rendered as gesperrt.

.. style:: strong :class: small−caps

And **Strong Emphasis** will be rendered as small−caps.

And *_Strong Emphasis_* will be rendered as small-caps.

.. style:: strong :class: small−caps x−large bold

And **Strong Emphasis** will be rendered as big bold small−caps.

And *_Strong Emphasis_* will be rendered as big bold small-caps.

.. style:: literal :class: red

``literally red``

.. style:: superscript :class: green

:superscript:`sup`\ er

.. style:: title_reference :class: blue

:title−reference:`Hamlet` and `Othello`.

literally red

super

_Hamlet_ and _Othello_.

You can semantically markup foreign text:

.. role:: french :class: language−fr italics

:french:`Pas de double` is the French for "father of twins".

_Pas de double_ is the French for "father of twins".

Pagination

Pagination is important if you generate PDFs. See the Directives For Pagination Table.

Directives For Pagination

───────────────────────────────────────────────────────────────── Directive Explanation ───────────────────────────────────────────────────────────────── clearpage This directive inserts a page break. ───────────────────────────────────────────────────────────────── cleardoublepage This directive inserts page breaks so that the next item starts on a right-hand page. ───────────────────────────────────────────────────────────────── vfill (PDF only.)

This directive generates ‘elastic´ vertical space. This space expands to all of the free space on one page. If you use this more than once on a page, the free space is equally divided among all invocations.

To vertically align an item to the bottom, use vfill before that item.

To vertically align an item about 1/3 of the page use vfill once before the item and twice after the item. ───────────────────────────────────────────────────────────────── frontmatter (PDF only.)

Put this directive at the start of your book.

The pgheader directive uses this directive internally, so you can omit frontmatter whenever you use pgheader.

This directive turns on roman page numbers. ───────────────────────────────────────────────────────────────── mainmatter (PDF only.)

Put this directive after the table of contents and before the first chapter.

This directive switches from roman page numbering to arabic page numbering and resets the page counter. ───────────────────────────────────────────────────────────────── backmatter (PDF only.)

Put this directive before appendices or indices. ─────────────────────────────────────────────────────────────────

Table of Contents

Use the RST contents directive to automatically generate a table of contents.

N.B. You may also provide a table of contents manually.

In PG-RST the contents directive requires you to specify an argument or the local option.

The local option displays a local table of contents, containing only the sub-sections of the section in which it is declared.

The page-numbers option displays the original page number in the TOC.

.. contents:: A TOC With Page Numbers :depth: 2 :page−numbers:

A TOC With Page Numbers

Installing EpubMaker .............................................. Windows ......................................................... Debian .......................................................... PG-RST Classes .................................................... Classes For Inline Text ......................................... Classes For Block Text .......................................... Classes For Front Matter Markup ................................. PG-RST Extensions ................................................. Styles .......................................................... Pagination ...................................................... Table of Contents ............................................... List of Figures ................................................. List of Tables .................................................. Toc-Entry ....................................................... Footnotes ....................................................... Page Numbers .................................................... Dropcaps ........................................................ Tables .......................................................... PG Metadata ....................................................... Top Boilerplate ................................................. Metadata Directive .............................................. Bottom Boilerplate .............................................. PG-RST Best Practices ............................................. Examples and Tests ................................................ Section 3.1 ..................................................... Section 3.2 ..................................................... Section 3.3 .....................................................

List of Figures

Use the lof directive to generate a list of figures automatically.

N.B. You may also provide a list of figures manually.

.. lof:: A List of Figures :page−numbers: :backlinks: none

A List of Figures

Richard and Drucilla Martin .......................................

List of Tables

Use the lot directive to generate a list of tables.

N.B. You may also provide a list of tables manually.

.. lot:: A List of Tables :page−numbers: :backlinks: none

A List of Tables

Classes For Inline Text I ......................................... Classes For Inline Text II ........................................ Classes For Inline Text III ....................................... Classes For Block Text ............................................ Classes For Front Matter Markup ................................... Directives For Pagination ......................................... Footnote Positions ................................................ Support for dropcaps in output formats ............................ Demo Table ........................................................ Truth table for “and” ............................................. Fields In the PG Scheme ........................................... Fields In the DC Scheme ........................................... Fields In the MARCREL Scheme ...................................... Fields Without Scheme ............................................. _TABLE 8_ Types of Computers Used in the Systems Reported .........

Toc-Entry

Use the toc-entry directive to:

- provide an alternate toc entry - suppress a toc entry, or - switch toc gathering on or off.

A toc-entry with argument sets the argument as toc entry for the next section, figure or table.

A toc-entry without argument suppresses the toc entry for the next section, figure or table.

Use the depth option to set the depth up to which section titles are gathered for the toc. A depth of 0 switches toc gathering off.

.. toc−entry:: An Alternative Caption

Footnotes

Always define footnotes right after the paragraph they are referenced.

Positioning of footnotes

───────────────────────────────────────────────── Format Position ───────────────────────────────────────────────── HTML Collected under the footnotes directive. ───────────────────────────────────────────────── EPUB Idem. ───────────────────────────────────────────────── TXT Where they are defined. ───────────────────────────────────────────────── PDF At the bottom of the current page. ─────────────────────────────────────────────────

To collect the footnotes use the footnotes directive. This directive will output a section with title and all footnotes in the document will be moved inside the section.

In PDF and TXT formats the footnotes directive will do nothing.¹

Test²³ .

¹ Not even print the section title.

.. footnotes:: Footnotes :class: smaller

² Another footnote, to test how multiple footnotes⁴ stack on one page.

³ Later editions continued as follows:

When the sands are all dry, he is gay as a lark, And will talk in contemptuous tones of the Shark, But, when the tide rises and sharks are around, His voice has a timid and tremulous sound.

⁴ Gibbon test. A footnote inside a footnote.

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 end of the word.

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. See page [pg 43]_.

See page [pg iii]_.

Dropcaps

You can insert dropcaps with the dropcap directive. You can use either an enlarged character or an image as dropcap. You can also specify a span of character that should be set in small-caps after the dropcap initial.

Support for dropcaps in output formats

──────────────────────────────────────────────────── Format Letter Image ──────────────────────────────────────────────────── HTML enlarged and resized and dropped dropped ──────────────────────────────────────────────────── EPUB enlarged on resized on baseline baseline ──────────────────────────────────────────────────── TXT normal size alt text ──────────────────────────────────────────────────── PDF enlarged and resized and dropped⁵ dropped⁵ ────────────────────────────────────────────────────

⁵ _Warning:_ If a paragraph with a dropcap gets page-broken the dropcap may stick into the page bottom. Avoid dropcaps unless you are sure that you are at the top of a page, like at a chapter start.

The first argument (mandatory) states the character(s) to replace with caps. It must match the beginning of the next paragraph.

The second (optional) argument states the characters to replace with small-caps. It must also match the beginning of the next paragraph.

.. clearpage::

.. dropcap:: L Lorem ipsum :lines: 4 :indents: −1.25em 0.5em

Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.

L_orem ipsum_ dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. 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 lines option (PDF only) specifies how many lines the dropcap should span. Default is 2.

The indents option (PDF only) can specifiy up to 2 length values. The first one is the indent of the first line, the second one the indent of the following lines. The indent is calculated from the right border of the dropcap letter. Defaults are 0em and 0.5em.

The image option specifies the image url. In plain text and EPUB the image will not be used.

.. clearpage::

.. dropcap:: G :image: images/G.png :lines: 4

Gorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.

__orem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.

Tables

Be careful with tables because the table support of many ereaders is weak or nil.

Tables also support these options:

width Makes the table that wide.

widths A space-separated list of unitless values, each specifying the relative width of one table column.

If you don’t use the option widths, the column widths are calculated from the layout of the table in your source file.

aligns Horizontally align the columns.

A space-separated list of alignments, each specifying the alignment of one column.

Valid alignments values are: left, center, right and justify.

vertical-aligns Vertically align the columns.

A space-separated list of vertical alignments, each specifying the alignment of one column.

Valid alignments values are: top, middle, and bottom.

Note: vertical alignment is fully supported in HTML only. Other formats may support it in varying degrees.

summary (HTML only.) Puts a summary attribute on the table element.

These are the extra classes supported by PG-RST:

norules Omits the rules between table rows. (Not the rule between header and body nor the rules at the top and bottom of the table.)

Use this class when the eye can follow the table rows without the aid of rules.

.. table:: Demo Table :width: 100% :align: center :widths: 3 1 1 1 :aligns: justify justify center right :vertical−aligns: top middle bottom top :summary: This table contains valuable data.

Demo Table

────────────────────────────────────────────────────────────────── Header row, column 1 (header Justified Centered Price ($) rows optional) ────────────────────────────────────────────────────────────────── row 1 column column 1.23 ────────────────────────────────────────────────────────────────── row 2 col col col 45.67 col col col col col ────────────────────────────────────────────────────────────────── row 3 Cells may span columns. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam sed diam voluptua. At vero eos accusam et justo duo dolores et rebum. ────────────────────────────────────────────────────────────────── Cells may span rows and columns. Lorem Cells may row 4 ipsum dolor sit amet, consetetur span ──────────── adipiscing. rows. row 5 ──────────────────────────────────────────────────────────────────

.. table:: Truth table for “and” :class: norules :align: center :width: 50%

===== ===== ========= A B A and B ===== ===== ========= False False False True False False False True False True True True ===== ===== =========

Truth table for “and”

───────────────────────────────── A B A and B ───────────────────────────────── False False False ───────────────────────────────── True False False ───────────────────────────────── False True False ───────────────────────────────── True True True ─────────────────────────────────

PG Metadata

Top Boilerplate

This section explains the PG boilerplate that you must put at the top of your PG-RST file.

It looks like this:

.. −*− encoding: utf−8 −*− (1)

.. meta:: (2) :PG.Id: 181 :PG.Title: Very Short Title :PG.Released: 2010−11−25 :PG.Rights: Public Domain :PG.Producer: Woody Guthrie :PG.Producer: Pete Seeger :PG.Producer: The Almanac Singers :PG.Credits: This file was produced from images stolen from the Louvre. :DC.Creator: Jane Austen :MARCREL.edt: Mark Twain :MARCREL.ill: Édouard Manet :DC.Title: Full Title Statement :DC.Language: en :DC.Language: fr :DC.Language: de :DC.Created: 1900 :coverpage: images/cover.jpg

=========== Short Title (3) ===========

.. pgheader:: (4)

(1) Insert this line verbatim. It must be the first line in the text.⁶ This tells the converter to use UTF-8 encoding and is also recognized by many editors. (2) The metadata directive: see section below. (3) This will be the first line of the generated files. It should say: “The Project Gutenberg Ebook of Title” or just “Title”. Use ’=’ above and below the title. (4) This directive inserts the PG header as generated from the metadata.

⁶ A unicode BOM is allowed before this. In fact most Windows editors will add a BOM without asking you.

Metadata Directive

The metadata directive contains all data that is used to generate the PG header and the PG catalog entry.

The scheme is the part before the dot.

PG Scheme

The PG scheme holds data that is relevant to Project Gutenberg only.

Fields In the PG Scheme

──────────────────────────────────────────────── Name Contents ──────────────────────────────────────────────── PG.Id The ebook number. ──────────────────────────────────────────────── PG.Released The PG release date in YYYY-MM-DD format. ──────────────────────────────────────────────── PG.Rights Either ’Public Domain’ or ’Copyrighted’. ──────────────────────────────────────────────── PG.Title A much shortened form of the title. Used in the PG boilerplate in the lines that say: “Start of this PG ebook …” and “End of this PG ebook …”. ──────────────────────────────────────────────── PG.Producer A personal name or organization that helped produce this text. This field may appear more than once. Don’t put more than one name into one field. Repeat the field if necessary. ──────────────────────────────────────────────── PG.Credits A line acknowledging the source of the images or other stuff. ────────────────────────────────────────────────

DC Scheme

This scheme holds standard Dublincore stuff and is used by many search engines and the PG cataloguing software.

Fields In the DC Scheme

──────────────────────────────────────────────── Name Contents ──────────────────────────────────────────────── DC.Creator Author. A personal name or organization that created the text. May appear more than once. Don’t put more than one name into one field. Repeat the field if necessary. ──────────────────────────────────────────────── DC.Title The full title statement as found on the book’s title page. ──────────────────────────────────────────────── DC.Language The 2 or 3 letter code for all languages used for substantial portions of the text. May appear more than once. Don’t put more than one code into one field. Repeat the field if necessary. The languages listed here are indicative for the catalog and do not set the text language and hyphenation rules. Use the option class language-<language-code> for that. ──────────────────────────────────────────────── DC.Created The year of original publication if known. ────────────────────────────────────────────────

MARCREL Scheme

This is used to record contributors to the text. All these fields may appear more than once. Don’t put more than one name into one field. Repeat the field if necessary.

Fields In the MARCREL Scheme

──────────────────────────────────────────────── Name Contents ──────────────────────────────────────────────── MARCREL.edt Editor ──────────────────────────────────────────────── MARCREL.ill Illustrator ──────────────────────────────────────────────── MARCREL.trl Translator ──────────────────────────────────────────────── MARCREL.* See the full list of MARC relator codes. ────────────────────────────────────────────────

No Scheme