RST: EpubMaker Guide
Note: RST is no longer used at DP. Information on this page may be out of date.
Project Gutenberg's EpubMaker (or epubmaker) is a Python program that generates Epubs from HTML as well as Epub, HTML, and plain text from reStructuredText for posting at PG. This page is a guide for DP post-processors who use epubmaker to generate output formats for testing before uploading the RST source file. It can also be used to generate separate HTML and text outputs and those may be sent up without the RST file as has traditionally been done. Guiguts Version 1.0.0 (guiguts-win-epub-1.0.0.zip) bundles ePubMaker.
Note: This page covers updating and using EpubMaker. For initial installation, including information on other tools you will need, please see the RST: Installation Guide.
Usage
Note: This usage reflects epubmaker >= 0.3.2. Update your epubmaker installlation with:
easy_install -U epubmaker
NOTE: beginning with epubmaker version 0.3.18, you MUST also update the version of DOCUTILS to 0.8. Use this at the command prompt:
easy_install -U docutils
First, a word about file naming. If your RST file contains the meta data block, the file will be named (typically) 99999.<extension>. If you do not include any meta data, the file will be named the same as the book's title. Also, the "pgheader" and "pgfooter" line are not required when testing the RST but are required when the file is finally uploaded as a single RST source file. If you aren't using the meta block and want a simpler file name than the full title of the book, specify the epub number in the command line:
epubmaker --ebook=99999 --make=<output format> filename.rst
Here are some typical examples. To generate all the text versions from a source file winsted.rst
epubmaker --ebook=99999 --make=txt winsted.rst
To get just the UTF-8 version:
epubmaker --ebook=99999 --make=txt.utf-8 winsted.rst
That generates a file winsted-0.txt, which currently has a BOM. Mac and Linux users can remove the BOM with
awk '{if(NR==1)sub(/^\xef\xbb\xbf/,"");print}' *.utf-8.txt > winsted-8.txt
However if you don't need UTF-8, you don't need to generate this file.
More likely you will want the Latin-1 (or iso-8859-1) version of the text file. Use this:
epubmaker --ebook=99999 --make=txt.iso-8859-1 winsted.rst
This generates a file winsted-8.txt, which is a Latin-1 file suitable for GuiGuts, etc.
You can generate the plain ASCII file with
epubmaker --ebook=99999 --make=txt.us-ascii winsted.rst
This generates winsted.txt, which is plain ASCII.
The HTML file is generated with
epubmaker --ebook=99999 --make=html winsted.rst
The Epub file is generated without or with images using:
epubmaker --ebook=99999 --make=epub.noimages winsted.rst epubmaker --ebook=99999 --make=epub.images winsted.rst
Remember, you can avoid having to specify the "--ebook=99999" line if you use the metadata block.
Web epubmaker at pglaf
From the forum:
Greg Newby has just made public an epubmaker service, running at pglaf machines. Going to http://epubmaker.pglaf.org one can upload a file (either a single file or a zip file) and get back the generated files from the epubmaker suite (as well as the log file). It has been tested by a small group of testers, (mainly garweyne and Roger Franks) and runs the same version of epubmaker that is used by the WW-ers to generate all the versions from our submissions. The main use is to provide a preview service both for rst (all the formats are generated) and html, avoiding the need of installing and maintaining the epubmaker software. The form contains a short usage description, but not an RST manual.
link to Known issues with epubmakers' conversion of RST
link to RST Index Page