Title: The Project Gutenberg RST ManualContaining a full treatise about the advantages of usingreStructuredText for ebook production along a description of itsmain properties and many instructive examples of its application⁂

List of Figures

PG-RST is a plain text markup language, ie. a language that tries to
do markup without using tags. (In contrast HTML is a markup language
that uses tags.) The amount of textual features it can express is
limited (compared to HTML+CSS). It is not aimed at producing complex or
technical publications.

PG-RST is based on standard RST. It extends standard RST’s
functionality especially in the realm of typography, but some features
of standard RST are not (yet) implemented.

epubmaker is the software that converts PG-RST into a multitude of
output formats. It is called epubmaker for historical reasons: It
started as a tool to convert HTML into EPUB. Currently it can convert
PG-RST into HTML4, EPUB2, Kindle7, PDF, and plain text. Support for
HTML5, EPUB3 and Kindle8 are forthcoming.

This file only describes the differences between PG-RST and standard
RST.

Everything not described here can be found in the standard RST
documentation. You should probably consult the standard RST
documentation first, then come back here to see what changes PG-RST
introduced over standard RST.

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.

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.

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.

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.

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.

Footnotes must be defined in the order they are referenced.
Define a footnote where it should appear in the plain text file.
In HTML all footnotes get moved to the footnote section.
In PDF they appear at the bottom of the current page.

To collect the footnotes at the end of the text in HTML use the
footnotes directive. (In PDF and TXT formats the
footnotes directive will do nothing.1)

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.

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.

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 0 em and 0.5 em.

The image option specifies the image url.

The raise option (PDF only) moves the dropped capital up (if
positive) or down (if negative). Values must be between 1 and -1.
Useful with capitals like J or Q which have a positive depth,
(default=0).

DC Scheme

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 scheme is used to record contributions to the text, that are more
narrow than Dublin Core allows you to specify.

All these fields may appear more than once. Don’t put more than one
name into one field. Repeat the field if necessary.

Kingston — Instructive remarks on early English history —
Instructive observations on carved oak and life in general — Sad
case of Stivvings, junior — Musings on antiquity — I forget that I
am steering — Interesting result — Hampton Court Maze — Harris as a
guide.

A similar accident is said to have happened to a Benedictine
monk in the eleventh century and to others attempting like
exploits in after years. A fall and a broken leg seem to have
been the usual results of these early attempts at aerial flight.

Sincerely yours,John Thompson

This is the line following the letter.

A parsed-literal that is visible only in non-image outputs:

An italicized paragraph with a non-italicized word.

An italicized container with a non-italicized word.

A normal paragraph.

more … more … more … more … more … more … more … more … more … more …
more … more … more … more … more … more … more … more … more … more …
more … more … more … more … more … more … more … more … more … more …
more … more … more … more … more … more … more … more … more … more …
more … more … more … more … more … more … more … more … more … more …
more … more … more … more … more … more … more … more … more … more …
more … more … more … more … more … more …

A Word from Project Gutenberg

Creating the works from public domain print editions means that no one
owns a United States copyright in these works, so the Foundation (and
you!) can copy and distribute it in the United States without
permission and without paying copyright royalties. Special rules, set
forth in the General Terms of Use part of this license, apply to
copying and distributing Project Gutenberg™ electronic works to
protect the Project Gutenberg™ concept and trademark. Project
Gutenberg is a registered trademark, and may not be used if you charge
for the eBooks, unless you receive specific permission. If you do not
charge anything for copies of this eBook, complying with the rules is
very easy. You may use this eBook for nearly any purpose such as
creation of derivative works, reports, performances and research.
They may be modified and printed and given away – you may do
practically anything with public domain eBooks. Redistribution is
subject to the trademark license, especially commercial
redistribution.

The Full Project Gutenberg License

Please read this before you distribute or use this work.

To protect the Project Gutenberg™ mission of promoting the free
distribution of electronic works, by using or distributing this work
(or any other work associated in any way with the phrase “Project
Gutenberg”), you agree to comply with all the terms of the Full
Project Gutenberg™ License available with this file or online at
http://www.gutenberg.org/license.

Section 1. General Terms of Use & Redistributing Project Gutenberg™ electronic works

1.A. By reading or using any part of this Project Gutenberg™
electronic work, you indicate that you have read, understand, agree to
and accept all the terms of this license and intellectual property
(trademark/copyright) agreement. If you do not agree to abide by all
the terms of this agreement, you must cease using and return or
destroy all copies of Project Gutenberg™ electronic works in your
possession. If you paid a fee for obtaining a copy of or access to a
Project Gutenberg™ electronic work and you do not agree to be bound by
the terms of this agreement, you may obtain a refund from the person
or entity to whom you paid the fee as set forth in paragraph 1.E.8.

1.B. “Project Gutenberg” is a registered trademark. It may only be
used on or associated in any way with an electronic work by people who
agree to be bound by the terms of this agreement. There are a few
things that you can do with most Project Gutenberg™ electronic works
even without complying with the full terms of this agreement. See
paragraph 1.C below. There are a lot of things you can do with Project
Gutenberg™ electronic works if you follow the terms of this agreement
and help preserve free future access to Project Gutenberg™ electronic
works. See paragraph 1.E below.

1.C. The Project Gutenberg Literary Archive Foundation (“the
Foundation” or PGLAF), owns a compilation copyright in the collection
of Project Gutenberg™ electronic works. Nearly all the individual
works in the collection are in the public domain in the United
States. If an individual work is in the public domain in the United
States and you are located in the United States, we do not claim a
right to prevent you from copying, distributing, performing,
displaying or creating derivative works based on the work as long as
all references to Project Gutenberg are removed. Of course, we hope
that you will support the Project Gutenberg™ mission of promoting free
access to electronic works by freely sharing Project Gutenberg™ works
in compliance with the terms of this agreement for keeping the Project
Gutenberg™ name associated with the work. You can easily comply with
the terms of this agreement by keeping this work in the same format
with its attached full Project Gutenberg™ License when you share it
without charge with others.

1.D. The copyright laws of the place where you are located also
govern what you can do with this work. Copyright laws in most
countries are in a constant state of change. If you are outside the
United States, check the laws of your country in addition to the terms
of this agreement before downloading, copying, displaying, performing,
distributing or creating derivative works based on this work or any
other Project Gutenberg™ work. The Foundation makes no
representations concerning the copyright status of any work in any
country outside the United States.

1.E. Unless you have removed all references to Project Gutenberg:

1.E.1. The following sentence, with active links to, or other
immediate access to, the full Project Gutenberg™ License must appear
prominently whenever any copy of a Project Gutenberg™ work (any work
on which the phrase “Project Gutenberg” appears, or with which the
phrase “Project Gutenberg” is associated) is accessed, displayed,
performed, viewed, copied or distributed:

This eBook is for the use of anyone anywhere at no cost and with
almost no restrictions whatsoever. You may copy it, give it away or
re-use it under the terms of the Project Gutenberg License included
with this eBook or online at http://www.gutenberg.org

1.E.2. If an individual Project Gutenberg™ electronic work is
derived from the public domain (does not contain a notice indicating
that it is posted with permission of the copyright holder), the work
can be copied and distributed to anyone in the United States without
paying any fees or charges. If you are redistributing or providing
access to a work with the phrase “Project Gutenberg” associated with
or appearing on the work, you must comply either with the requirements
of paragraphs 1.E.1 through 1.E.7 or obtain permission for the use of
the work and the Project Gutenberg™ trademark as set forth in
paragraphs 1.E.8 or 1.E.9.

1.E.3. If an individual Project Gutenberg™ electronic work is
posted with the permission of the copyright holder, your use and
distribution must comply with both paragraphs 1.E.1 through 1.E.7 and
any additional terms imposed by the copyright holder. Additional terms
will be linked to the Project Gutenberg™ License for all works posted
with the permission of the copyright holder found at the beginning of
this work.

1.E.4. Do not unlink or detach or remove the full Project
Gutenberg™ License terms from this work, or any files containing a
part of this work or any other work associated with Project
Gutenberg™.

1.E.5. Do not copy, display, perform, distribute or redistribute
this electronic work, or any part of this electronic work, without
prominently displaying the sentence set forth in paragraph 1.E.1 with
active links or immediate access to the full terms of the Project
Gutenberg™ License.

1.E.6. You may convert to and distribute this work in any binary,
compressed, marked up, nonproprietary or proprietary form, including
any word processing or hypertext form. However, if you provide access
to or distribute copies of a Project Gutenberg™ work in a format other
than “Plain Vanilla ASCII” or other format used in the official
version posted on the official Project Gutenberg™ web site
(http://www.gutenberg.org), you must, at no additional cost, fee or
expense to the user, provide a copy, a means of exporting a copy, or a
means of obtaining a copy upon request, of the work in its original
“Plain Vanilla ASCII” or other form. Any alternate format must include
the full Project Gutenberg™ License as specified in paragraph 1.E.1.

1.E.7. Do not charge a fee for access to, viewing, displaying,
performing, copying or distributing any Project Gutenberg™ works
unless you comply with paragraph 1.E.8 or 1.E.9.

1.E.8. You may charge a reasonable fee for copies of or providing
access to or distributing Project Gutenberg™ electronic works provided
that

You pay a royalty fee of 20% of the gross profits you derive from
the use of Project Gutenberg™ works calculated using the method you
already use to calculate your applicable taxes. The fee is owed to
the owner of the Project Gutenberg™ trademark, but he has agreed to
donate royalties under this paragraph to the Project Gutenberg
Literary Archive Foundation. Royalty payments must be paid within 60
days following each date on which you prepare (or are legally
required to prepare) your periodic tax returns. Royalty payments
should be clearly marked as such and sent to the Project Gutenberg
Literary Archive Foundation at the address specified in Section 4,
“Information about donations to the Project Gutenberg Literary
Archive Foundation.”

You provide a full refund of any money paid by a user who notifies
you in writing (or by e-mail) within 30 days of receipt that s/he
does not agree to the terms of the full Project Gutenberg™
License. You must require such a user to return or destroy all
copies of the works possessed in a physical medium and discontinue
all use of and all access to other copies of Project Gutenberg™
works.

You provide, in accordance with paragraph 1.F.3, a full refund of
any money paid for a work or a replacement copy, if a defect in the
electronic work is discovered and reported to you within 90 days of
receipt of the work.

You comply with all other terms of this agreement for free
distribution of Project Gutenberg™ works.

1.E.9. If you wish to charge a fee or distribute a Project
Gutenberg™ electronic work or group of works on different terms than
are set forth in this agreement, you must obtain permission in writing
from both the Project Gutenberg Literary Archive Foundation and
Michael Hart, the owner of the Project Gutenberg™ trademark. Contact
the Foundation as set forth in Section 3. below.

1.F.

1.F.1. Project Gutenberg volunteers and employees expend
considerable effort to identify, do copyright research on, transcribe
and proofread public domain works in creating the Project Gutenberg™
collection. Despite these efforts, Project Gutenberg™ electronic
works, and the medium on which they may be stored, may contain
“Defects,” such as, but not limited to, incomplete, inaccurate or
corrupt data, transcription errors, a copyright or other intellectual
property infringement, a defective or damaged disk or other medium, a
computer virus, or computer codes that damage or cannot be read by
your equipment.

1.F.2. LIMITED WARRANTY, DISCLAIMER OF DAMAGES – Except for the
“Right of Replacement or Refund” described in paragraph 1.F.3, the
Project Gutenberg Literary Archive Foundation, the owner of the
Project Gutenberg™ trademark, and any other party distributing a
Project Gutenberg™ electronic work under this agreement, disclaim all
liability to you for damages, costs and expenses, including legal
fees. YOU AGREE THAT YOU HAVE NO REMEDIES FOR NEGLIGENCE, STRICT
LIABILITY, BREACH OF WARRANTY OR BREACH OF CONTRACT EXCEPT THOSE
PROVIDED IN PARAGRAPH 1.F.3. YOU AGREE THAT THE FOUNDATION, THE
TRADEMARK OWNER, AND ANY DISTRIBUTOR UNDER THIS AGREEMENT WILL NOT BE
LIABLE TO YOU FOR ACTUAL, DIRECT, INDIRECT, CONSEQUENTIAL, PUNITIVE OR
INCIDENTAL DAMAGES EVEN IF YOU GIVE NOTICE OF THE POSSIBILITY OF SUCH
DAMAGE.

1.F.3. LIMITED RIGHT OF REPLACEMENT OR REFUND – If you discover a
defect in this electronic work within 90 days of receiving it, you can
receive a refund of the money (if any) you paid for it by sending a
written explanation to the person you received the work from. If you
received the work on a physical medium, you must return the medium
with your written explanation. The person or entity that provided you
with the defective work may elect to provide a replacement copy in
lieu of a refund. If you received the work electronically, the person
or entity providing it to you may choose to give you a second
opportunity to receive the work electronically in lieu of a refund. If
the second copy is also defective, you may demand a refund in writing
without further opportunities to fix the problem.

1.F.4. Except for the limited right of replacement or refund set
forth in paragraph 1.F.3, this work is provided to you ‘AS-IS,’ WITH
NO OTHER WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
LIMITED TO WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PURPOSE.

1.F.5. Some states do not allow disclaimers of certain implied
warranties or the exclusion or limitation of certain types of
damages. If any disclaimer or limitation set forth in this agreement
violates the law of the state applicable to this agreement, the
agreement shall be interpreted to make the maximum disclaimer or
limitation permitted by the applicable state law. The invalidity or
unenforceability of any provision of this agreement shall not void the
remaining provisions.

1.F.6. INDEMNITY – You agree to indemnify and hold the Foundation,
the trademark owner, any agent or employee of the Foundation, anyone
providing copies of Project Gutenberg™ electronic works in accordance
with this agreement, and any volunteers associated with the
production, promotion and distribution of Project Gutenberg™
electronic works, harmless from all liability, costs and expenses,
including legal fees, that arise directly or indirectly from any of
the following which you do or cause to occur: (a) distribution of this
or any Project Gutenberg™ work, (b) alteration, modification, or
additions or deletions to any Project Gutenberg™ work, and (c) any
Defect you cause.

Section 2. Information about the Mission of Project Gutenberg™

Project Gutenberg™ is synonymous with the free distribution of
electronic works in formats readable by the widest variety of
computers including obsolete, old, middle-aged and new computers. It
exists because of the efforts of hundreds of volunteers and donations
from people in all walks of life.

Volunteers and financial support to provide volunteers with the
assistance they need, is critical to reaching Project Gutenberg™’s
goals and ensuring that the Project Gutenberg™ collection will remain
freely available for generations to come. In 2001, the Project
Gutenberg Literary Archive Foundation was created to provide a secure
and permanent future for Project Gutenberg™ and future generations. To
learn more about the Project Gutenberg Literary Archive Foundation and
how your efforts and donations can help, see Sections 3 and 4 and the
Foundation web page at http://www.pglaf.org .

The Project Gutenberg Literary Archive Foundation is a non profit
501(c)(3) educational corporation organized under the laws of the
state of Mississippi and granted tax exempt status by the Internal
Revenue Service. The Foundation’s EIN or federal tax identification
number is 64-6221541. Its 501(c)(3) letter is posted at
http://www.gutenberg.org/fundraising/pglaf . Contributions to the
Project Gutenberg Literary Archive Foundation are tax deductible to
the full extent permitted by U.S. federal laws and your state’s laws.

The Foundation’s principal office is located at 4557 Melan Dr.
S. Fairbanks, AK, 99712., but its volunteers and employees are
scattered throughout numerous locations. Its business office is
located at 809 North 1500 West, Salt Lake City, UT 84116, (801)
596-1887, email business@pglaf.org. Email contact links and up to date
contact information can be found at the Foundation’s web site and
official page at http://www.pglaf.org

Project Gutenberg™ depends upon and cannot survive without wide spread
public support and donations to carry out its mission of increasing
the number of public domain and licensed works that can be freely
distributed in machine readable form accessible by the widest array of
equipment including outdated equipment. Many small donations ($1 to
$5,000) are particularly important to maintaining tax exempt status
with the IRS.

The Foundation is committed to complying with the laws regulating
charities and charitable donations in all 50 states of the United
States. Compliance requirements are not uniform and it takes a
considerable effort, much paperwork and many fees to meet and keep up
with these requirements. We do not solicit donations in locations
where we have not received written confirmation of compliance. To SEND
DONATIONS or determine the status of compliance for any particular
state visit http://www.gutenberg.org/fundraising/donate

While we cannot and do not solicit contributions from states where we
have not met the solicitation requirements, we know of no prohibition
against accepting unsolicited donations from donors in such states who
approach us with offers to donate.

International donations are gratefully accepted, but we cannot make
any statements concerning tax treatment of donations received from
outside the United States. U.S. laws alone swamp our small staff.

Please check the Project Gutenberg Web pages for current donation
methods and addresses. Donations are accepted in a number of other
ways including checks, online payments and credit card donations. To
donate, please visit: http://www.gutenberg.org/fundraising/donate

Professor Michael S. Hart is the originator of the Project Gutenberg™
concept of a library of electronic works that could be freely shared
with anyone. For thirty years, he produced and distributed Project
Gutenberg™ eBooks with only a loose network of volunteer support.

Project Gutenberg™ eBooks are often created from several printed
editions, all of which are confirmed as Public Domain in the
U.S. unless a copyright notice is included. Thus, we do not
necessarily keep eBooks in compliance with any particular paper
edition.

Each eBook is in a subdirectory of the same number as the eBook’s
eBook number, often in several formats including plain vanilla ASCII,
compressed (zipped), HTML and others.

Corrected editions of our eBooks replace the old file and take over
the old filename and etext number. The replaced older file is
renamed. Versions based on separate sources are treated as new
eBooks receiving new filenames and etext numbers.

Most people start at our Web site which has the main PG search
facility:

This Web site includes information about Project Gutenberg™, including
how to make donations to the Project Gutenberg Literary Archive
Foundation, how to help produce our new eBooks, and how to subscribe
to our email newsletter to hear about new eBooks.