User:Monasi/My RST checklist
RST: An Introduction for Post-Processors
Overview
reStructuredText, or RST, is an easy-to-read plaintext markup syntax available to post-processors to produce books. It's easiest to understand when compared to the traditional post-processing methods.
Traditionally, a project comes into post-processing and is edited with GuiGuts. After checks have been made, two versions of the text are saved out of GuiGuts: a text version and an HTML version. Then each of these files is edited as necessary to produce the final versions. Both are sent to the PPV or are uploaded. When these files are being processed at PG, an epub is generated.
With RST, the process starts the same. After checks have been made only one file is saved, the plain text one. It need not even have been rewrapped, because it will be marked up with RST syntax. Once marked up, that single file (and any images) goes forward. Once reaching the whitewasher, the marked-up source file is used to generate all outputs posted by DP, including text, HTML, and Epub. The user doesn't need to know anything about HTML or Epub and doesn't have to worry about line lengths and rewrapping. All of that is done automatically during the generation process. The user only has to get one file right; the PPVer only has to check one file; the WWer deals with one file for production and errata.
So what is this "markup" for RST? It's very simple. For example, for a chapter header traditionally the PPer needed to ensure there were four spaces before and two after in text and that all the code was in place, including links, in HTML. With RST, the PPer simply underlines the chapter title with a series of equal signs. That's it. RST knows it's a chapter header, displays it correctly in text and HTML, build a Table of Contents entry for it, and creates a <div> there for Epub segmentation.
RST is described as a what-you-see-is-what-you-get markup syntax and parser system. Most markup is as straightforward as the chapter header example. A quick look here shows common markup examples. A more detailed manual is here.
Applicability
Though RST is compelling for many books, it is not for every book and it is not for every post-processor. It does have support for paragraphs, subdivisions and headers; italics, small-cap, bold; poetry; images; footnotes; lists and tables and other common constructions. However there are some constructions, such as sidenotes and visible page numbers, that are not currently available in RST. If a book requires semantic markup not in RST, that book should be processed with traditional post-processing methods. For many books, it's all there, as illustrated by this test document.
RST is also not for every post-processor. If a PPer wants to maintain full control over all the presentational aspects of the book, they will not be happy with RST. The RST parser makes decisions about how a blockquote will look, or how a footnote will be rendered, or what a table of contents looks like. RST is primarily semantic markup describing what something is instead of presentational markup describing what something looks like. That is by design and is at the heart of why a single markup source file can generate so many different output formats. Each generator interprets what an element is and renders it according to the format: text, HTML, Epub, PDF, etc.
Process
Anyone can use RST to post-process a suitable book, from the experienced to the brand-new PPer, and anywhere in between. If you are new, or still working towards DU status, working within GuiGuts will ensure that you have a bin file for the PPVer. If you have DU status, using GuiGuts is optional.
Follow regular procedures for checking the file for questionable hyphenation, proofers' notes, checking poetry and block quotes, removing visible page markers, moving illustrations, footnotes, etc.
If you use any of the GuiGuts text checks (Gutcheck, Word Frequency, Jeebies, spell-check routines) run through them prior to converting the file to the RST coding. In Gutcheck, I turn off certain flags, such as, short and long lines; and HTML tags and symbols. The text is not rewrapped and most of the HTML tags will be converted to RST markup.
The major difference between the "traditional" PPer and a RST PPer, is that the RST PPer works with a single-source file and doesn't have to know HTML coding to post-process a book--but the end result is the same, with both producing text and HTML versions. The bonus for the RST PPers is creating the epub at the same time.
RST: Post-Processing Tutorial
This document describes one way to post-process a DP project with reStructuredText. It is targeted at a typical PPer who uses Windows and who submits files to PPV. There are many variations possible with the same outcome: a single RST source file gets sent to the whitewasher. This one, however, is the one the RST post-processing mentors will most often refer to.
Requirements
For post-processors who don't want to use GuiGuts and who want only the bare minimums, only Python and Epubmaker are all that are needed. Both are straightforward installs on Windows or Mac.
For post-processors who typically use GuiGuts, here are the suggested pieces to produce RST:
- GuiGuts
- Python
- Epubmaker (local install or server access)
- a UTF-8 capable editor. (optional)
Post-processing sequence
This post-processing sequence is based on using guiguts. For those not using guiguts, contact DP user:rfrank.
- post-process with guiguts in Latin-1
- generate the text file with the .bin file and save both for PPV
- first two steps can be identical to the existing procedures with guiguts, though some simplification is allowed.
- make a copy of the text file and mark it up with RST.
- RST is native UTF-8, so work with a UTF-8 editor.
- convert all italics and/or bold markup to pairs of single asterisks or double for bold text
- convert any non-Latin-1 characters (such as [oe]) to their UTF-8 equivalent: œ
- convert 2-hyphen dashes to their UTF-8 equivalent: —
- convert straight quotes to smart quotes (optional)
- generate the outputs with epubmaker
- this is to check that it generates successfully. Edit only the source file if changes are needed.
- send up the text file and .bin file (from step 2) to PPV
- also send up the .rst file (and images folder, if present).
PPV sequence
- checks the provided text file using the provided .bin in GG.
- if corrections are needed, change the text file and the RST file.
- generate the outputs with epubmaker as go/no-go
- upload (only) the .rst file (and images folder, if present) to the WWer.
This skeleton view of the process will be flushed out as the first few projects go through the system.
RST: Best Practices
This page is a reference for post-processors using RST. Here, suggested best practices will be presented. These are the suggested ways of semantic and presentational markup compatible with the toolchain.
Poetry
Poetry is marked using the pipe symbol "|". Three spaces, the pipe symbol, and one space should precede each line of poetry that is left-adjusted in the original poem.
Written in a stiff little hand I read:
| "Your lips are lined with roses,
| Your eyes they shine like gold
| If you call me from the sunlight,
| I'll answer from the cold.
| But I wonder why, Oh, why,
| You stay so far from me?
| If you whisper from the prairie,
| I'll call from Calgary."
“Won't it be wonderful,” said Lossie as I sat pondering over those
foolish little lines, “won't it be wonderful, if Dinkie grows up to be
a great poet?”
Note that after the pipe symbol, the PPer can indicate relative indentation.
Epigraphs
Epigraphs typically come immediately after a chapter heading. They may contain prose:
.. epigraph::
The historical development of a particular branch of
science, such as radio telegraphy, in order to be complete and of
instructive value should, if possible, be traced thru the personal
connection therewith of all of its pioneers.
—Donald McNicol, in `Early Wireless Magazine`, Oct. 1917
The ship stole through the darkness with extremest caution...
or even poetry:
.. epigraph::
| `When you are old and grey and full of sleep,`
| `And nodding by the fire, take down this book,`
| `And slowly read, and dream of the soft look`
| `Your eyes had once, and of their shadows deep;`
—W. B. Yeats
In the dim, humid basement of his Maryland home...
Note the use of the back-tick on each line to cause it to render as italic. The attribution in each example is optional.
Chapters and Sections
Chapters should be marked with a single underline using equal signs exactly the same length as the title.
CHAPTER I: BETTY LEE’S MOST MOVING ADVENTURE ============================================ Betty Lee, aged almost fourteen, was dressing for travel. She both dreaded and anticipated the day...
The title of the book, included once at the start of the text, also uses the equal sign. However, the title must have a row of equal signs above and below:
=========================================================
BETTY LEE, FRESHMAN
=========================================================
For subsections, underline the subsection title with a row of dashes ("-") exactly as long as the subsection text. If subsections are used and if you want them to show up in the autogenerated Table of Contents, change the depth to 2:
.. contents:: Table of Contents
:backlinks: entry
:depth: 1
Block Quotes
Block quotes can be indicated by indenting the left margin at least three spaces.
Further, evidence suggests that Milton understood exactly what
it meant to retreat, Ignatian-style, into the inner self for private
imaginings:
It is better therefore to contemplate the Deity, and to conceive of him,
not with reference to human passions, that is, after the manner of men,
who are never weary of forming subtle imaginations respecting him, but
after the manner of Scripture, that is, in the way wherein God has
offered himself to our contemplation; . . . (`CE` xiv. 33)
Who are these ambiguous men who “never weary of forming subtle
imaginations”?
Block quotes may be nested.
A block quote may end with an attribution: a text block beginning with "--", "---", or a true em-dash, flush left within the block quote. If the attribution consists of multiple lines, the left edges of the second and subsequent lines must align.
Footnotes
Footnotes are typically indicated by a space, left bracket, a number, a right bracket, and an underscore.
Only an American—and I am not one except by long association [1]_—can speak for the heart of America.
Note that the space before the bracket is required and is handled by each rendering back-end. For example, in text it is removed. You can also auto-number footnotes using "[#]_" instead of a specific number. You can also use auto-symbols using "[*]_" designators. Footnote marks, starting with an asterisk, will be automatically be generated in the order defined by the The Chicago Manual of Style, 14th edition.
The footnote target is straightforward and is included here for completeness:
.. [1] Perhaps I should add that I have not been in the United
States since January 1912. My observations stretched, with
some intervals, through the forty years preceding that date.
Italics
Italics are usually the result of markup using an asterisk for emphasis.
That was *not* a good reason.
will generate the word not in "italics" usually.
However, there are times when only part of a word is to be in italics. The asterisk needs a separator so to have only the "As" in aspiration be in italics, set the asterisk marking emphasis off with a backslash+space:
“‘Inspiration,’ then,” said Carolyn. “What’ll I hitch up with? I couldn’t play a violin.” “\ *As*\ piration,” chuckled Betty. “Pick out your brightest dream, ‘Caro,’ and put on the harness!”
The backslash+space does not show up in the output when used in this way.
Small Caps
Small caps are not part of the base RST specification, however they are easily added using methods provided for such extensions. If you have small caps in your book and want to retain them, first put these two lines near the start of the book, typically after the encoding directive:
.. role:: small-caps
:class: small-caps
Then, in text, use
:small-caps:`The rain` wouldn't stop.
The two words "The rain" will be presented in small caps. Note: EpubMaker has a class for small-caps built in. Users of rst2html need small caps defined in their working CSS file. It's one line of CSS: .small-caps { font-variant: small-caps }
TOC/LOI
RST can generate a Table of Contents with links and backlinks to each chapter with the simple directive:
.. contents:: Table of Contents
:backlinks: entry
:depth: 1
However, the PPer does not have to use that directive. The Table of Contents or a List of Illustrations can be marked-up manually as well, using internal links to the chapters. Here's how to do that for the TOC and LOI.
For the Table of Contents, this construction works well:
.. class: larger **CONTENTS** I. `Swickey Shoots a Bear`_ II. `Lost Farm Folk`_ III. `Much Ado about Beelzebub`_ IV. `The Compact`_
Then, the target for the first chapter is
.. _`Swickey Shoots a Bear`: CHAPTER I—SWICKEY SHOOTS A BEAR =============================== Old man Avery hurried from the woods...
Each chapter is marked as an explicit internal hyperlink as shown.
For a List of Illustrations, this construction works well:
.. class: larger **ILLUSTRATIONS** | `"Where be they?" she whispered`_ | `"Here's your game," he said hoarsely`_ | `"I didn't know, Swickey—I thought—there was someone else"`_
The target for the first illustration is then:
.. _`"Where be they?" she whispered`:
.. figure:: images/camp-076.jpg
:align: center
"WHERE BE THEY?" SHE WHISPERED
Tables
There are two syntaxes for tables in reStructuredText. Grid tables are complete but cumbersome to create. Simple tables are easy to create but limited. Here are examples of each for reference. First a simple table.
===== ===== ======
Inputs Output
------------ ------
A B A or B
===== ===== ======
False False False
True False True
False True True
True True True
===== ===== ======
Note the pattern of the "=====" to indicate the rows. Now a grid table:
+------------+------------+-----------+ | Header 1 | Header 2 | Header 3 | +============+============+===========+ | body row 1 | column 2 | column 3 | +------------+------------+-----------+ | body row 2 | Cells may span columns.| +------------+------------+-----------+ | body row 3 | Cells may | - Cells | +------------+ span rows. | - contain | | body row 4 | | - blocks. | +------------+------------+-----------+
RST markup is not appropriate for books containing tables with more advanced requirements.
Escaping
Sometimes a line of text entered as presented in the original book will trigger RST into thinking it is markup.
A. Einstein
should be written with a leading backslash:
\A. Einstein
so the parser doesn't think it is the start of a list (A., B, C. etc.)
Superscripts, subscripts
These are used infrequently:
For superscript. E = mc\ :superscript:`2` For subscript. H\ :subscript:`2`\ O For references to titles of works, eg. :title-reference:`Hamlet`. For code blocks. :literal:`print 'Hello, World!'`
Vertical Space
Vertical space can be produced in two ways. One is as recommended in standard RST. The other is to use a non-standard presentation markup extension defined in EpubMaker. Considering only the first method, here is an example of the front matter of a book using vertical spacing between original pages:
.. class:: align-center
|
|
BETTY LEE, FRESHMAN
By
HARRIET PYNE GROVE
.. image:: images/illus-emb.jpg
:align: center
.. class:: align-center
THE WORLD SYNDICATE PUBLISHING CO.
Cleveland, Ohio — New York City
|
|
Copyright, 1931
by
THE WORLD SYNDICATE PUBLISHING CO.
.. image:: images/illus-em2.jpg
:align: center
.. class:: align-center italics
Printed in the United States of America
Note the vertical "pipe" symbols with three spaces to the left. Each of these will generate a single blank line at that point in the output. The result is shown on the title page here.
There is no need to provide vertical space where markup implies the spacing already. For example, if a chapter header is indicated the appropriate spacing before and after will be applied automatically. Typically, PPers will use the "|" symbol to create a vertical space only in front matter, like the title page, and in back matter, typically advertisement pages.
UTF-8
You should use UTF-8 for RST markup. The standard header for a RST file submitted to PG has this as the first line:
.. -*- encoding: utf-8 -*-
The tools used by the WWer's to produce the book start with the UTF-8 file as submitted and generate the Latin-1 and plain ASCII files from that. Note that GuiGuts was written to handle UTF-8 characters. PPers who use GG will save their RST source file as UTF-8 by default if any UTF-8 characters are in the file.
Roles
Roles allow limited styling to RST markup. For example to have some words in small caps:
.. role:: small-caps
:class: small-caps
This text is in :small-caps:`Small Caps`.
You can attach more than one class to a role:
.. role:: big-and-bold
:class: larger bold
This text is :big-and-bold:`big and bold`.
PPers are limited to classes that are part of EpubMaker. For example, there is a class "larger" but not one for "x-large".
Sidenotes
writeup in progress.
Title Page
Most of any book is a series of pages with little formatting. The title page, as printed, often has considerable formatting for appearance. RST is not strong on presentational markup, by design. Semantic markup is its strength, which is appropriate for a one-source, many-output solution.
You can produce a reasonable title page with RST—not a facsimile but something that is recognizable as a title page in text, HTML and in the generated Epub. Here is the source to a title page with line numbers added for reference:
1 .. -*- encoding: utf-8 -*-
2
3 =========================================================
4 THE INVISIBLE CENSOR
5 =========================================================
6
7 .. class:: align-center larger bold
8
9 THE INVISIBLE CENSOR
10
11 .. class:: align-center
12
13 By
14
15 .. class:: align-center larger
16
17 FRANCIS HACKETT
18
19 .. image:: images/illus-emb.png
20 :align: center
21
22 .. class:: align-center
23
24 | New York
25 | \B. W. HUEBSCH, INC.
26 | MCMXXI
27 |
28 |
29 |
30 |
31 | Copyright, 1921,
32 | by B. W. Huebsch, Inc.
33 | Printed in U. S. A.
34 |
35 |
36 |
37 |
38 | TO MY WIFE
39 | SIGNE TOKSVIG
40 |
41 | WHOSE LACK OF INTEREST IN THIS BOOK
42 | HAS BEEN MY CONSTANT DESPERATION
43 |
44 |
45 |
46
47 These sketches and articles appeared in the
48 *New Republic* and I am indebted to the other
49 editors for being allowed to reprint them.
50
51 .. contents:: Table of Contents
52 :backlinks: entry
53 :depth: 1
What is shown is from the first line of the document up to the start of the first chapter. Here are some explanations:
- line 1 The document is in UTF-8. If you've edited it in Latin-1, convert to UTF-8 before presenting it to epubmaker.
- lines 3-5 The name of the book.
- line 7: The next line of text will be centered, larger, and bold (the title on the title page)
- line 11 and line 15: slightly different presentations for the next two lines
- lines 19,20: a decorative emblem
- line 22 and all of lines 24-45: the first line says to center everything following. The "|" symbol keeps it together as a block and allows vertical spacing. Note the separation by four spaces as is DP's convention. There are only three at the end because any line block group has a blank line after it automatically.
- line 25: The leading escape is required or this line will be interpreted as part of a list and not an abbreviation.
- lines 47-49: This will be rendered as a block quote.
- line 51: The TOC will be autogenerated for this book.
- line 52: Clicking on the chapter title will take the reader back to the TOC.
- line 53: This book has chapters and sections and only the chapters should show up in the TOC.
There is no RST or DP standard for this. This "best practices" entry is only an example.
Meta Information
Every RST file submitted to Project Gutenberg must have a meta-information block near the top of the file, below the title block. The meta information is not required during early stages of post-processing, but it is not harmful.
Here is the start of an example file as submitted to the WW:
.. -*- encoding: utf-8 -*-
===================
BETTY LEE, FRESHMAN
===================
.. meta::
:PG.Id:
:PG.Title: Betty Lee, Freshman
:PG.Released:
:PG.Rights: Public Domain
:PG.Producer: Roger Frank
:PG.Producer: the Online Distributed Proofreading Team at http://www.pgdp.net
:DC.Creator: Harriet Pyne Grove
:DC.Title: Betty Lee, Freshman
:DC.Language: en
:DC.Created: 1931
:coverpage: images/cover.jpg
The post-processor has this information readily available. Note The PG.Id and PG.Released fields can be left blank for the WWers to fill in when an etext number is assigned and the book is posted. Post-processors should make sure the PG.Producer line(s), the two Title fields and the Creator field should all agree with the upload info.
The submitted file must also include the .. pgheader:: and .. pgfooter:: directives as shown in the examples.
Finally, if the post-processor has provided a cover image, include the last line indicating the filename to use, else omit the last line entirely.
RST: PG Extensions to RST
EpubMaker generates all the outputs from RST source files at Project Gutenberg (PG). It includes non-standard extensions to RST that are included here for post-processors who want to use them. Using these features assures that the resulting RST source file is only usable at Project Gutenberg and in particular, with EpubMaker. The "in the wild" tools, like rst2html, rst2latex, etc. will not work with RST source files that have added these extensions.
There is an effort to get at least some of these features into the standard RST specification. For many, once that happens these currently non-standard extensions will become viable. For others, these extensions are part of EpubMaker now.
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 beginning of the word instead. Example:
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.
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]_.
An invisible page number can be inserted with the sequence "[pg!n]".
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.
Dropcaps
The first argument is required. It is the character(s) to replace. This argument must match the beginning of the next paragraph.
.. dropcap:: L 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 second argument is optional. It is an image url. If this argument is present, the image will replace the character.
.. dropcap:: G images/G.png Gorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.
Line Break
Line breaks are for when you absolutely need it. Spaces are required around the linebreak tag.
Copyright 1917 by Grosset & Dunlap :linebreak: All rights reserved.
TOC entry
Sometimes the TOC entry for a chapter is different that the words used in the chapter heading itself.
.. toc-entry:: Section III — Beyond the Frontier BEYOND THE FRONTIER ===================
RST: Installation Guide
This is where we explain how to install Python and related support tools for RST on Windows and on Mac/Linux. Names in parenthesis are who we hope will be able to fill in that section.
Package Descriptions
These are the instructions for installing software to support RST on Windows. Python is required for all other packages. Most DP users will only install rst2html to generate HTML from their RST source.
python
Most PPers are familiar with Perl, the computer language used in GuiGuts. Python just another computer language. It is the language used for the other tools shown on this page. Users must install Python to be able to use these tools. There are two versions of Python out right now: version 2 and version 3. All instructions in this section presume you will be using Python version 2. Most users will be using 2.7, the latest stable release.
epubmaker
epubmaker is a locally installable subset of the software used at Project Gutenberg to convert between formats. Epubmaker can convert:
- from HTML to EPUB, or
- from RST to HTML, EPUB, and plain text in utf-8, iso-8859-1 and us-ascii flavours.
PPers can use the plain text files for checking with the usual DP tools.
You can check which version of epubmaker is current at: http://pypi.python.org/pypi/epubmaker
Windows Installation
Python
Windows XP
These instructions are for a new install of Python on a Window XP system only. If you already have a version installed (other than PYTHON 3 which will not run the rst2html.py program at this time), you don't need to download the latest version (2.7.1), unless you want to. I am using version 2.6.2 with no problems.
To install Python 2.7 on Windows XP systems:
- go HERE to the Python download page.
- download the "Windows X86 MSI installer (2.7)."
- when downloaded, double-click to install.
Next, add Python 2.7 to your PATH statement:
- click Start | Control Panel | System | Advanced | Environment Variables.
- find and double-click on the "PATH" line in the "System variables" box.
- right arrow to the end of the PATH line and type in ";C:\Python27" without the quotes. Make sure there is no space before or after the semi-colon. (there is no dot between 2 and 7)
- click OK three times.
To check installation:
- click Start | Run and enter "cmd" (no quotes) and press the ENTER key.
- in the command window that pops up, type "python --version" (without the quotes) and press the ENTER key.
- Python should announce itself.
epubmaker
The epubmaker program requires Python setup tools. From http://pypi.python.org/pypi/setuptools download "setuptools-0.6c11.win32-py2.7.exe" (or any newer version) and run it.
The epubmaker program requires Groff to generate 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.
Modify the path statement (similar to as done above for Python)
Start | Control Panel | System | Advanced | Environment Variables. Click "Path" in the User variables at the top. Click "Edit" Add a semicolon if there isn't one at the end already and then type this: c:\python27\Scripts;C:\Program Files\GnuWin32\bin; click Ok three times.
Open a command window and type
easy_install epubmaker
Check the installation:
epubmaker --help
RST: EpubMaker Guide
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.
Usage
Note: This usage reflects epubmaker >= 0.3.2. Update your epubmaker installlation with:
easy_install -U epubmaker
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.
RST: Resources
There are many resources available for those wanting to learn and use RST.
Web Resources
A ReStructuredText Primer In this document, the author begins: “From the outset, let me say that ‘Structured Text’ is probably a bit of a misnomer. It's more like ‘Relaxed Text’ that uses certain consistent patterns.” This primer introduces these patterns in a conversational style and is a good starting point.
Quick reStructuredText This is a quick reference to the markup available with RST. It is presented in tabular form, with markup on the left and resulting output on the right. It's an excellent reference when adding post-processing markup.
reStructuredText Markup Specification This is the full specification for reStructuredText with links to extensions to RST.
Sample Texts
A contrived text including many of the constructions post-processors may want to use is here. The RST source for that file is zipped here.