The Project Gutenberg RST Manual

Marcello Perathoner

Read The Project Gutenberg RST Manual by Marcello Perathoner in the Tower of Babel, a free online library of public-domain works preserved in clean, searchable text. No sign-up. The full text is served as a plain-text file at a predictable URL, where text is present: https://antarctic-labs.com/tower-of-babel/181-the-project-gutenberg-rst-manual.txt.

Introduction

The Project Gutenberg RST Manual opens with reStructuredText markup rather than finished pages: container directives, a title page block, and lists of tables and figures. Its first chapter heading is Installing EpubMaker. The leaves provided run only 392 characters, holding the manual's skeleton of contents and lists. The instructions themselves, on formatting texts for the project's EpubMaker tool, are not present in the pages at hand.

Catalog record

CREATORMarcello Perathoner
COLLECTIONBOOKS
FORMATTXT
FILE SIZE35 KB
LICENSEPUBLIC_DOMAIN
RIGHTSPUBLIC DOMAIN
SOURCEProject Gutenberg

Source: https://www.gutenberg.org/ebooks/181

Browse the full library · About the Tower of Babel

Full text

The opening of the work, from the library's hosted text:

 | | | | .. _pg-produced-by: .. container:: | [pg!i] .. container:: titlepage .. vfill:: .. class:: center x-large | The | | Project Gutenberg | | RST Manual .. vfill:: .. vfill:: [pg!iii] .. contents:: Contents :depth: 2 [pg!v] .. lot:: List of Tables [pg!vii] .. lof:: List of Figures .. mainmatter:: [pg!1] Installing EpubMaker ==================== EpubMaker is Project Gutenberg's file converter. It can convert from PG-RST to HTML, EPUB, PDF and plain text. Windows ------- Prerequisites ````````````` 1. Install Python. Assuming you don't have python yet. If you have either version 2.6 or 2.7 already installed, skip this. From http://www.python.org/download/releases/2.7/ download the :file:`Windows x86 MSI Installer (2.7)` and run it. Select all the default options and install. 2. Install Python Setuptools. From http://pypi.python.org/pypi/setuptools download :file:`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` (:file:`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 :file:`install-tl.zip`. Then say:: > unzip install-tl.zip > cd install-tl* > install-tl This will open the TeX Live installation wizard. Follow the instructions. When in doubt use the defaults. This will take quite a while. (3 hours on an old Dell Vostro 1000 laptop. It installs about 2.5 GB in 93,000 files.) If you experience download problems, restart the wizard: it will resume the download where it left off. Long installation instructions can be found at http://www.tug.org/texlive/doc/texlive-en/texlive-en.html#x1-150003 5. Install HTML Tidy. (You can skip this step if you only want to process RST files and don't want to build EPUBs from HTML input.) If you are a post-processor you already have this. http://tidy.sourceforge.net/ 6. Update your PATH. Start | Control Panel | System | Advanced | Environment Variables. Click "Path" in the User variables at the top. Click "Edit" If the field is empty just enter (all in one line):: C:\Python27; C:\Python27\Scripts; C:\Program Files\GnuWin32\bin; If the field contains data, go to the end of that data and add a semicolon if there isn't one already and then add the string above. Click Ok three times. EpubMaker ````````` 1. At the command prompt run:: > easy_install epubmaker 2. Test your installation:: > epubmaker --help > epubmaker https://www.gutenberg.org/masters/rst/181/181.rst Debian ------ Prerequisites ````````````` (Does not work with python 3 yet. If your distribution uses python 3 as default (not likely!), you'll have to parallel install python 2.6 or 2.7.) :: # apt-get install python python-setuptools python-lxml # apt-get install groff tidy # apt-get install libpng-dev libjpeg-dev libfreetype6-dev Note: To get PDF generation to work, you have to use TeX Live version 2009-11 or newer. You can get those from debian testing or unstable. If don't want to switch from debian stable, you have to install TeX Live manually. If you are on testing or unstable:: # apt-get install texlive texlive-latex-extra texlive-xetex # apt-get install ttf-linux-libertine ttf-dejavu Else, to install TeX Live manually, go to http://mirror.ctan.org/systems/texlive/tlnet and download the file :file:`install-tl-unx.tar.gz`. Unpack it. Then:: # cd /path/where/unpacked # perl install-tl -gui Long installation instructions can be found at http://www.tug.org/texlive/doc/texlive-en/texlive-en.html#x1-150003 EpubMaker ````````` :: # easy_install epubmaker Kindlegen ````````` (Optional: Used only to make Kindle files): :: $ wget http://s3.amazonaws.com/kindlegen/kindlegen_linux_2.6_i386_v1.2.tar.gz $ tar -xzf kindlegen_linux_2.6_i386_v1.2.tar.gz PG-RST Classes ============== A list of classes you can use in PG-RST. Classes For Inline Text ----------------------- These classes have an effect on inline text. If you put them on a block, all inline contents of the block will be rendered accordingly. .. table:: Classes For Inline Text I :width: 75% :widths: 1 3 :class: norules ==================== ======================================================== Class Explanation ==================== ======================================================== :css:`italics` Switch to italic font. :css:`bold` Switch to boldface. :css:`small-caps` Switch to small capitals. :css:`gesperrt` Switch to gesperrt (extended letter spacing). :css:`antiqua` Switch to antiqua. :css:`monospaced` Switch to monospaced font. ==================== ======================================================== .. table:: Classes For Inline Text II :width: 75% :widths: 1 3 :class: norules ==================== ======================================================== Class Explanation ==================== ======================================================== :css:`smaller` Switch to smaller font. :css:`larger` Switch to larger font. :css:`xx-small` Switch to smallest font. :css:`x-small` Switch to very small font. :css:`small` Switch to small font. :css:`medium` Switch to normal font size. :css:`large` Switch to large font. :css:`x-large` Switch to very large font. :css:`xx-large` Switch to largest font. ==================== ======================================================== .. table:: Classes For Inline Text III :width: 75% :widths: 1 3 :class: norules ==================== ======================================================== Class Explanation ==================== ======================================================== :css:`red` Switch to red font. :css:`green` Switch to green font. :css:`blue` Switch to blue font. :css:`yellow` Switch to yellow font. :css:`white` Switch to white font. :css:`gray` Switch to gray font. :css:`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 :option:`align` option. .. table:: Classes For Block Text :width: 75% :widths: 1 3 :class: norules =========================== ================================================= Class Explanation =========================== ================================================= :css:`left` Left-aligns the text in the block. :css:`center` Centers the text in the block. :css:`right` Right-aligns the text in the block. :css:`justify` Justifies the text in the block. :css:`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. .. table:: Classes For Front Matter Markup :width: 75% :widths: 1 3 :class: norules ==================== ======================================================== Class Explanation ==================== ======================================================== :css:`coverpage` The cover page. :css:`frontispiece` The frontispiece. :css:`titlepage` The title page. :css:`verso` The title page verso. :css:`dedication` The dedication page. :css:`plainpage` A general class for page. ==================== ======================================================== Use these classes on a :directive:`container`. These classes already insert page breaks before the container so you need not insert page breaks on your own. .. example:: :norender: .. container:: titlepage | Pride and Prejudice | | Written by Jane Austen. PG-RST Extensions ================= You can create custom roles based on the existing ones. This is how you create and then use custom roles. .. example:: .. role:: small-caps :class: small-caps This text is in :small-caps:`Small Caps`. You can attach more than one class to a role: .. example:: .. role:: big-and-bold :class: x-large bold This text is :big-and-bold:`big and bold`. Styles ------ You can redefine the rendering of elements: .. example:: .. style:: emphasis :class: gesperrt Now *emphasis* will be rendered as gesperrt. .. example:: .. style:: strong :class: small-caps And **Strong Emphasis** will be rendered as small-caps. .. example:: .. style:: strong :class: small-caps x-large bold And **Strong Emphasis** will be rendered as big bold small-caps. .. example:: .. style:: literal :class: red ``literally red`` .. style:: superscript :class: green :superscript:`sup`\ er .. style:: title_reference :class: blue :title-reference:`Hamlet` and `Othello`. You can semantically markup foreign text: .. example:: .. role:: french :class: language-fr italics :french:`Pas de double` is the French for "father

Read the complete text