|
[pg!i] The Project Gutenberg RST Manual[pg!iii] Contents
[pg!v] List of Tables
[pg!vii] List of Figures
[pg!1] Installing EpubMakerEpubMaker is Project Gutenberg’s file converter. It can convert fromPG-RST to HTML, EPUB, PDF and plain text. WindowsPrerequisites
EpubMaker
DebianPrerequisites(Does not work with python 3 yet. If your distribution uses python 3 asdefault (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 version2009-11 or newer. You can get those from debian testing orunstable. If don’t want to switch from debian stable, you have toinstall 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 tohttp://mirror.ctan.org/systems/texlive/tlnet and download the fileinstall-tl-unx.tar.gz. Unpack it. Then: # cd /path/where/unpacked# perl install-tl -gui Long installation instructions can be found athttp://www.tug.org/texlive/doc/texlive-en/texlive-en.html#x1-150003 EpubMaker# easy_install epubmaker Kindlegen(Optional: Used only to make Kindle files): $ wget http://s3.amazonaws.com/kindlegen/kindlegen_linux_2.6_i386_v1.2.tar.gz$ tar -xzf kindlegen_linux_2.6_i386_v1.2.tar.gz PG-RST ClassesA list of classes you can use in PG-RST. Classes For Inline TextThese classes have an effect on inline text. If you put them on a block, allinline contents of the block will be rendered accordingly.
Classes For Block TextThese classes have an effect on block text. Please do not confuse thealignment of the block with the alignment of the text in theblock. Eg. a table can be centered, while the text inside the tableis left-aligned. The alignment of the block is set with the alignoption.
Classes For Front Matter MarkupEpubMaker includes a few classes to markup front matter. While it isnot necessary to do this, it adds value. In future the PG catalogmight automatically extract not only the cover page but also the titlepage, verso, etc.
Use these classes on a container. These classes alreadyinsert page breaks before the container so you need not insert pagebreaks on your own. .. container:: titlepage | Pride and Prejudice | | Written by Jane Austen. PG-RST ExtensionsYou can create custom roles based on the existing ones. This is howyou create and then use custom roles. .. role:: small-caps :class: small-capsThis text is in :small-caps:`Small Caps`. This text is in Small Caps. You can attach more than one class to a role: .. role:: big-and-bold :class: x-large boldThis text is :big-and-bold:`big and bold`. This text is big and bold. StylesYou can redefine the rendering of elements: .. style:: emphasis :class: gesperrtNow *emphasis* will be rendered as gesperrt. Now emphasiswill be rendered as gesperrt. .. style:: strong :class: small-capsAnd **Strong Emphasis** will be rendered as small-caps. And Strong Emphasiswill be rendered as small-caps. .. style:: strong :class: small-caps x-large boldAnd **Strong Emphasis** will be rendered as big bold small-caps. And Strong Emphasiswill be rendered as big bold small-caps. .. style:: literal :class: red``literally red``.. style:: superscript :class: green:superscript:`sup`\ er.. style:: title_reference :class: blue:title-reference:`Hamlet` and `Othello`. literally red super Hamletand Othello. You can semantically markup foreign text: .. role:: french :class: language-fr italics:french:`Pas de double` is the French for "father of twins". Pas de double is the French for "father of twins". PaginationPagination is important if you generate PDFs. See the Directives ForPagination Table.
Table of ContentsUse the RST contents directive to automatically generatea table of contents. N.B. You may also provide a table of contents manually. In PG-RST the contents directive requires you to specifyan argument or the local option. The local option displays a local table of contents, containingonly the sub-sections of the section in which it is declared. The page-numbers option displays the original page number inthe TOC. .. contents:: A TOC With Page Numbers :depth: 2 :page-numbers: A TOC With Page Numbers
List of FiguresUse the lof directive to generate a list of figuresautomatically. N.B. You may also provide a list of figures manually. .. lof:: A List of Figures :page-numbers: :backlinks: none A List of Figures
List of TablesUse the lot directive to generate a list of tables. N.B. You may also provide a list of tables manually. .. lot:: A List of Tables :page-numbers: :backlinks: none A List of Tables
Toc-EntryUse the toc-entry directive to:
A toc-entry with argument sets the argument as toc entryfor the next section, figure or table. A toc-entry without argument suppresses the toc entry forthe next section, figure or table. Use the depth option to set the depth up to which sectiontitles are gathered for the toc. A depth of 0 switches toc gatheringoff. .. toc-entry:: An Alternative Caption FootnotesAlways define footnotes right after the paragraph they are referenced.
To collect the footnotes use the footnotesdirective. This directive will output a section with title and allfootnotes in the document will be moved inside the section. In PDF and TXT formats the footnotes directive will donothing.1 Test23. .. footnotes:: Footnotes :class: smaller Page NumbersThe sequence [pg n] will convert into a page number marker ofn. n can be any arabic or roman numeral. The sequence itself will beremoved from the text flow leaving a page anchor. There mustbespaces around the sequence. If the page break is in the middle of aword, join the word and put the sequence at the end of the word. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diamnonumy eirmod tempor invidunt [pg 42] ut labore et dolore magnaaliquyam erat, sed diam voluptua. At vero eos et accusam et justoduo dolores [pg xviii] et ea rebum. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diamnonumy eirmod tempor invidunt [pg 42] ut labore et dolore magnaaliquyam erat, sed diam voluptua. At vero eos et accusam et justoduo dolores [pg xviii] et ea rebum. A reference to a page number can be inserted with the sequence[pg n]_. This will generate a link to the page anchor. See page [pg 42]_. See page [pg 42]_. An invisible page number can be inserted with the sequence[pg!n]. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diamnonumy eirmod tempor invidunt [pg!43] ut labore et dolore magnaaliquyam erat, sed diam voluptua. At vero eos et accusam et justoduo dolores et ea rebum. See page [pg 43]_. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diamnonumy eirmod tempor invidunt [pg!43] ut labore et dolore magnaaliquyam erat, sed diam voluptua. At vero eos et accusam et justoduo dolores et ea rebum. See page [pg 43]_. See page [pg iii]_. DropcapsYou can insert dropcaps with the dropcap directive. Youcan use either an enlarged character or an image as dropcap. You canalso specify a span of character that should be set in small-capsafter the dropcap initial.
The first argument (mandatory) states the character(s) to replace withcaps. It must match the beginning of the next paragraph. The second (optional) argument states the characters to replace withsmall-caps. It must also match the beginning of the next paragraph. .. clearpage::.. dropcap:: L Lorem ipsum :lines: 4 :indents: -1.25em 0.5emLorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diamnonumy eirmod tempor invidunt ut labore et dolore magna aliquyamerat, sed diam voluptua. At vero eos et accusam et justo duodolores et ea rebum. Stet clita kasd gubergren, no sea takimatasanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet,consetetur sadipscing elitr, sed diam nonumy eirmod tempor inviduntut labore et dolore magna aliquyam erat, sed diam voluptua. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diamnonumy eirmod tempor invidunt ut labore et dolore magna aliquyamerat, sed diam voluptua. At vero eos et accusam et justo duodolores et ea rebum. Stet clita kasd gubergren, no sea takimatasanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet,consetetur sadipscing elitr, sed diam nonumy eirmod tempor inviduntut labore et dolore magna aliquyam erat, sed diam voluptua. The lines option (PDF only) specifies how many lines thedropcap should span. Default is 2. The indents option (PDF only) can specifiy up to 2 lengthvalues. The first one is the indent of the first line, the second onethe indent of the following lines. The indent is calculated from theright border of the dropcap letter. Defaults are 0em and 0.5em. The image option specifies the image url. In plain text andEPUB the image will not be used. .. clearpage::.. dropcap:: G :image: https://www.gutenberg.org/cache/epub/181/images/G.png :lines: 4Gorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diamnonumy eirmod tempor invidunt ut labore et dolore magna aliquyamerat, sed diam voluptua. At vero eos et accusam et justo duodolores et ea rebum. Stet clita kasd gubergren, no sea takimatasanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet,consetetur sadipscing elitr, sed diam nonumy eirmod tempor inviduntut labore et dolore magna aliquyam erat, sed diam voluptua.
TablesBe careful with tables because the table support of many ereaders isweak or nil. Tables also support these options:
These are the extra classes supported by PG-RST:
.. 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. +------------------------+-----------+----------+-----------+ | 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 | +------------------------------------+----------+-----------+
.. table:: Truth table for “and” :class: norules :align: center :width: 50% ===== ===== ========= A B A and B ===== ===== ========= False False False True False False False True False True True True ===== ===== =========
PG MetadataTop BoilerplateThis section explains the PG boilerplate that you must put at the topof your PG-RST file. It looks like this: .. -*- encoding: utf-8 -*- (1) .. meta:: (2) :PG.Id: 181 :PG.Title: Very Short Title :PG.Released: 2010-11-25 :PG.Rights: Public Domain :PG.Producer: Woody Guthrie :PG.Producer: Pete Seeger :PG.Producer: The Almanac Singers :PG.Credits: This file was produced from images stolen from the Louvre. :DC.Creator: Jane Austen :MARCREL.edt: Mark Twain :MARCREL.ill: Édouard Manet :DC.Title: Full Title Statement :DC.Language: en :DC.Language: fr :DC.Language: de :DC.Created: 1900 :coverpage: https://www.gutenberg.org/cache/epub/181/images/cover.jpg =========== Short Title (3) =========== .. pgheader:: (4)
Metadata DirectiveThe metadata directive contains all data that is used to generate thePG header and the PG catalog entry. The scheme is the part before the dot. PG SchemeThe PG scheme holds data that is relevant to Project Gutenberg only.
DC SchemeThis scheme holds standard Dublincore stuff and is used by many searchengines and the PG cataloguing software.
MARCREL SchemeThis is used to record contributors to the text. All these fields mayappear more than once. Don’t put more than one name into onefield. Repeat the field if necessary.
No SchemeSome fields are associated with none of the above schemes.
Bottom BoilerplateYou must put this at the very bottom of your PG-RST file. .. pgfooter:: (1)
PG-RST Best PracticesImages Specify a width option in images and a figwidthoption in figures and express it in percent. If you don’t specify a width, the converter will calculate the widthpercentile for you, using the formula: image_width / (980px * 0.8) * 100 (980px is the approx. wide of a browser window with scrollbar on a1024px wide screen, 0.8 are 10% margins left and right.) Expressing the image size relative to the screen width is the best wayto get images right on a wide variety of devices form iPhones toprint. .. toc-entry:: Richard and Drucilla Martin.. figure:: https://www.gutenberg.org/cache/epub/181/images/cover.jpg :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. 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. Loremipsum dolor sit amet, consetetur sadipscing elitr, sed diamnonumy eirmod tempor invidunt ut labore et dolore magna aliquyamerat, sed diam voluptua. At vero eos et accusam et justo duodolores et ea rebum. [pg!2] Tests and ExamplesNotice The rest of this file contains tests. You may look at the RSTsource to learn how things are done. A generated local table of contents:
A local table of contents as highlights:
ÄÖÜ äöüß Æsop Œdipus cœr. Đ. †‡ ウ. §2.1 ‘’ ‚‛ “ ” ‹› em — en –. “ ‘Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diamnonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat,sed diam voluptua. At vero eos et accusam et justo duo dolores et earebum. Stet clita kasd gubergren, no sea takimata sanctus est Loremipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetursadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore etdolore magna aliquyam erat, sed diam voluptua. At vero eos et accusamet justo duo dolores et ea rebum. Stet clita kasd gubergren, no seatakimata sanctus est Lorem ipsum dolor sit amet.’ ” Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diamnonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat,sed diam voluptua. [pg 3] At vero eos et accusam et justo duo doloreset ea rebum. Stet clita kasd gubergren, no sea takimata sanctus estLorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetursadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore etdolore magna aliquyam erat, sed diam voluptua. At vero eos et accusamet justo duo dolores et ea rebum. Stet clita kasd gubergren, no seatakimata sanctus est Lorem ipsum dolor sit amet. ―――― Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diamnonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat,sed diam voluptua. At vero eos et accusam et justo duo dolores et earebum. Stet clita kasd gubergren, no sea takimata sanctus est Loremipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetursadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore etdolore magna aliquyam erat, sed diam voluptua. At vero eos et accusamet justo duo dolores et ea rebum. Stet clita kasd gubergren, no seatakimata sanctus est Lorem ipsum dolor sit amet. [pg 4] Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diamnonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat,sed diam voluptua. At vero eos et accusam et justo duo dolores et earebum. Stet clita kasd gubergren, no sea takimata sanctus est Loremipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetursadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore etdolore magna aliquyam erat, sed diam voluptua. At vero eos et accusamet justo duo dolores et ea rebum. Stet clita kasd gubergren, no seatakimata sanctus est Lorem ipsum dolor sit amet. ‘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.And now a quote by Lorem Ipsum:
[pg 7] Section 3.1
Simple List with hyphens
Simple List with bullets
Nested List
Definition List
Option List (not used by PG)
[pg 123] Section 3.27Some text so this section isn’t empty. Section 3.3THE MAN WHO PLEASES. The dearest friend to me, the kindest man,The best-conditioned and unwearied spiritIn doing courtesies.―― Merchant of Venice. He hath a daily beauty in his life.―― Othello. Such a man would win any woman in the worldif a’ could get her good will.―― Much Ado About Nothing. There are few subjects of deeper interest tomen and women than that of personal fascination,
total computer cost 0.22 ± 0.06 by averaging------------------------ = 0.23 -> separate ratios for eachcost of bare accelerator system [pg!10] Footnotes
[pg 99] Transcriber’s Note Minor spelling errors have been silently corrected. Hyphenation has been made consistent. *** END OF THIS PROJECT GUTENBERG EBOOK PG-RST MANUAL *** |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

orem ipsum dolor sit amet, consetetur sadipscing elitr, sed diamnonumy eirmod tempor invidunt ut labore et dolore magna aliquyamerat, sed diam voluptua. At vero eos et accusam et justo duodolores et ea rebum. Stet clita kasd gubergren, no sea takimatasanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet,consetetur sadipscing elitr, sed diam nonumy eirmod tempor inviduntut labore et dolore magna aliquyam erat, sed diam voluptua.
Richard Martin was a slave in Memphis, Tennessee.