RST: FAQ
Note: RST is no longer used at DP. Information on this page may be out of date.
This page is for frequently asked questions and answers about RST.
How can I have more control over font size?
Right now, you can use "larger" and "smaller." Others, like "x-large" or "xx-large" as used on title pages may well be baked in to epubmaker. The way it is set up, there needs to be one set of CSS for HTML and one for Epub. Ideally, we would agree as an organization on what's in each of those to best meet our production needs and then Marcello would put them in if they don't break something in HTML or, more likely, Epub. Remember, epubmaker is a work in progress. Though it is completely functional now, expect it to be improved over time to even better meet our needs.
Where are those "meta" lines, like "DC:Creator" defined?
Near the top of the RST source file is a block of "meta" information. This is used by cataloging systems. It is not essential to have this information during post-processing, None of it shows up in HTML or text in a browser. When the file is sent to PPV or to PG, the information has to be there and correct. For a description of this data, see this page.
The ".. pgheader::" line places all the boilerplate text for a Project Gutenberg posting at the start of the generated files. Similarly, after the last line of your book, the ".. pgfooter::" line inserts all the legal notices, etc. During post-processing, leave these lines out. They can be added, like the meta data, immediately before the file is sent to PPV or PG.
Do I need to use epubmaker at all?
No, you do not, though you might want to. If you are producing books to be posted to Project Gutenberg, it is more convenient to just use epubmaker, since that's what they use to generate outputs from your RST. If you are not producing for PG, you still may want to as a convenience, but then there's always the danger that you will use something in PG's "extended" RST that isn't part of the RST spec, which makes your source file of limited value outside of PG. It's perfectly possible to start with RST and produce HTML and Epub without using PG's epubmaker.
What are my alternatives, then?
Starting with RST, your other choice is to use software provided as part of RST's Docutils package. Though PG hopes to influence the evolution of the RST standard, the definition of RST at any given moment is defined by published specifications and the Docutils tools, such as rst2html. You can start with a RST source, generate HTML with rst2html, and from there generate an epub with any of many freely available epub generators.
Project Gutenberg's epubmaker (EPM) allows "extensions to RST" that are not part of the standard. If you use some of those extensions, then the RST source file you create can only be processed by EPM. Other extensions to RST in epubmaker are really just predefined and immutable classes. You can create a RST source file that uses those because RST allows classes to be added. Let's look at some specific examples.
If you use the "line break" directive provided by EPM, then you have something that the "in the wild" programs, like rst2html and rst2latex cannot handle. This is also true for the visible page numbering capility of EPM. There is no way in CSS to implement a line break or a page number. Those are hard-coded into EPM and not part of RST.
However, EPM also provides the class "larger" to increase text size. Without EPM, this same class can be included in supplemental CSS. How this is done is well documented. Anything that EPM adds that is representable in a CSS class can be done without using EPM. If you want something that isn't built in to EPM as a class, for example a font size of "x-large," then you can't have it with EPM unless it becomes a built-in class as user-defined extensions are not allowed.
Does my RST source file need to be in UTF-8?
TBC.
What classes are available in standard RST?
TBC.
What additional classes are available through PG's extensions to RST?
TBC.
link to RST Index Page
