The Project Gutenberg RST Manual
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/license.
Title: The Project Gutenberg RST Manual
Containing a full treatise about the advantages of using
reStructuredText for ebook production along a description of its
main properties and many instructive examples of its application
⁂
Author: Marcello Perathoner
Release Date: November 25, 2010 [EBook #181]
Reposted: August 15, 2011
Language: English
Character set encoding: UTF-8
*** START OF THIS PROJECT GUTENBERG EBOOK PG-RST MANUAL ***
The Project Gutenberg
RST Manual
Contents
Introduction
PG-RST
epubmaker
RST Documentation
Installing EpubMaker
Windows
Debian
PG-RST Classes
Classes For Inline Text
Classes For Block Text
Classes For Front Matter Markup
PG-RST Extensions
Styles
Forced Line Breaks
Pagination
Table of Contents
List of Figures
List of Tables
Toc-Entry
Footnotes
Page Numbers
Line Numbers
Dropcaps
Tables
PG Metadata
Top Boilerplate
Docinfo section
Bottom Boilerplate
PG-RST Best Practices
Titles
Titlepages
Images
Examples and Tests
Danny Deever
Section 3.1
Section 3.2
Section 3.3
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
List of Figures
Richard and Drucilla Martin
Introduction
PG-RST
PG-RST is a single-source multiple-output markup language well suited
for producing simple fiction books.
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
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.
RST Documentation
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.
The documentation of standard RST can be found here:
Quick reStructuredText
reStructuredText Markup Specification
reStructuredText Directives
reStructuredText Interpreted Text Roles
The newest version of this file can always be found at:
http://pgrst.pglaf.org/publish/181/
Installing EpubMaker
Windows
Prerequisites
1. Install Python.
Skip this step if you already have Python either version 2.6 or 2.7
installed.
From http://www.python.org/download/releases/2.7.2/ download the
Windows x86 MSI Installer (2.7.2) 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 http://pgrst.pglaf.org/publish/181/181−rst.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_v2_4.tar.gz
$ tar −xzf kindlegen_linux_2.6_i386_v2.tar.gz
Then copy the kindlegen executable into your path.
PG-RST Classes
PG-RST specifies a number of predefined classes, that cover most of the
standard uses at PG.
Classes For Inline Text
These classes have an effect on inline text only. Mainly, you use these
on role directives. If you put them on a block instead, all inline
contents of the block will be rendered accordingly.
Using classes on a role directive.
.. role:: xl−sc
:class: x−large small−caps
:xl−sc:`This Text in Extra Large Small Caps`
Using classes on a block.
.. class:: x−large small−caps
This Text in Extra Large Small Caps
Classes For Inline Text I
─────────────────────────────────────────────────────────────────
Class Explanation
─────────────────────────────────────────────────────────────────
italics Switch to italic font.
─────────────────────────────────────────────────────────────────
no-italics Switch to roman font.
─────────────────────────────────────────────────────────────────
bold Switch to boldface.
─────────────────────────────────────────────────────────────────
no-bold Switch to normal weight.
─────────────────────────────────────────────────────────────────
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.
──────────────────────────────────────────────────────────────────────
noindent Removes indentation of this paragraph in
formats where paragraphs are indented.
──────────────────────────────────────────────────────────────────────
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.
Using the titlepage class.
.. cleardoublepage::
.. container:: titlepage
Pride and Prejudice
.. vspace:: 2
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.
Creating a custom role.
.. 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:
Creating another custom 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
With the style-directive you can set classes and options on elements in
a CSS-like fashion.
style is local to the enclosing element. Global styles must be set
before the document title.
The (mandatory) argument is a CSS-like selector. It has the form:
[element][.class[.class]] [, [element][.class]] ]
_Element_ matches the element name while _.class_ matches any class on
the element.
Option formats selects for which output formats the directive will
apply. A space-separated list of format specifiers. If this option is
missing the directive applies to all output formats.
Valid output format specifiers are: html.images html.noimages
epub.images epub.noimages kindle.images kindle.noimages pdf.images
pdf.noimages txt.utf-8 txt.iso-8859-1 txt.us-ascii.
’*’ acts as wildcard. Eg. txt.* *.images
A ’-’ negates the test. Eg. -txt.*
Caveat: new formats may be added in future releases of epubmaker.
Option class adds classes to all matched elements.
Option width sets the width on all matched elements.
Option align sets the alignment on all matched elements.
Option before adds text before all matched elements.
Option after adds text after all matched elements.
Option display set to ’none’ hides the element.
If the style-directive has content, it will replace the content of all
matched elements with the directive’s content.
Redeclaring the presentation of emphasis.
.. style:: emphasis
:class: no−italics gesperrt
Now *emphasis* will be rendered as gesperrt.
Now _emphasis_ will be rendered as gesperrt.
Redeclaring the presentation of strong emphasis.
.. style:: strong
:class: no−bold 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 small-caps.
And _Strong Emphasis_ will be rendered as big bold small-caps.
Setting the width of all illustrations.
.. style:: figure.illustration
:width: 50%
:align: center
All figures with a :option:`:figclass:` of illustration
are now set to 50% width and are center aligned.
Redeclaring some more presentations.
.. 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_.
Declaring a passage of 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".
Declaring the language of the whole document.
.. style:: document
:class: language−de
The whole document is in German.
Replacing transitions with images.
.. style:: transition
:formats: *.images
:class: center
.. image:: images/G.png
:float: none
Localizing plain text illustration markers.
.. style:: caption.figure−caption
:formats: txt.*
:class: left
:before: ’[Abbildung: ’
:after: ’]’
Forced
Line
Breaks
Line blocks (|) are semantically associated with poetry and should not
be used to force line breaks in text that is not poetry.
PG-RST offers extensions to force line breaks:
1. You may set the class white-space-pre-line on any object or
container. All text elements inside that object will retain the
line breaks of the rst source.
Line breaks 1.
.. container:: white−space−pre−line
Line one
Line two
Line three
Line one
Line two
Line three
If processed with vanilla docutils, the text will flow and the line
breaks will not be preserved.
2. You may specify a role with class white-space-pre-line once in the
file header and then use that role on inlined text.
Line breaks 2.
.. role:: br
:class: white−space−pre−line
:br:`Line one
Line two
Line three`
Line one
Line two
Line three
Again, if processed with vanilla docutils, the text will flow and
the line breaks will not be preserved.
Line Breaks in Titles
To have line breaks in a title, you must: 1) somehow put the newline
character in the title, and 2) somehow put the white-space-pre-line
class on the title element.
You achieve 1) by declaring a substitution reference once in the file
header and then use the substitution reference in the title.
You achieve 2) by styling all title elements in the document with the
class white-space-pre-line.
Line breaks 3.
In the document header use:
.. |nl| unicode:: 0x0A .. new line
:trim:
.. style:: title
:class: white−space−pre−line
Then in the document body use:
Chapter I |nl| Down The Rabbit Hole
Line Breaks in Figure Captions
Put the white-space-pre-line class into the figclass option, or use the
:br: rule as shown above.
Line breaks 4.
.. figure:: images/pretty.png
:figclass: white−space−pre−line
Line One
Line Two
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.
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.
Generating a table of contents.
.. contents::
:depth: 2
:page−numbers:
:backlinks: none
Introduction ................................................... 1
PG-RST ....................................................... 1
epubmaker .................................................... 1
RST Documentation ............................................ 1
Installing EpubMaker ........................................... 1
Windows ...................................................... 1
Debian ....................................................... 1
PG-RST Classes ................................................. 1
Classes For Inline Text ...................................... 1
Classes For Block Text ....................................... 1
Classes For Front Matter Markup .............................. 1
PG-RST Extensions .............................................. 1
Styles ....................................................... 1
Forced Line Breaks ........................................... 1
Pagination ................................................... 1
Table of Contents ............................................ 1
List of Figures .............................................. 1
List of Tables ............................................... 1
Toc-Entry .................................................... 1
Footnotes .................................................... 1
Page Numbers ................................................. 1
Line Numbers ................................................. 43
Dropcaps ..................................................... 43
Tables ....................................................... 43
PG Metadata .................................................... 43
Top Boilerplate .............................................. 43
Docinfo section .............................................. 43
Bottom Boilerplate ........................................... 43
PG-RST Best Practices .......................................... 43
Titles ....................................................... 43
Titlepages ................................................... 43
Images ....................................................... 43
Examples and Tests ............................................. 2
Danny Deever ................................................. 5
Section 3.1 .................................................. 7
Section 3.2 .................................................. 123
Section 3.3 .................................................. 123
List of Figures
Use the lof directive to generate a list of figures automatically.
The selector option allows to filter the selected figures in a CSS-like
manner.
N.B. You may also provide a list of figures manually.
Generating a list of illustrations.
.. lof::
:page−numbers:
:backlinks: none
:selector: figure.illustration
Richard and Drucilla Martin ..................................... 43
This example builds a list of all figures with class chart or class map.
Generating a list of maps and charts.
.. lof::
:page−numbers:
:backlinks: none
:selector: figure.chart, figure.map
List of Tables
Use the lot directive to generate a list of tables.
N.B. You may also provide a list of tables manually.
Generating a list of tables.
.. lot::
:page−numbers:
:backlinks: none
Classes For Inline Text I ...................................... 1
Classes For Inline Text II ..................................... 1
Classes For Inline Text III .................................... 1
Classes For Block Text ......................................... 1
Classes For Front Matter Markup ................................ 1
Directives For Pagination ...................................... 1
Footnote Positions ............................................. 1
Support for dropcaps in output formats ......................... 43
Demo Table ..................................................... 43
Truth table for “and” .......................................... 43
Fields In the PG Scheme ........................................ 43
Fields In the DC Scheme ........................................ 43
Fields In the MARCREL Scheme ................................... 43
Fields Without Scheme .......................................... 43
_TABLE 8_ Types of Computers Used in the Systems Reported ...... 123
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.
Alternative captions.
.. toc−entry:: An Alternative Caption
.. table:: A Caption
Footnotes
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.¹)
Declaring a footnote section.
.. footnotes::
:class: smaller
Positioning of footnotes
─────────────────────────────────────────────────────────────────
Format Position
─────────────────────────────────────────────────────────────────
TXT Where they are defined.
─────────────────────────────────────────────────────────────────
HTML Collected under the footnotes directive.
─────────────────────────────────────────────────────────────────
EPUB "
─────────────────────────────────────────────────────────────────
PDF At the bottom of the current page.
─────────────────────────────────────────────────────────────────
Test one² two³.
¹ Not even print the section title.
² 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.
Declaring page numbers.
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.
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.
A reference to a page number can be inserted with the sequence [pg n]_.
This will generate a link to the page anchor.
Declaring a page number reference.
See page [pg 42]_.
See page 42.
An invisible page number can be inserted with the sequence [pg!n].
Declaring invisible page numbers.
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]_.
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. See
page 43.
See page iii.
Line Numbers
The sequence [ln n] will convert into a line number marker of n. n can
be any arabic numeral. The sequence itself will be removed from the text
and the line number printed on the far right.
As ids have to be unique, only the first line with any number will have
an anchor automatically inserted.
Declaring line numbers.
| Habe nun, ach! Philosophie, [ln 1]
| Juristerei und Medizin,
| Und leider auch Theologie
| Durchaus studiert, mit heißem Bemühn.
| Da steh ich nun, ich armer Tor! [ln 5]
| Und bin so klug als wie zuvor;
Habe nun, ach! Philosophie,
Juristerei und Medizin,
Und leider auch Theologie
Durchaus studiert, mit heißem Bemühn.
Da steh ich nun, ich armer Tor!
Und bin so klug als wie zuvor;
A reference to a line number can be inserted with the sequence [ln n]_.
This will generate a link to the first line that has the number n.
Declaring a line number reference.
See line [ln 5]_.
See line 5.
An invisible line number can be inserted with the sequence [ln!n].
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 dropped resized and dropped
───────────────────────────────────────────────────────────────────
EPUB enlarged on baseline resized on baseline
───────────────────────────────────────────────────────────────────
TXT normal size alt text
───────────────────────────────────────────────────────────────────
PDF enlarged and dropped⁵ resized and 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.
Declaring drop caps 1.
.. dropcap:: L L’orem ipsum
:lines: 4
:indents: −1.25em 0.5em
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.
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 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).
Declaring drop caps 2.
.. dropcap:: G
:image: images/G.png
:lines: 4
:raise: 0.5
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.
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.
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.
hrules Valid arguments are: none, table, rows.
’None’ omits all horizontal rules. ’table’ draws rules at the
top and bottom of the table and between header and body. ’rows’
draws rules between rows.
float (PDF output only.) Specify where the table should go if there is
not enough room on the page left to put it here.
Valid arguments are:
none does not move the table from its position in the text
flow. This may leave a lot of empty space on the page
before the table, though.
here puts the table where it is if there is enough space left
on the page, else floats it to another location.
top puts the table at the top of the next page.
bottom puts the table at the bottom of this page or the next
page.
page puts the table on a page of its own.
Declaring a table 1.
.. 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.
:hrules: table rows
:float: none
+−−−−−−−−−−−−−−−−−−−−−−−−+−−−−−−−−−−−+−−−−−−−−−−+−−−−−−−−−−−+
| Header row, column 1 | Justified | Centered | Price ($) |
| (header 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 | Cells | row 4 |
| columns. Lorem ipsum dolor sit | may span +−−−−−−−−−−−+
| amet, consetetur adipiscing. | rows. | row 5 |
+−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−+−−−−−−−−−−+−−−−−−−−−−−+
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
──────────────────────────────────────────────────────────────────
Declaring a table 2.
.. table:: Truth table for “and”
:hrules: table
:align: center
:width: 50%
:float: none
===== ===== =========
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:
Building the PG boilerplate 1.
.. −*− encoding: utf−8 −*− (1)
===========
Short Title (2)
===========
:PG.Title: Very Short Title (3)
:PG.Id: 181
:PG.Released: 2010−11−25
:PG.Reposted: 2011−11−25 HTML version created
:PG.Reposted: 2012−11−25 textual corrections applied
: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
.. clearpage:: (4)
.. pgheader:: (5)
(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) This will be the first line of the generated files. It should say
either: “The Project Gutenberg Ebook of Title” or just “Title”.
Use ’=’ bars above and below the title.
(3) The docinfo section: see section below.
(4) This directive inserts a page break.
(5) This directive inserts the PG header as generated from the docinfo
section.
⁶ A unicode BOM is allowed before this. In fact most Windows editors
will add a BOM without asking you.
Docinfo section
The docinfo contains all data that is used to generate the PG header and
the PG catalog entry.
It consists of a list of name-value pairs. The name part may be a plain
name like ’coverpage’ or a scheme.name pair. The scheme is used to group
the entries of the docinfo section into related groups.
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.Reposted Date of repost in YYYY-MM-DD format. A short
comment may be appended. Don’t put more than
one date in this field. Repeat the field if
necessary.
─────────────────────────────────────────────────────────────────
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 …” and “***END OF …”. This field is
optional. It defaults to the first line of the
’DC.Title’ field.
─────────────────────────────────────────────────────────────────
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 page
scans, etc.
─────────────────────────────────────────────────────────────────
DC Scheme
This scheme is standardized by the _Dublin Core Metadata Initiative_ and
is understood by many search engines and also by 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- 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.
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
Some fields are associated with none of the above schemes.
Fields Without Scheme
─────────────────────────────────────────────────────────────────
Name Contents
─────────────────────────────────────────────────────────────────
coverpage A coverpage for those formats (eg. Kindle)
that support a cover page. This image must be
included in the upload but must not
necessarily be put in the text flow.
─────────────────────────────────────────────────────────────────
Bottom Boilerplate
You must put this at the very bottom of your PG-RST file.
Building the PG boilerplate 2.
.. pgfooter:: (1)
(1) This directive inserts the PG footer and license.
PG-RST Best Practices
Titles
If you include the PG license (using the pgfooter directive) , you have
to use these characters for underlining titles in your text:
Title levels.
Title Level 1
=============
Title Level 2
−−−−−−−−−−−−−
Title Level 3
`````````````
The license has 3 levels of titles and uses these characters. You have
to use the same ones.
Titlepages
Don’t use line blocks to format title pages etc. Line blocks have the
semantics of poetry. They wrap with the second and further lines
indented.
Instead use a container with a class of white-space-pre-line and the
vspace directive to obtain vertical spacing.
A title page formatted like poetry. (Don’t do this!)
|
|
|
|
| Title of Work
|
| by
|
| Author
A well-formatted title page.
.. cleardoublepage::
[pg!3]
.. container:: titlepage center white−space−pre−line
:xl:`ADVENTURES`
.. vspace:: 2
OF
.. vspace:: 2
:xl:`HUCKLEBERRY FINN`
.. vspace:: 1
(TOM SAWYER’S COMRADE).
.. vspace:: 2
Scene: The Mississippi Valley.
Time: Forty to Fifty Years Ago.
.. vspace:: 2
BY
.. vspace:: 1
:xl:`MARK TWAIN`.
.. vspace:: 2
WITH ONE HUNDRED AND SEVENTY−FOUR ILLUSTRATIONS.
.. vfill::
NEW YORK:
CHARLES L. WEBSTER AND COMPANY.
1885.
The vfill directive inserts elastic space, that fills the remaining
blank space, pushing the last 3 lines to the bottom of the page.
Images
Specify a width option in images and a figwidth option in figures and
express it in percent.
If you don’t specify a width, the converter will calculate the width
percentile for you, using the formula:
image_width / (980px * 0.8) * 100
(980px is the approx. wide of a browser window with scrollbar on a
1024px wide screen, 0.8 are 10% margins left and right.)
Expressing the image size relative to the screen width is the best way
to get images right on a wide variety of devices form iPhones to print.
Declaring a figure.
.. toc−entry:: Richard and Drucilla Martin
.. figure:: images/cover.jpg
:figclass: illustration
:align: center
:alt: Richard and Drucilla Martin
:lb:`Richard Martin was a slave in Memphis, Tennessee.
Drucilla Martin was a slave in Giles County, Tennessee.`
The legend consists of all elements after the caption. 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.
[Illustration: Richard Martin was a slave in Memphis, Tennessee.
Drucilla Martin was a slave in Giles County, Tennessee.]
The legend consists of all elements after the caption. 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.
Tests and Examples
Notice
The rest of this file contains tests. You may look at the RST source to
learn how things are done.
A generated local table of contents:
Danny Deever
Section 3.1
Section 3.2
Section 3.3
A local table of contents as highlights:
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.
ÄÖÜ äöüß Æsop Œdipus cœr. Đ. †‡ ｳ. §2.1
‘’ ‚‛ “ ” ‹› em — en –.
“ ‘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. 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.’ ”
[Illustration: Caption.]
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. 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.
Transition follows.
⁂
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. 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.
Transition follows.
⁂
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. 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.
A simple poem:
Habe nun, ach! Philosophie,
Juristerei und Medizin,
Und leider auch Theologie
Durchaus studiert, mit heißem Bemühn.
Da steh ich nun, ich armer Tor!
Und bin so klug als wie zuvor;
A poem that is inside a block quote:
Habe nun, ach! Philosophie,
Juristerei und Medizin,
Und leider auch Theologie
Durchaus studiert, mit heißem Bemühn.
Da steh ich nun, ich armer Tor!
Und bin so klug als wie zuvor;
Two fancy-formatted poems:
‘Speak roughly to your little boy,
And beat him when he sneezes:
He only does it to annoy,
Because he knows it teases.’
CHORUS.
(In which the cook and the baby joined):—
‘Wow! wow! wow!’
Summer wanes, the children are grown;
Fun and frolic no more he knows;
Robert of Lincoln’s a humdrum crone;
Off he flies and we sing as he goes:
Bob-o’link, bob-o’-link,
Spink, spank, spink;
When you can pipe that merry old strain,
Robert of Lincoln, come back again.
Chee, chee, chee.
Danny Deever
"What are the bugles blowin’ for?" said Files-on-Parade.
"To turn you out, to turn you out", the Colour-Sergeant said.
"What makes you look so white, so white?" said Files-on-Parade.
"I’m dreadin’ what I’ve got to watch", the Colour-Sergeant said.
For they’re hangin’ Danny Deever, you can hear the Dead March play,
The regiment’s in ’ollow square—they’re hangin’ him to-day;
They’ve taken of his buttons off an’ cut his stripes away,
An’ they’re hangin’ Danny Deever in the mornin’.
"What makes the rear-rank breathe so ’ard?" said Files-on-Parade.
"It’s bitter cold, it’s bitter cold", the Colour-Sergeant said.
"What makes that front-rank man fall down?" said Files-on-Parade.
"A touch o’ sun, a touch o’ sun", the Colour-Sergeant said.
They are hangin’ Danny Deever, they are marchin’ of ’im round,
They ’ave ’alted Danny Deever by ’is coffin on the ground;
An’ ’e’ll swing in ’arf a minute for a sneakin’ shootin’ hound—
O they’re hangin’ Danny Deever in the mornin’!
"’Is cot was right-’and cot to mine", said Files-on-Parade.
"’E’s sleepin’ out an’ far to-night", the Colour-Sergeant said.
"I’ve drunk ’is beer a score o’ times", said Files-on-Parade.
"’E’s drinkin’ bitter beer alone", the Colour-Sergeant said.
They are hangin’ Danny Deever, you must mark ’im to ’is place,
For ’e shot a comrade sleepin’—you must look ’im in the face;
Nine ’undred of ’is county an’ the regiment’s disgrace,
While they’re hangin’ Danny Deever in the mornin’.
"What’s that so black agin’ the sun?" said Files-on-Parade.
"It’s Danny fightin’ ’ard for life", the Colour-Sergeant said.
"What’s that that whimpers over’ead?" said Files-on-Parade.
"It’s Danny’s soul that’s passin’ now", the Colour-Sergeant said.
For they’re done with Danny Deever, you can ’ear the quickstep play,
The regiment’s in column, an’ they’re marchin’ us away;
Ho! the young recruits are shakin’, an’ they’ll want their beer
to-day,
After hangin’ Danny Deever in the mornin’.
And now for something completely different:
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. 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
Who could have stolen the tickets was a mystery, until a slip of paper
was handed to Giles, the treasurer, which read:
“Leo Dunbar was hanging around the ticket wagon last night.
Better watch and search him.
“A Friend.”
Giles lost no time in acting upon the suggestion given in the note. He
ran to the dressing-tent and, finding a key to fit Leo’s trunk, opened
it.
Section 3.1
I pity the man who can travel from Dan to Beersheba, and say
“’Tis all barren;” and so is all the world to him who will not
cultivate the fruits it offers.
―― Sterne: Sentimental Journey.
Simple List with hyphens
- Wash left ear.
- Wash right ear.
- Brush teeth.
Simple List with bullets
· Wash left ear.
· Wash right ear.
· Brush teeth.
Nested List
1. Item 1.
a) Item 1a.
b) Item 1b.
I) Item 1.a.I
II) Item 1.a.II
III) Item 1.a.III
IV) Item 1.a.IV
2. A) i) Item 2.A.i
ii) Item 2.A.ii
B) i) Item 2.B.i
ii) Item 2.B.ii
iii) Item 2.B.iii
C) Item 2.C
3. Item 3.
Definition List
term Definition.
term 2 Definition 2
Definition 2 paragraph 2.
long term 3
Definition 3
Option List (not used by PG)
-a
, command-line option "a"
-1
[4m_file_[0m
,
--one
=[4m_file_[0m
,
--two
[4m_file_[0m
, Multiple options with arguments.
Section 3.2⁷
⁷ This title contains a footnote reference. The footnote reference
will not show up in the TOC.
Some text so this section isn’t empty.
Just editing something to test VCS. More.
Section 3.3
THE MAN WHO PLEASES.
_The dearest friend to me, the kindest man, jabbada jabbada
jabbada jabbada jabbada jabbada jabbada jabbada_
_The best-conditioned and unwearied spirit_
_In doing courtesies._
_―― Merchant of Venice._
_He hath a daily beauty in his life._
_―― Othello._
_Such a man would win any woman in the world_
_if a’ could get her good will._
_―― Much Ado About Nothing._
There are few subjects of deeper interest to men and women than that of
personal fascination,
«Ora si comincia per quelli di fuori e per quelli di dentro a
far grandissima e crudel guerra.»
_Istorie pistolesi._
Larger text block with some _emphasis_.
*Mme Bovary*
_TABLE 8_Types of Computers Used in the Systems Reported
───────────────────────────────────────────────────────────────────
Type Number
───────────────────────────────────────────────────────────────────
ASI 210 1
───────────────────────────────────────────────────── (3)
ASI 2100 2
───────────────────────────────────────────────────────────────────
CDC 160A 2
───────────────────────────────────────────────────── (3)
CDC 3100 1
───────────────────────────────────────────────────────────────────
total computer cost 0.22 ± 0.06 by averaging
−−−−−−−−−−−−−−−−−−−−−−−− = 0.23 −> separate ratios for each
cost of bare accelerator system
This is an example of letter in a block quote.
Dear Beth,
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:
Korouaputa = Rakumia (f.).
______________|____________________
| |
Pare−wahawaha = Te Rangipumamao Parekohatu =
(f.) | |
________| ________|
| |
Tihao = _Te Rauparaha_.
___|____________________
| |
Te Whata−nui = Kotia (f.) =
_____| |
| _Te Ngarara_.
Tutaki =
___|
|
_Hinematioro_.
_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 …
Transcriber’s Note
Minor spelling errors have been silently corrected.
Hyphenation has been made consistent.
*** END OF THIS PROJECT GUTENBERG EBOOK PG-RST MANUAL ***
A Word from Project Gutenberg
We will update this book if we find any errors.
This book can be found under: http://www.gutenberg.org/ebooks/181
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 .
Section 3. Information about the Project Gutenberg Literary Archive
Foundation
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
For additional contact information:
Dr. Gregory B. Newby
Chief Executive and Director
gbnewby@pglaf.org
Section 4. Information about Donations to the Project Gutenberg Literary
Archive Foundation
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
Section 5. General Information About Project Gutenberg™ electronic
works.
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:
http://www.gutenberg.org
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.