Producing an Ebook, Step by Step
This guide is meant to take you step-by-step through the creation of a complete Standard Ebook. While it might seem a little long, most of the text is a description of how to use various automated scripts. It can take just an hour or two for an experienced producer to produce a draft ebook for proofreading (depending on the complexity of the ebook, of course).
Download and set up the Standard Ebooks production toolset
The Standard Ebooks project has a toolset that will help you produce an ebook. Read how to install them here.
Make sure you take a moment to put the
seexecutable that’s installed with the toolset on your shell’s
$PATH. How to do that varies depending on what shell you’re using.
Make sure the toolset is up-to-date
The toolset changes frequently. If this isn’t your first ebook production, always make sure to update the toolset before you start a new ebook, so that you’re working with the latest version of the tools.
pip3 install --upgrade standardebooks
Select an ebook to produce
The best place to look for public domain ebooks to produce is Project Gutenberg. If downloading from Gutenberg, be careful of the following:
There may be different versions of the same publication on Gutenberg, and the best one might not be the one with the most downloads. In particular, there could be a better translation that has fewer downloads because it was produced later, or there could be a version with better HTML markup. A great example of this phenomenon is the Gutenberg version of 20,000 Leagues Under the Seas. The most-Vdownloaded version is an old translation widely criticized as being slapdash and inaccurate. The less popular version is a fresh, modern translation dedicated to the public domain.
Gutenberg usually offers both an HTML version and an epub version of the same ebook. Note that one is not always exactly the same as the other! A casual reader might assume that the HTML version is generated from the epub version, or the other way around; but for some reason the HTML and epub versions often differ in important ways, with the HTML version typically using fewer useless CSS classes, and including
<em>tags that the epub version is often missing.
Picking either the HTML or the epub version is fine as a starting point, but make sure to pick the one that appears to be the most accurate.
For this guide, we’ll use The Strange Case of Dr. Jekyll and Mr. Hyde, by Robert Louis Stevenson. If you search for it on Gutenberg, you’ll find that there are two versions; the most popular one is a poor choice to produce, because the transcriber included the page numbers smack in the middle of the text! What a pain those’d be to remove. The less popular one is a better choice to produce, because it’s a cleaner transcription.
Locate page scans of your book online
As you produce your book, you’ll want to check your work against the actual page scans. Often the scans contain formatting that is missing from the source transcription. For example, older transcriptions sometimes throw away italics entirely, and you’d never know unless you looked at the page scans. So finding page scans is essential.
Below are some good sources for page scans:
Each of those sources allows you to filter results by publication date, so make sure you select 1923 and earlier to ensure they’re in the US public domain.
If you can’t find scans of your book at the above sources, and you’re using a Project Gutenberg transcription as source material, there’s a good chance that PGDP (the sister project of Project Gutenberg that does the actual transcriptions) has a copy of the scans they used accessible in their archives. You should only use the PGDP archives as a last resort; because their scans are not searchable, verifying typos becomes extremely time-consuming.
Please keep the following important notes in mind when searching for page scans:
Make sure the scans you find are published in 1923 or earlier. You must verify the copyright page in the page scans before proceeding.
Often you’ll find different editions, published at different times by different publishers, for the same book. It’s worth the effort to quickly browse through each different one to get an idea of the kinds of changes the different publishers introduced. Maybe one edition is better than another!
You’ll enter a link to the page scans you used in the
content.opfmetadata as a
Create a Standard Ebooks epub skeleton
An epub file is just a bunch of files arranged in a particular folder structure, then all zipped up. That means editing an epub file is as easy as editing a bunch of text files within a certain folder structure, then creating a zip file out of that folder.
You can’t just arrange files willy-nilly, though—the epub standard expects certain files in certain places. So once you’ve picked a book to produce, create the basic epub skeleton in a working directory.
se create-draftwill create a basic Standard Ebooks epub folder structure, initialize a
gitrepository within it, and prefill a few fields in
content.opf(the file that contains the ebook’s metadata).
You can pass
se create-draftthe URL for the Project Gutenberg ebook, and it’ll try to download the ebook into
./src/epub/text/body.xhtmland prefill a lot of metadata for you:
se create-draft --author="Robert Louis Stevenson" --title="The Strange Case of Dr. Jekyll and Mr. Hyde" --gutenberg-ebook-url="https://www.gutenberg.org/ebooks/43" cd robert-louis-stevenson_the-strange-case-of-dr-jekyll-and-mr-hyde/
Because Project Gutenberg ebooks are produced in different ways by different people,
se create-drafthas to make some guesses and it might guess wrong. Make sure to carefully review the data it prefills into
In particular, make sure that the Project Gutenberg license is stripped from
./src/epub/text/body.xhtml, and that the original transcribers in
./src/epub/content.opfare presented correctly.
If you prefer to do things by hand, that’s an option too.
se create-draft --author="Robert Louis Stevenson" --title="The Strange Case of Dr. Jekyll and Mr. Hyde" cd robert-louis-stevenson_the-strange-case-of-dr-jekyll-and-mr-hyde/
Now that we have the skeleton up, we’ll download Gutenberg’s HTML file for Jekyll directly into
text/folder and name it
wget -O src/epub/text/body.xhtml https://www.gutenberg.org/files/43/43-h/43-h.htm
Many Gutenberg books were produced before UTF-8 became a standard, so we may have to convert to UTF-8 before we start work. First, check the encoding of the file we just downloaded. (Mac OS users, try
file -bi src/epub/text/body.xhtml
The output is
text/html; charset=iso-8859-1. That’s the wrong encoding!
We can convert that to UTF-8 with
iconv --from-code="ISO-8859-1" --to-code="UTF-8" < src/epub/text/body.xhtml > src/epub/text/tmp mv src/epub/text/tmp src/epub/text/body.xhtml
Do a rough cleanup of the source text and perform the first commit
If you inspect the folder we just created, you’ll see it looks something like this:
You can learn more about what the files in a basic Standard Ebooks source folder are all about before you continue.
Now that we’ve got the source text, we have to do some very broad cleanup before we perform our first commit:
Remove the header markup and everything, including any Gutenberg text and the work title, up to the beginning of the actual public domain text. We’ll add our own header markup to replace what we’ve removed later.
Jekyll doesn’t include front matter like an epigraph or introduction; if it did, that sort of stuff would be left in, since it’s part of the main text.
This edition of Jekyll includes a table of contents; remove that too. Standard Ebooks uses the ToC generated by the ereader, and doesn’t include one in the readable text.
Remove any footer text and markup after the public domain text ends. This includes the Gutenberg license—but don’t worry, we’ll credit Gutenberg in the colophon and metadata later. If you invoked
se create-draftwith the
--gutenberg-ebook-urloption, then it may have already stripped the license for you and included some Gutenberg metadata.
Now our source file looks something like this:
<h2> STORY OF THE DOOR </h2> <p> Mr. Utterson the lawyer was a man of a rugged countenance that was never lighted by a smile; cold, scanty and embarrassed in discourse; backward in <!--snip all the way to the end...--> proceed to seal up my confession, I bring the life of that unhappy Henry Jekyll to an end. </p>
Now that we’ve removed all the cruft from the top and bottom of the file, we’re ready for our first commit.
Please use the following commit message for consistency with the rest of our ebooks:
git add -A git commit -m "Initial commit"
Split the source text at logical divisions
The file we downloaded contains the entire work. Jekyll is a short work, but for longer work it quickly becomes impractical to have the entire text in one file. Not only is it a pain to edit, but ereaders often have trouble with extremely large files.
The next step is to split the file at logical places; that usually means at each chapter break. For works that are contain their chapters in larger “parts,” the part division should also be its own file. For example, see Treasure Island.
To split the work, we use
se split-filetakes a single file and breaks it in to a new file every time it encounters the markup
se split-fileautomatically includes basic header and footer markup in each split file.
Notice that in our source file, each chapter is marked with an
h2tag. We can use that to our advantage and save ourselves the trouble of adding the
<!--se:split-->markup by hand:
perl -pi -e "s/<h2/<\!--se:split--><h2/g" src/epub/text/body.xhtml
(Note the slash before the ! for compatibility with some shells.)
Now that we’ve added our markers, we split the file.
se split-fileputs the results in our current directory and conveniently names them by chapter number.
se split-file src/epub/text/body.xhtml mv chapter* src/epub/text/
Once we’re happy that the source file has been split correctly, we can remove it.
Clean up the source text
If you open up any of the chapter files we now have in the
src/epub/text/folder, you’ll notice that the code isn’t very clean. Paragraphs are split over multiple lines, indentation is all wrong, and so on.
If you try opening a chapter in a web browser, you’ll also likely get an error if the chapter includes any HTML entities, like
—. This is because Gutenberg uses plain HTML, which allows entities, but epub uses XHTML, which doesn’t.
We can fix all of this pretty quickly using
se cleanaccepts as its argument the root of a Standard Ebook directory, and with the
--single-linesoption it’ll remove the hard line wrapping that Gutenberg is fond of. We’re already in the root, so we pass it
se clean --single-lines .
Things look much better now, but we’re not perfect yet. If you open a chapter you’ll notice that the
<h2>tags have a space between the tag and the text. We can clean that up with a few
perl -pi -e "s/<(p|h2)>\s+/<\1>/g" src/epub/text/chapter* perl -pi -e "s/\s+<\/(p|h2)>/<\/\1>/g" src/epub/text/chapter*
Finally, we have to do a quick runthrough of each file by hand to cut out any lingering Gutenberg markup that doesn’t belong. In Jekyll, notice that each chapter ends with some extra empty
<p>s. These were used by the original transcriber to put spaces between the chapters, and they’re not necessary anymore, so remove them before continuing.
Now our chapter 1 source looks like this:
<?xml version="1.0" encoding="UTF-8"?> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" epub:prefix="z3998: http://www.daisy.org/z3998/2012/vocab/structure/, se: http://standardebooks.org/vocab/1.0" xml:lang="en-US"> <head> <title>Chapter 1</title> <link href="../css/core.css" rel="stylesheet" type="text/css"/> <link href="../css/local.css" rel="stylesheet" type="text/css"/> </head> <body epub:type="bodymatter z3998:fiction"> <section id="chapter-1" epub:type="chapter"> <h2>STORY OF THE DOOR</h2> <p>Mr. Utterson the lawyer was a man of a rugged countenance...</p> <!--snip all the way to the end...--> <p>"With all my heart," said the lawyer. "I shake hands on that, Richard."</p> </section> </body> </html>
If you look carefully, you’ll notice that the
<html>tag has the
xml:lang="en-US"attribute, even though our source text uses British spelling! We have to change the
xml:langattribute for the source files to match the actual language, which in this case is en-GB. Let’s do that now:
perl -pi -e "s|en-US|en-GB|g" src/epub/text/chapter*
Note that we don’t change the language for the metadata or front/back matter files, like
colophon.xhtml. Those must always be in American spelling, so they’ll always have the en-US language tag.
Typogrify the source text and perform the second commit
Now that we have a clean starting point, we can start getting the real work done.
se typogrifycan do a lot of the heavy lifting necessary to bring an ebook up to Standard Ebooks typography standards.
se typogrifyaccepts as its argument the root of a Standard Ebook directory.
se typogrify .
Among other things,
se typogrifydoes the following:
Converts straight quotes to curly quotes;
Adds no-break spaces where appropriate for some common abbreviations;
Normalizes spacing in em-, en-, and double-em-dashes, as well as between nested quotation marks, and adds word joiners.
You can run
se typogrifyas many times as you want on a source directory; it should always produce the same result, regardless of what state the source directory was in when you ran it.
se typogrifydoes a lot of work for you, each ebook is totally different so there’s almost always more work to do that can only be done by hand. In Jekyll, you’ll notice that the chapter titles are in all caps. The SE standard requires chapter titles to be in title case, and
se titlecasecan do that for us.
se titlecaseaccepts a string as its argument, and outputs the string in title case. Many text editors allow you to configure external macros—perfect for creating a keyboard shortcut to run
se titlecaseon selected text.
There are many things that
se typogrifyisn’t well suited to do automatically. Check our complete typography manual to see exactly how to format the work. Below is a brief, but incomplete, list of common issues that arise in ebooks:
Typography rules for coordinates. Use the prime and double prime glyphs for coordinates. These regexes helps match and replace coordinates:
Typography rules for ampersands in names. This regex helps match candidates:
Typography rules for text in all caps. Text in all caps is almost never correct, and should either be converted to lowercase with the
<em>tag (for spoken emphasis),
<strong>(for extreme spoken emphasis), or
<b>(for unsemantic small caps, like in storefront signs). This case-sensitive regex helps find candidates:
se typogrifydoesn’t close quotation marks near em-dashes correctly. Try to find such instances with this regex:
Commas and periods should generally be inside quotation marks, not outside. This regex helps find them:
The second commit
Once you’ve run
se typogrifyand you’ve searched the work for the common issues above, you can perform your second commit.
git add -A git commit -m "Typogrify"
Convert footnotes to endnotes and add a list of illustrations
Works often include footnotes, either added by an annotator or as part of the work itself. Since ebooks don’t have a concept of a “page,” there’s no place for footnotes to go. Instead, we convert footnotes to a single endnotes file, which will provide popup references in the final epub.
The endnotes file and the format for endnote links are standardized in the semantics manual.
If you find that you accidentally mis-ordered an endnote, never fear!
se reorder-endnoteswill allow you to quickly rearrange endnotes in your ebook.
If a work has illustrations besides the cover and title pages, we include a “list of illustrations” at the end of the book, after the endnotes but before the colophon. The LoI file is also standardized in the semantics manual.
Jekyll doesn’t have any footnotes, endnotes, or illustrations, so we skip this step.
Converting British quotation to American quotation
If the work you’re producing uses British quotation style (single quotes for dialog versus double quotes in American), we have to convert it to American style. We use American style in part because it’s easier to programmatically convert from American to British than it is to convert the other way around. Skip this step if your work is already in American style.
se british2americanattempts to automate the conversion. Your work must already be typogrified (the previous step in this guide) for the script to work.
se british2american .
se british2americantries its best, thanks to the quirkiness of English punctuation rules it’ll invariably mess some stuff up. Proofreading is required after running the conversion.
After you’ve run the conversion, do another commit.
git add -A git commit -m "Convert from British-style quotation to American style"
Part of the Standard Ebooks project is adding meaningful semantics wherever possible in the text.
se semanticatedoes a little of that for us—for example, for some common abbreviations—but much of it has to be done by hand.
Adding semantics means two things:
Using meaningful tags to mark up the work:
<em>when conveying emphatic speech instead of
<abbr>to wrap abbreviations,
<section>to mark structural divisions, using the
xml:langattribute to specify the language of a word or passage, and so on.
Using the epub3 semantic inflection language to add deeper meaning to tags.
Currently we use a mix of epub3 structural semantics, z3998 structural semantics for when the epub3 vocabulary isn’t enough, and our own SE semantics for when z3998 isn’t enough.
se semanticateto do some common cases for you:
se semanticate .
se semanticatetries its best to correctly add semantics, but sometimes it’s wrong. For that reason you should review the changes it made before accepting them:
Beyond that, adding semantics is mostly a by-hand process. See our semantics manual for a detailed list of the kinds of semantics we expect in a Standard Ebook.
Here’s a short list of some of the more common semantic issues you’ll encounter:
Semantics for italics:
<em>should be used for when a passage is emphasized, as in when dialog is shouted or whispered.
<i>is used for all other italics, with the appropriate semantic inflection. Older transcriptions usually use just
<i>for both, so you must change them manually if necessary.
Semantics rules for abbreviations. Abbreviations should always be wrapped in the
<abbr>tag and with the correct
Specifically, see the typography rules for initials. Wrap people’s initials in
<abbr class="name">. This regex helps match initials:
Typography rules for times. Wrap a.m. and p.m. in
<abbr class="time">and add a no-break space between digits and a.m. or p.m.
Words or phrases in foreign languages should always be marked up with
<i xml:lang="TAG">, where TAG is an IETF language tag. This app can help you look them up. If the text uses fictional or unspecific languages, use the “x-” prefix and make up a subtag yourself.
Semantics for poetry, verse, and song: Many Gutenberg productions use the
<pre>tag to format poetry, verse, and song. This is, of course, semantically incorrect. See the Poetry section of our semantics manual for templates on how to semantically format poetry, verse, and song.
After you’ve added semantics according to the semantics manual, do another commit.
git add -A git commit -m "Semanticate"
Modernize spelling and hyphenation
Many older works use outdated spelling and hyphenation that would distract a modern reader. (For example, “to-night” instead of “tonight”).
se modernize-spellingautomatically removes hyphens from words that used to be compounded, but aren’t anymore in modern English spelling.
Do run this tool on prose. Don’t run this tool on poetry.
se modernize-spelling .
After you run the tool, you must check what the tool did to confirm that each removed hyphen is correct. Sometimes the tool will remove a hyphen that needs to be included for clarity, or one that changes the meaning of the word, or it may result in a word that just doesn’t seem right. Re-introducing a hyphen is OK in these cases.
Here’s a real-world example of where
se modernize-spellingmade the wrong choice: In The Picture of Dorian Gray chapter 11, Oscar Wilde writes:
He possessed a gorgeous cope of crimson silk and gold-thread damask…
se modernize-spellingwould replace the dash in
gold-threadso that it reads
goldthreadis an actual word, which is why it’s in our dictionary, and why the script makes a replacement—but it’s the name of a type of flower, not a golden fabric thread! In this case,
se modernize-spellingmade an incorrect replacement, and we have to change it back.
gitprovides a handy way for us to visualize these differences:
After you’ve reviewed the changes that the tool made, do another commit. This commit is important, because it gives purists an avenue to revert modernizing changes to the original text.
Note how we preface this commit with “[Editorial]”. Any change you make to the source text that can be considered a modernization or editorial change should be prefaced like this, so that the
githistory can be easily searched by people looking to revert changes.
git add -A git commit -m "[Editorial] Modernize hyphenation and spelling"
Modernize spacing in select words
Over time, spelling of certain common two-word phrases has evolved into a single word. For example, “someone” used to be the two-word phrase “some one,” which would read awkwardly to modern readers. This is our chance to modernize such phrases.
Note that we use
se interactive-srto perform an interactive search and replace, instead of doing a global, non-interactive search and replace. This is because some phrases caught by the regular expression should not be changed, depending on context. For example, "some one" in the following snippet from Anton Chekhov’s short fiction should not be corrected:
He wanted to think of some one part of nature as yet untouched...
Use the following regular expression invocations to correct a certain set of such phrases:
se interactive-sr "/\v([Ss])ome one/\1omeone/" src/epub/text/* git commit -am "[Editorial] some one -> someone"
se interactive-sr "/\v(<[Aa])ny one/\1nyone/" src/epub/text/* git commit -am "[Editorial] any one -> anyone"
se interactive-sr "/\v([Ee])very one(\s+of)@\!/\1veryone/" src/epub/text/* git commit -am "[Editorial] every one -> everyone"
se interactive-sr "/\v([Ee])very thing/\1verything/" src/epub/text/* git commit -am "[Editorial] every thing -> everything"
se interactive-sr "/\v(<[Aa])ny thing/\1nything/" src/epub/text/* git commit -am "[Editorial] any thing -> anything"
se interactive-sr "/\v([Ff])or ever(>)/\1orever\2/" src/epub/text/* git commit -am "[Editorial] for ever -> forever"
se interactive-sr "/\v(in\s+)@<\!(<[Aa])ny way/\1nyway/" src/epub/text/* git commit -am "[Editorial] any way -> anyway"
se interactive-sr "/\v([Yy])our self/\1ourself/" src/epub/text/* git commit -am "[Editorial] your self -> yourself"
se interactive-sr "/\v([Mm])ean time/\1eantime/" src/epub/text/* git commit -am "[Editorial] mean time -> meantime"
se interactive-sr "/\v([Aa])ny how/\1nyhow/" src/epub/text/* git commit -am "[Editorial] any how -> anyhow"
se interactive-sr "/\v([Aa])ny body/\1nybody/" src/epub/text/* git commit -am "[Editorial] any body -> anybody"
se interactive-sr "/\v([Ee])very body/\1verybody/" src/epub/text/* git commit -am "[Editorial] every body -> everybody"
Create the cover image
Cover images for Standard Ebooks books have a standardized layout. The bulk of the work you’ll be doing is locating a suitable public domain painting to use. See our complete art manual for details on assembling a cover image.
As you search for an image, keep the following in mind:
Cover images must be in the public domain. Thanks to quirks in copyright law, this is harder to decide for paintings than it is for published writing. In general, Wikipedia is a good starting point for deciding if a work is in the public domain, but very careful research is required to confirm that status.
Find the largest possible cover image you can. Since the final image is 1400 × 2100, having to resize a small image will greatly reduce the quality of the final cover.
The image you pick should be a “fine art” oil painting so that all Standard Ebooks have a consistent cover style. This is actually easier than you think, because it turns out most public domain artwork is from the era of fine art.
You must provide proof of public domain status to the SE Editor-in-Chief in the form of a page scan of the painting from a 1923-or-older book, and the Editor-in-Chief must approve your selection before you can commit it to your repository.
The Standard Ebooks Editor-in-Chief has the final say on the cover image you pick, and it may be rejected for, among other things, poor public domain status research, being too low resolution, not fitting in with the “fine art” style, or being otherwise inappropriate for your ebook.
What can we use for Jekyll? In 1885 Albert Edelfelt painted a portrait of Louis Pasteur in a laboratory. A crop of the lab equipment would be a good way to represent Dr. Jekyll’s lab.
The cover file itself,
cover.svg, is easy to edit. It automatically links to
cover.jpg. All you have to do is open
cover.svgwith a text editor and edit the title and author. Make sure you have the League Spartan font installed on your system!
After we’re done with the cover, we’ll have three files in
cover.source.jpgis the raw image file we used for the cover. We keep it in case we want to make adjustments later. For Jekyll, this would be the raw Pasteur portrait downloaded from Wikipedia.
cover.jpgis the scaled cover image that
cover.svglinks to. This file is exactly 1400 × 2100. For Jekyll, this is a crop of
cover.source.jpgthat includes just the lab equipment, and resized up to our target resolution.
cover.svgis the completed cover image with the title and author.
se build-imageswill take
cover.jpg, convert the text to paths, and place the result in
./src/epub/images/for inclusion in the final epub.
Create the titlepage image, build both the cover and titlepage, and commit
Titlepage images for Standard Ebooks books are also standardized. See our the art manual for details.
se create-draftalready created a completed titlepage for you. If the way it arranged the lines doesn’t look great, you can always edit the titlepage to make the arrangement of words on each line more aesthetically pleasing. Don’t use a vector editing program like Inkscape to edit it. Instead, open it up in your favorite text editor and type the values in directly.
The source images for both the cover and the titlepage are kept in
./images/. Since the source images refer to installed fonts, and since we can’t include those fonts in our final ebook without having to include a license, we have to convert that text to paths for final distribution.
se build-imagesdoes just that.
se build-images .
se build-imagestakes both
./images/titlepage.svg, converts text to paths, and embeds the cover jpg. The output goes to
Once we built the images successfully, perform a commit.
git add -A git commit -m "Add cover and titlepage images"
content.opfis the file that contains the ebook metadata like author, title, description, and reading order. Most of it will be filling in that basic information, and including links to various resources related to the text.
content.opfis standardized. Please see our extensive Metadata Manual for details on how to fill out
As you complete the metadata, you’ll have to order the spine and the manifest in this file. Fortunately, Standard Ebooks has a tool for that too:
se print-manifest-and-spine. Run this on our source directory and, as you can guess, it’ll print out the
<spine>tags for this work.
If you’re using a Mac, and thus the badly-behaved Finder program, you may find that it has carelessly polluted your work directory with useless
.DS_Storefiles. Before continuing, you should find a better file manager program, then delete all of that litter with the following command. Otherwise,
se print-manifest-and-spinewill include that litter in its output and your epub won’t be valid.
find . -name ".DS_Store" -type f -delete
Since this is the first time we’re editing
content.opf, we’re OK with replacing both the manifest and spine tags with a guess at the correct contents. We can do this using the
--in-placeoption. If we have to update the manifest or spine later, we can omit the option to print to standard output instead of altering
se print-manifest-and-spine --in-place .
The manifest is already in the correct order and doesn’t need to be edited. The spine, however, will have to be reordered to be in the correct reading order. Once you’ve done that, commit!
git add -A git commit -m "Complete content.opf"
Complete the table of contents
The table of contents is a structured document that should let the reader easily navigate the book. In a Standard Ebook, it’s stored outside of the readable text directory with the assumption that the reading system will parse it and display a navigable representation for the user.
Once you’ve completed the
content.opf, you can use
se print-tocto generate a table of contents for this ebook. Since this is the first time we’re generating a ToC for this ebook, use the
--in-placeflag to replace the template ToC file with the generated ToC.
se print-toc --in-place .
Review the generated ToC in
./src/epub/toc.xhtmlto make sure
se print-tocdid the right thing.
se print-tocis valuable tool to discover structural problems in your ebook. If an entry is arranged in a way you weren’t expecting, perhaps the problem isn’t with
se print-toc, but with your HTML code—be careful! You may have to make changes by hand for complex or unusual books.
Once you’re done, commit:
git add -A git commit -m "Add ToC"
Complete the colophon
se create-draftput a skeleton
colophon.xhtmlfile in the
./src/epub/text/folder. Now that we have the cover image and artist, we can fill out the various fields there. Make sure to credit the original transcribers of the text (generally we assume them to be whoever’s name is on the file we download from Gutenberg) and to include a link back to the Gutenberg text we used, along with a link to any scans we used (from archive.org or hathitrust.org, for example).
You can also include your own name as the producer of this Standard Ebooks edition. Besides that, the colophon is standardized; don’t get too creative with it.
The release and updated dates should be the same for the first release, and they should match the dates in
content.opf. For now, leave them unchanged, as
git add -A git commit -m "Complete the colophon"
Complete the imprint
There’s also a skeleton
imprint.xhtmlfile in the
./src/epub/text/folder. All you’ll have to change here is the links to the transcription and page scans you used.
Clean and lint before building
Before you build the final ebook for you to proofread, it’s a good idea to check the ebook for some common problems you might run in to during production.
se cleanone more time to both clean up the source files, and to alert you if there are XHTML parsing errors. Even though we ran
se cleanbefore, it’s likely that in the course of production the ebook got in to less-than-perfect markup formatting. Remember you can run
se cleanas many times as you want—it should always produce the same output.
se clean .
se lint. If your ebook has any problems, you’ll see some output listing them. If everything’s OK, then
se lintwill complete silently.
se lint .
Build and proofread, proofread, proofread!
At this point we’re just about ready to build our proofreading draft!
se builddoes this for us. We’ll run it with the
--checkflag to make sure the epub we produced is valid, and with the
--koboflag to build a file for Kindles and Kobos too. If you won’t be using a Kindle or Kobo, you can omit those flags.
se build --output-dir=$HOME/dist/ --kindle --kobo --check .
If there are no errors, we’ll see five files in the brand-new
~/dist/folder in our home directory:
the-strange-case-of-dr-jekyll-and-mr-hyde.epub3is a pure epub3 file—basically just a zipped up version of our source. Unfortunately most ebook readers don’t fully support all of epub3’s capabilities yet, so we’re more interested in…
the-strange-case-of-dr-jekyll-and-mr-hyde.epub, the epub2 version of our ebook. If you don’t have a Kindle, this is the file you’ll be using to proofread.
the-strange-case-of-dr-jekyll-and-mr-hyde.kepub.epubis the Kobo version of our ebook. You can copy this to a Kobo using a USB cable.
the-strange-case-of-dr-jekyll-and-mr-hyde.azw3is the Kindle version of our ebook. You can copy this to a Kindle using a USB cable.
thumbnail_xxxx_EBOK_portrait.jpgis a thumbnail file you can copy to your Kindle to have the cover art appear in your reader. A bug in Amazon’s software prevents the Kindle from reading cover imags in side-loaded files; contact Amazon to complain.
This is the step where you read the ebook and make adjustments to the text so that it conforms to our typography manual.
All Standard Ebooks productions must be proofread at this stage to confirm that there are no typos, formatting errors, or typography errors. It’s extremely common for transcriptions sourced from Gutenberg to have various typos and formatting errors (like missing italics), and it’s also not uncommon for one of Standard Ebook’s tools to make the wrong guess about things like a closing quotation mark somewhere. As you proofread, it’s extremely handy to have a print copy of the book with you. For famous books that might just be a trip to your local library. For rarer books, or for those without a library nearby, there are several sites that provide free digital scans of public domain writing:
The HathiTrust Digital Library is a comprehensive collection of Google’s book scanning project. They have a vast catalog and a feature-rich search and reading interface.
The Internet Archive is another collection of scans of public domain books.
If you end up using scans from one of these sources, you must mention it in the ebook’s colophon and as a
If you’re using a transcription from Project Gutenberg as the base for this ebook, you may wish to report typos you’ve found to them, so that they can correct their copy. Instructions for how to do so are here.
Now that we’ve proofread the work and corrected any errors we’ve found, we’re ready to release the finished ebook!
It’s a good idea to run
se cleanone more time before releasing. Make sure to review the changes with
git difftoolbefore accepting them—
se typogrifyis usually right, but not always!
If you’re submitting your ebook to Standard Ebooks for review:
se prepare-releaseon an ebook you’re submitting for review!
Contact the mailing list with a link to your GitHub repository to let them know you’re finished. A reviewer will review your production and work with you to fix any issues. They’ll then release the ebook for you.
If you’re producing this ebook for yourself, not for release at Standard Ebooks:
Complete the initial publication by adding a release date, modification date, and final word count to
se prepare-releasedoes all of that for us.
se prepare-release .
With that done, we commit again using a commit message of “Initial publication” to signify that we’re all done with production, and now expect only proofreading corrections to be committed. (This may not actually be the case in reality, but it’s still a nice milestone to have.)
git add -A git commit -m "Initial publication"
Finally, build everything again.
se build --output-dir=$HOME/dist/ --kindle --kobo --check .
If the build completed successfully, congratulations! You’ve just finished producing a Standard Ebook!