standardebooks/web
1
0
Fork 0
mirror of https://github.com/standardebooks/web.git synced 2025-07-05 14:20:29 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

Release SEMOS 1.0.0

Browse source
This commit is contained in:
Alex Cabal 2020-03-29 11:51:11 -05:00
parent 6783e0e1a9
commit fe2d83461f
37 changed files with 758 additions and 7111 deletions
Download patch file Download diff file Expand all files Collapse all files

3
config/apache/standardebooks.org.conf
View file

@ -165,6 +165,9 @@ Define domain standardebooks.org
# Favicon rewrites
RewriteRule ^/(apple-touch|android-chrome|favicon|mstile|safari-pinned|browserconfig|manifest)([^/]+)$ /images/favicons/$1$2 [L]
# Redirect latest version of the manual
RewriteRule ^/manual/latest(.*) /manual/index.php?url=$1 [L]
# List of specific URL rewrites
RewriteRule ^/ebooks/aristotle/the-nicomachean-ethics(.+)$ /ebooks/aristotle/nicomachean-ethics$1 [R=301,L]
RewriteRule ^/ebooks/sir-arthur-conan-doyle(.+)$ /ebooks/arthur-conan-doyle$1 [R=301,L]

3
config/apache/standardebooks.test.conf
View file

@ -164,6 +164,9 @@ Define domain standardebooks.test
# Favicon rewrites
RewriteRule ^/(apple-touch|android-chrome|favicon|mstile|safari-pinned|browserconfig|manifest)([^/]+)$ /images/favicons/$1$2 [L]
# Redirect latest version of the manual
RewriteRule ^/manual/latest(.*) /manual/index.php?url=$1 [L]
# List of specific URL rewrites
RewriteRule ^/ebooks/aristotle/the-nicomachean-ethics(.+)$ /ebooks/aristotle/nicomachean-ethics$1 [R=301,L]
RewriteRule ^/ebooks/sir-arthur-conan-doyle(.+)$ /ebooks/arthur-conan-doyle$1 [R=301,L]

9
templates/Header.php
View file

@ -16,10 +16,6 @@ if(!isset($manual)){
$manual = false;
}
if(!isset($js)){
$js = false;
}
?><!doctype html>
<html lang="en-US">
<head>
@ -40,11 +36,6 @@ if(!isset($js)){
<link rel="alternate" type="application/rss+xml" title="Standard Ebooks - New Releases" href="https://standardebooks.org/rss/new-releases">
<link color="#394451" href="/safari-pinned-tab.svg" rel="mask-icon">
<meta content="#394451" name="theme-color">
<? if($js){ ?>
<link href="/js/highlight.js/styles/paraiso-dark.css" rel="stylesheet">
<script src="/js/highlight.js/highlight.pack.js"></script>
<script src="/js/core.js"></script>
<? } ?>
<meta content="<?= Formatter::ToPlainText($title) ?>" property="og:title">
<meta content="<?= $ogType ?? 'website' ?>" property="og:type">
<meta content="<?= SITE_URL . str_replace(SITE_URL, '', ($_SERVER['ORIG_PATH_INFO'] ?? $_SERVER['SCRIPT_URI'] ?? '')) ?>" property="og:url">

2
www/contribute/a-basic-standard-ebooks-source-folder.php
View file

@ -1,6 +1,6 @@
<?
require_once('Core.php');
?><?= Template::Header(['title' => 'A Basic Standard Ebooks Source Folder', 'highlight' => 'contribute', 'description' => 'All Standard Ebooks source folders have the same basic structure, described here.']) ?>
?><?= Template::Header(['title' => 'A Basic Standard Ebooks Source Folder', 'manual' => true, 'highlight' => 'contribute', 'description' => 'All Standard Ebooks source folders have the same basic structure, described here.']) ?>
<main>
<article id="a-basic-standard-ebooks-source-folder">
<h1>A Basic Standard Ebooks Source Folder</h1>

569
www/contribute/art.php
View file

@ -1,569 +0,0 @@
<?
require_once('Core.php');
?><?= Template::Header(['title' => 'Art Manual', 'js' => true, 'highlight' => 'contribute', 'description' => 'The Standard Ebooks Art Manual, containing details on cover and titlepage images, cover art requirements, and public domain research requirements and tips.']) ?>
<main>
<article>
<h1>Art Manual</h1>
<aside class="alert">
<p>Standard Ebooks is a brand-new project&mdash;this manual is a pre-alpha, and much of it is incomplete. If you have a question, need clarification, or run in to an issue not yet covered here, please <a href="https://groups.google.com/forum/#!forum/standardebooks">contact us</a> so we can update this manual.</p>
</aside>
<section id="general-notes">
<h2>General notes</h2>
<ul>
<li>
<p>When you create a new Standard Ebooks draft using <code class="program">se create-draft</code>, you’ll already have templates for the cover and titlepage images present in <code class="path">DRAFT-ROOT/images/</code>. The text in the <abbr class="initialism">SVG</abbr> files is represented as text, not paths, so you can edit them using a text editor and not an <abbr class="initialism">SVG</abbr> editor. Then, <code class="program">se build-images</code> converts these text-based source images into path-based compiled images, for distribution in the final epub file. We do this so to avoid having to distribute the font files along with the epub.</p>
</li>
<li>
<p>To develop cover and titlepage images, you must have the free <a href="https://github.com/theleagueof/league-spartan">League Spartan</a> and <a href="https://github.com/theleagueof/sorts-mill-goudy">Sorts Mill Goudy</a> fonts installed on your system.</p>
</li>
</ul>
</section>
<section id="list-of-files">
<h2>Complete list of files</h2>
<p>A complete set of image source files consists of:</p>
<ul>
<li>
<p><code class="path">DRAFT-ROOT/images/cover.source.jpg</code>: The full source image used for the cover art, in as high a resolution as possible. Can be of any image format, but typically we end up with <abbr class="initialism">JPG</abbr>s.</p>
</li>
<li>
<p><code class="path">DRAFT-ROOT/images/cover.jpg</code>: A cropped part of the source image that will serve as the actual image file we use in the cover. Must be exactly 1400w × 2100h.</p>
</li>
<li>
<p><code class="path">DRAFT-ROOT/images/cover.svg</code>: The <abbr class="initialism">SVG</abbr> source file for the cover, with any text represented as actual, editable text. Must be exactly 1400w × 2100h pixels. Since the final cover image <abbr class="initialism">SVG</abbr> has the text converted to paths, we keep this file around to make it easier to make changes to the cover in the future.</p>
</li>
<li>
<p><code class="path">DRAFT-ROOT/src/epub/images/cover.svg</code>: The final <abbr class="initialism">SVG</abbr> cover image. This image should be exactly like <code class="path">DRAFT-ROOT/images/cover.svg</code>, but with the text converted to paths.</p>
<p>This image is generated by <code class="path">se build-images</code>.</p>
</li>
<li>
<p><code class="path">DRAFT-ROOT/images/titlepage.svg</code>: The <abbr class="initialism">SVG</abbr> source file for the titlepage, with any text represented as actual, editable text. Must be exactly 1400 pixels wide, but the height must exactly match the text height plus some padding (described below).</p>
</li>
<li>
<p><code class="path">DRAFT-ROOT/src/epub/images/titlepage.svg</code>: The final <abbr class="initialism">SVG</abbr> titlepage image, with text converted to paths just like the cover page.</p>
<p>This image is generated by <code class="path">se build-images</code>.</p>
</li>
</ul>
</section>
<section id="cover-image">
<h2>The cover image</h2>
<aside class="alert">
<p>The SE Editor-in-Chief must review and approve of the cover art you select before you can commit it to your repository.</p>
<p><strong>Do not commit cover art without contacting the mailing list first!</strong></p>
</aside>
<p>There are three cover image templates available to you based on how long the ebook’s title is. <code class="path">create-draft</code> tries to guess which one to use, but it may not be correct. If your novel title is too long to fit in the template <code class="path">create-draft</code> picked for you, you can try a different cover image template. They’re located in the <a href="https://github.com/standardebooks/tools">Standard Ebooks toolset</a> <code class="path">TOOLSET-ROOT/se/data/templates/</code> folder.</p>
<p>To edit <code class="path">DRAFT-ROOT/images/cover.svg</code>, simply open it with your favorite text editor. Replace “NOVEL” with your novel’s title and “AUTHOR” with the author.</p>
<p>Only use a text editor to edit <code class="path">cover.svg</code>, not an SVG editing program like Inkscape. <abbr class="initialism">SVG</abbr> editors like Inkscape often reformat <abbr class="initialism">SVG</abbr>s and insert all sorts of useless metadata.</p>
<p>You must have the free <a href="https://github.com/theleagueof/league-spartan">League Spartan</a> font installed on your system for the cover to render and build correctly.</p>
<h3>Cover image SVG rules</h3>
<ul>
<li>
<p>Both the title and author are in League Spartan font with 5px letter spacing in ALL CAPS.</p>
</li>
<li>
<p>The left and right sides of the black title box must have at least 40px padding. More padding is preferrable over cramming the title in.</p>
</li>
<li>
<p>For the title lines:</p>
<ul>
<li>
<p>One-line titles: the line is 80px tall. <a href="/ebooks/niccolo-machiavelli/the-prince/w-k-marriott">Example.</a></p>
</li>
<li>
<p>Two-line titles: each line is 80px tall, and the second title line is 20px below the first line. <a href="/ebooks/fyodor-dostoevsky/crime-and-punishment/constance-garnett">Example.</a></p>
</li>
<li>
<p>Two-line, very long titles: each line is 60px tall, and the second line is 20px below the first line. <a href="/ebooks/selma-lagerlof/the-wonderful-adventures-of-nils/velma-swanston-howard">Example.</a></p>
</li>
<li>
<p>Two-line, extremely long titles: each line is 50px tall, and the second line is 20px below the first line. <a href="/ebooks/rudolph-erich-raspe/the-surprising-adventures-of-baron-munchausen">Example.</a></p>
</li>
</ul>
</li>
<li>
<p>For the author lines:</p>
<ul>
<li>
<p>The first author line begins 60px below the last title line.</p>
</li>
<li>
<p>One-line authors: the line is 40px tall.</p>
</li>
<li>
<p>Two-line authors: each line is 40px tall, and the second author line is 20px below the first line.</p>
</li>
</ul>
</li>
<li>
<p>Once the author and title lines are the correct distance from each other, the group of both should be horizontally centered in the black title box.</p>
</li>
<li>
<p><code class="path">cover.svg</code> uses <code class="path">cover.jpg</code> as the canvas background.</p>
</li>
<li>
<p><code class="path">cover.jpg</code> is exactly 1400w × 2100h pixels, and should be compressed to be no larger than one megabyte. This might not always be possible while maintining an acceptable level of image quality, but keeping the file size of <code class="path">cover.jpg</code> as small as possible is desirable.</p>
</li>
<li>
<p>Because <code class="path">cover.jpg</code> is a large image, you should source it from a high-quality scan. This might not always be possible, so it’s allowed to upscale the source image a small amount. But, for example, don’t use a 300w × 500h image as a source; that wouldn’t scale up well.</p>
</li>
</ul>
<h3>Cover image artwork rules</h3>
<p>Once you’ve set up <code class="path">cover.svg</code>, it’s time to find a suitable fine art painting to use for the cover image.</p>
<p>The paintings we use are all in the U.S. public domain (PD). Your task is to locate a painting suitable for the kind of book you’re producing, and then demonstrate that the painting is indeed in the U.S. public domain.</p>
<p>U.S. copyright law is complicated. Because of this, <strong>we <em>require</em> that you provide a link to a page scan of a 1924-or-older book that reproduces the painting you selected.</strong> <em>This is a hard requirement</em> to demonstrate that the painting you selected is in fact in the U.S. public domain. Just because a painting is very old, or Wikipedia says it’s PD, or it’s PD in a country besides the U.S., doesn’t necessarily mean it actually <em>is</em> PD in the U.S.</p>
<p>The painting you select must be a fine-art oil painting. We require this to maintain a consistency in the overall style of all of our covers.</p>
<h3>Tips for location 1924-or-older reproductions of cover art</h3>
<p>To actually demonstrate that a painting is PD, you must locate a reproduction of that painting in a 1924-or-older book.</p>
<p>This can be quite difficult. Many people find this to be the most time-consuming part of the ebook production process.</p>
<p>Because of the difficulty, finding suitable cover at is <em>all about compromise</em>. You’re unlikely to find the perfect cover image. You’ll find a lot of paintings that would be great matches, but that you can’t find reproductions of and thus we can’t use. So, be ready to compromise.</p>
<h4>General tips</h4>
<ul>
<li>
<p>Before you can go looking for a reproduction of a specific painting to prove its PD status, you have to find a suitable painting to begin with. <a href="https://www.wikiart.org/">Wikiart.org</a> is a great resource to search paintings by keyword. Museum online collections are another good place to look for inspiration. Once you find a potential candidate, then you can start researching its PD status.</p>
</li>
<li>
<p>When searching for cover art, remember that artist names and painting titles may be spelled in many different ways. Often a painting went by multiple titles, or if the title was not in English, by many different translations. Your best bet is to simply search for an artist’s last name, and not the painting title.</p>
</li>
<li>
<p>Once you locate a book with reproductions, open the book up in thumbnail view and quickly eyeball the pages to see if the artwork is reproduced there.</p>
</li>
<li>
<p>Note that if your IP address is not in the U.S., many book archives like Google Books and HathiTrust may disable book previews.</p>
</li>
<li>
<p>Many museum online catalogs have a “bibliography” or “references” section for each painting in their collection. This is usually a list of books in which the painting was either mentioned or reproduced. This is a good shortcut to finding the names of books in which a painting was reproduced, and if you’re lucky, a search for the book title in Google Books will turn up scans.</p>
</li>
<li>
<p>In <code class="path">cover.svg</code>, the black title and author box always goes in the lower half of the work. Thus, paintings in which some important detail would be obscured by the box cannot be used.</p>
</li>
</ul>
<h4>Gotchas</h4>
<ul>
<li>
<p>Sometimes the catalog record for a book has an incorrect publication year. Please verify the page scan of the copyright page to ensure the book is 1924 or older.</p>
</li>
<li>
<p>In older books it was common to have <em>etchings</em> of paintings. Etchings are not strict reproductions, and so we cannot count them when researching PD status.</p>
</li>
<li>
<p>Oftentimes painters would produce several different versions of the same artwork. You must carefully compare the reproduction in the page scan with the high-resolution artwork scan you found to ensure they are the same painting. Small details like the position of trees, clouds, reflections, or water are good ways to check if the painting is identical, or if you’re looking at a different version.</p>
</li>
</ul>
<h4>PD research step-by-step</h4>
<ol>
<li>
<p>Your first stop should be Google Books. Google Books allows you to filter results so that you only see 1924-or-older books. <a href="https://www.google.com/webhp?tbs=cdr:1,cd_min:,cd_max:1924&amp;tbm=bks">You can use this shortcut to search Google Books for 1924-or-older books.</a></p>
<p>Google Books is a convenient first stop because its thumbnail view is very fast, and it does a better job of highlighting search results than HathiTrust or Internet Archive.</p>
</li>
<li>
<p>If you can’t find anything on Google Books, next go to HathiTrust. HathiTrust’s thumbnail view is much slower, but it has a different catalog than Google Books does. <a href="https://babel.hathitrust.org/cgi/ls?a=srchls&amp;anyall1=all&amp;q1=&amp;field1=ocr&amp;op3=AND&amp;yop=before&amp;pdate_end=1924">You can use this shortcut to search HathiTrust for 1924-or-older books.</a></p>
</li>
<li>
<p>Lastly, try the Internet Archive. IA has a similar catalog as Google Books, but you may still find something there. <a href="https://archive.org/search.php?query=+date%3A%5B1850-01-01+TO+1924-12-31%5D&amp;sin=TXT&amp;sort=-date">You can use this shortcut to search the Internet Archive for 1924-or-older books.</a></p>
</li>
<li>
<p>Once you’ve found a reproduction of your artwork in a 1924-or-older book, you need to find a high-resolution color scan that we can use for the cover. Various museum sites can be good for this, along with <a href="https://commons.wikimedia.org">Wikimedia Commons</a>, <a href="https://www.google.com/culturalinstitute/project/art-project">Google Art Project</a>, and <a href="https://www.wikiart.org">Wikiart.org</a>.</p>
</li>
</ol>
<h4 id="pd-research-resources">PD research resources</h4>
<p>Evan Hall has begun compiling a spreadsheet of artwork for use in our ebooks. You can <a href="https://docs.google.com/spreadsheets/d/1BqmDx4EvkRxbJAijFBIZOkawyflGBMJzom-fVhLC5-0/edit#gid=557113123">view it here</a>.</p>
<p>You may find these resources helpful in your PD research:</p>
<ul>
<li>
<p><a href="https://books.google.com/books?id=Q3YoAAAAYAAJ">Art Studies for Schools: Or, Hints on the Use of Reproductions of High Art ...</a></p>
</li>
<li>
<p><a href="https://babel.hathitrust.org/cgi/pt?id=gri.ark:/13960/t7xm3q676;view=thumb;seq=13">Catalogue of the ... annual exhibition / The Pennsylvania ... 1912</a></p>
</li>
<li>
<p><a href="https://catalog.hathitrust.org/Record/009438195">Catalog Record: Art at the Royal Academy, London, 1897</a></p>
</li>
<li>
<p><a href="https://catalog.hathitrust.org/Record/100913061">Catalog Record: The work of John S. Sargent, R.A.</a></p>
</li>
<li>
<p><a href="https://catalog.hathitrust.org/Record/100344701">Catalog Record: Cubists and post-impressionism</a></p>
</li>
<li>
<p><a href="https://babel.hathitrust.org/cgi/pt?id=uc2.ark:/13960/t8cf9x30t;view=thumb;seq=229">The Luxembourg museum; its paintings. Three hundred and eighty-nine ...</a></p>
</li>
<li>
<p><a href="https://catalog.hathitrust.org/Record/009438136">Catalog Record: Illustrated catalogue : paintings in the...</a></p>
</li>
<li>
<p><a href="https://books.google.com/books?id=Qn1FAQAAMAAJ">A.L.A. Portrait Index: Index to Portraits Contained in Printed Books and ...</a></p>
</li>
<li>
<p><a href="https://babel.hathitrust.org/cgi/pt?id=njp.32101066379189;view=thumb;seq=5">The Nicolas Roerich exhibition, with introduction and catalogue ...</a></p>
</li>
<li>
<p><a href="https://books.google.com/books?id=NBgtAAAAYAAJ">Art of the British Empire Overseas - Charles Holme</a></p>
</li>
<li>
<p><a href="https://books.google.com/books?id=i6hEAQAAMAAJ">The International Studio</a></p>
</li>
<li>
<p><a href="https://catalog.hathitrust.org/Record/008018731">Catalog Record: Royal Academy pictures and sculpture</a></p>
</li>
<li>
<p><a href="https://catalog.hathitrust.org/Record/100237187">Catalog Record: Paris-Salon, 1883</a></p>
</li>
<li>
<p><a href="https://catalog.hathitrust.org/Record/000352339">Catalog Record: Farbige Tierbilder</a></p>
</li>
<li>
<p><a href="https://catalog.hathitrust.org/Record/000287970">Catalog Record: Catalogue of the Berlin Photographic Company...</a></p>
</li>
<li>
<p><a href="https://babel.hathitrust.org/cgi/pt?id=uc1.b3068561;view=thumb;seq=165">Katalog der Grossen Berliner Kunstausstellung, 1912.</a></p>
</li>
<li>
<p><a href="https://babel.hathitrust.org/cgi/pt?id=umn.31951p00149881h;view=thumb;seq=161">Grosse Berliner Kunst-Ausstellung, 1900 : Katalog.</a></p>
</li>
<li>
<p><a href="https://babel.hathitrust.org/cgi/pt?id=wu.89056204787;view=thumb;seq=161">Illustrirter Katalog / Grosse Berliner Kunst-Ausstellung. ... 1903.</a></p>
</li>
<li>
<p><a href="https://babel.hathitrust.org/cgi/pt?id=umn.31951000746060s;view=thumb;seq=1">La Ilustración ibérica. t.14 (1896).</a></p>
</li>
<li>
<p><a href="https://babel.hathitrust.org/cgi/pt?id=gri.ark:/13960/t08w61g82;view=thumb;seq=349">Entwickelungsgeschichte der modernen Kunst : ... 3.</a></p>
</li>
<li>
<p><a href="https://babel.hathitrust.org/cgi/pt?id=nnc1.ar62882988;view=thumb;seq=1">Illustrated catalogue of highly important old and modern paintings ...</a></p>
</li>
<li>
<p><a href="https://babel.hathitrust.org/cgi/pt?id=mdp.39015015820817;view=thumb;seq=541">Pittura, scultura futuriste (dinamismo plastico) Con 51 riproduzioni ...</a></p>
</li>
<li>
<p><a href="http://www.twainquotes.com/UniformEds/UniformEdsCh33.html">Harper and Brothers Pictorial Hardcover and Gift Editions</a></p>
</li>
<li>
<p><a href="http://brandywine.doetech.net/Detlobjps.cfm?ParentListID=126891&amp;ObjectID=1531590&amp;rec_num=175">Object Detail</a></p>
</li>
<li>
<p><a href="https://babel.hathitrust.org/cgi/pt?id=yale.39002088545273;view=thumb;seq=57">(this is a whole series) Royal Academy pictures and sculpture. 1900</a></p>
</li>
<li>
<p><a href="https://catalog.hathitrust.org/Record/011254573">Catalog Record: The art of the Hon. John Collier</a></p>
</li>
<li>
<p><a href="https://books.google.com/books?id=_0w4AAAAMAAJ">The Story of American Painting: The Evolution of Painting in America from ... - Charles Henry Caffin</a></p>
</li>
<li>
<p><a href="https://archive.org/details/diekunstmonatshe21mnuoft">Die Kunst : Monatsheft für freie und angewandte Kunst</a></p>
</li>
<li>
<p><a href="https://archive.org/stream/cubistesfuturist00coquuoft#page/267/mode/thumb">Cubistes, futuristes, passéistes; essai sur la ...</a></p>
</li>
<li>
<p><a href="https://archive.org/stream/einblickin00wald#page/23/mode/thumb">Einblick in Kunst: Expressionismus, Futurismus,...</a></p>
</li>
<li>
<p><a href="https://archive.org/stream/studiointernatio54lond#page/8/mode/thumb">Studio international</a></p>
</li>
<li>
<p><a href="https://books.google.com/books?id=q7GUsAXiiA4C">The Magazine of Art</a></p>
</li>
<li>
<p><a href="https://books.google.com/books?id=sdJAAAAAYAAJ">Cubists and Post-impressionism - Arthur Jerome Eddy</a></p>
</li>
<li>
<p><a href="https://catalog.hathitrust.org/Record/100344340">Catalog Record: L&#39;art flamand</a></p>
</li>
<li>
<p><a href="https://catalog.hathitrust.org/Record/100445834">Catalog Record: L&#39;école belge de peinture, 1830-1905</a></p>
</li>
<li>
<p><a href="https://catalog.hathitrust.org/Record/100578657">Catalog Record: Fernand Khnopff</a></p>
</li>
<li>
<p><a href="https://catalog.hathitrust.org/Record/000640739">Catalog Record: Gazette des beaux-arts (FULL SERIES)</a></p>
</li>
<li>
<p><a href="https://archive.org/stream/catalogueofficiel00expo#page/40/mode/thumb">Catalogue officiel illustré de l&#39;Exposition cen...</a></p>
</li>
<li>
<p><a href="https://babel.hathitrust.org/cgi/pt?id=njp.32101067654994;view=1up;seq=6">Offizieller Katalog der Internationalen Kunst-Ausstellung ... (1899).</a></p>
</li>
<li>
<p><a href="https://babel.hathitrust.org/cgi/pt?id=wu.89057259921;view=1up;seq=23">British painting, by Irene Maguinness.</a></p>
</li>
<li>
<p><a href="https://books.google.com/books?id=Jl9OAQAAMAAJ">Illustrated Catalogue: Paintings in the Metropolitan Museum of Art, New York - George Henry Story</a></p>
</li>
<li>
<p><a href="https://archive.org/stream/bub_gb_yxRaAAAAYAAJ#page/n54/mode/thumb">Impressionisten Guys, Manet, Van Gogh, Pissarro...</a></p>
</li>
<li>
<p><a href="https://catalog.hathitrust.org/Record/000636935">Catalog Record: The Royal Academy illustrated</a></p>
</li>
<li>
<p><a href="https://catalog.hathitrust.org/Record/000071454">Catalog Record: The Art journal</a></p>
</li>
<li>
<p><a href="https://catalog.hathitrust.org/Record/100585480">Catalog Record: Handbuch der Kunstgeschichte</a></p>
</li>
<li>
<p><a href="https://babel.hathitrust.org/cgi/pt?id=nyp.33433082172564;view=thumb;seq=9">Catalogue of the annual exhibition. v. 70-71 (1901-1902).</a></p>
</li>
<li>
<p><a href="https://catalog.hathitrust.org/Record/000521207">Catalog Record: Catalogue of the annual exhibition of...</a></p>
</li>
<li>
<p><a href="https://books.google.com/books?id=mEpGAQAAIAAJ">Meissonier, his life and his art - Jean Louis Ernest Meissonier, Octave Gréard</a></p>
</li>
<li>
<p><a href="https://babel.hathitrust.org/cgi/pt?id=gri.ark:/13960/t4fn6k42j;view=thumb;seq=41">Catalogue of the ... annual exhibition / The Pennsylvania ... 1905.</a></p>
</li>
<li>
<p><a href="https://books.google.com/books?id=xCtAAAAAYAAJ">Zur Geschichte der Düsseldorfer Kunst insbesondere im xix. Jahrhundert - Friedrich Schaarschmidt</a></p>
</li>
<li>
<p><a href="https://books.google.com/books?id=v7hHAQAAIAAJ">Bryan&#39;s dictionary of painters and engravers - Michael Bryan, George Charles Williamson</a></p>
</li>
<li>
<p><a href="https://archive.org/details/memorialexhibiti00eaki">Memorial exhibition of the works of the late Thomas Eakins, beginning December 23, 1917 and continuing through January 13, 1918 : Eakins, Thomas, 1844-1916</a></p>
</li>
<li>
<p><a href="https://books.google.com/books?id=CSFbAAAAYAAJ">Kunst und Künstler: Illustrierte Monatsschrift für bildende Kunst und ... - Karl Scheffler</a></p>
</li>
<li>
<p><a href="https://catalog.hathitrust.org/Record/000415396">Catalog Record: Gauguin et le groupe de Pont-Aven. Documents...</a></p>
</li>
<li>
<p><a href="https://catalog.hathitrust.org/Record/000062223">Catalog Record: Salon of the &amp;quot;Nationale</a></p>
</li>
<li>
<p><a href="https://books.google.com/books?id=JAcrAAAAYAAJ">Academy Notes</a></p>
</li>
<li>
<p><a href="https://books.google.com/books?id=etcwAQAAMAAJ">Great Painters of the XLX Century and Their Paintings - Léonce Bénédite</a></p>
</li>
<li>
<p><a href="https://catalog.hathitrust.org/Record/005722615">Catalog Record: Catalogue of paintings and drawings</a></p>
</li>
<li>
<p><a href="https://books.google.com/books?id=nH9HAQAAMAAJ">The International Studio</a></p>
</li>
<li>
<p><a href="https://books.google.com/books?id=B6saAAAAYAAJ&">Exhibition: Oil Paintings by Contemporary American Artists</a></p>
</li>
<li>
<p><a href="https://books.google.com/books?id=oYdLAQAAMAAJ">Catalogue of the ... Annual Exhibition of the Pennsylvania Academy of the ...</a></p>
</li>
<li>
<p><a href="https://catalog.hathitrust.org/Record/000523379">Catalog Record: Studio international</a></p>
</li>
<li>
<p><a href="https://books.google.com/books?id=xCtAAAAAYAAJ">Zur Geschichte der Düsseldorfer Kunst insbesondere im xix. Jahrhundert</a></p>
</li>
<li>
<p><a href="https://babel.hathitrust.org/cgi/pt?id=njp.32101079835656;view=thumb;seq=1">Catalogue of the paintings and sketches of the late Thomas Hill</a></p>
</li>
<li>
<p><a href="https://babel.hathitrust.org/cgi/pt?id=iau.31858028830473;view=thumb;seq=1">Picturesque California</a></p>
</li>
<li>
<p><a href="https://catalog.hathitrust.org/Record/000417706">Hubert Robert</a></p>
</li>
<li>
<p><a href="https://catalog.hathitrust.org/Record/100439727">The Copley prints; reproductions of notable paintings</a></p>
</li>
<li>
<p><a href="https://archive.org/details/cu31924014892024">Scottish painting past and present, 1620-1908</a></p>
</li>
<li>
<p><a href="https://archive.org/stream/cyclopediaofpain03chamuoft">Cyclopedia of Painters and Paintings</a></p>
</li>
<li>
<p><a href="https://catalog.hathitrust.org/Record/009437624">Art in Australia (series)</a></p>
</li>
<li>
<p><a href="https://archive.org/stream/julianashtonbook00asht#page/14/mode/thumb">The Julian Ashton Book</a></p>
</li>
<li>
<p><a href="https://catalog.hathitrust.org/Record/100951925">Das Museum (11 volume series, see Hathi catalog listing for other volumes</a></p>
</li>
<li>
<p><a href="https://babel.hathitrust.org/cgi/pt?id=umn.31951001591477w;view=thumb">Belgian Art in Exile</a></p>
</li>
<li>
<p><a href="https://archive.org/stream/expositiongn1907expo">Exposition Generale des Beaux-Arts Bruxelles 1907</a></p>
</li>
<li>
<p><a href="https://books.google.com/books?id=91FJAQAAMAAJ">Grützner</a></p>
</li>
<li>
<p><a href="https://catalog.hathitrust.org/Record/100598168">Ruska S kola mali r ska (Russian art)</a>
</p>
</li>
</ul>
<h4 id="faq">Cover art FAQs</h4>
<ul>
<li>
<p><b>I found a great painting, and Wikipedia says it’s public domain, but I can’t find a reproduction in a book. Can I use it?</b></p>
<p>No. You must find a reproduction of your selected painting in a book published in 1924 or earlier.</p>
</li>
<li>
<p><b>I found a great painting, and it’s really old, and the author died a long time ago, but I can’t find a reproduction in a book. Can I use it?</b></p>
<p>No. You must find a reproduction of your selected painting in a book published in 1924 or earlier.</p>
</li>
<li>
<p><b>I’ve found a reproduction in a book, but the book was published in 1924. Is that OK?</b></p>
<p>No. You must find a reproduction of your selected painting in a book published in 1924 or earlier.</p>
</li>
<li>
<p><b>I’ve found a scan on a museum site. Is that OK?</b></p>
<p>No. You must find a reproduction of your selected painting in a book published in 1924 or earlier.</p>
</li>
<li>
<p><b>But...</b></p>
<p>No. You must find a reproduction of your selected painting in a book published in 1924 or earlier.</p>
</li>
</ul>
<h4 id="museums">Museums with explicit CC0 collections</h4>
<p>Images that are explicitly marked as CC0 from these museums can be used without further research. Not all of their images are CC0, you must confirm the presence of a CC0 license on the specific image you want to use.</p>
<ul>
<li>
<p><a href="https://www.rijksmuseum.nl/en/search?q=&f=1&p=1&ps=12&type=painting&imgonly=True&st=Objects">Rijksmuseum</a> (Open the "Object Data" section and check they "Copyright" entry under the "Acquisition and right" section to confirm CC0)</p>
</li>
<li>
<p><a href="https://www.europeana.eu/portal/en/collections/art?f%5BDATA_PROVIDER%5D%5B%5D=Finnish+National+Gallery&f%5BREUSABILITY%5D%5B%5D=open&f%5BRIGHTS%5D%5B%5D=http%2A%3A%2F%2Fcreativecommons.org%2F%2Apublicdomain%2Fzero%2A&per_page=96&view=grid">Finnish National Gallery via Europeana</a> (Use the "View at" link under the "Find out more" header to confirm CC0 license at the museum's site)</p>
</li>
<li>
<p><a href="https://www.metmuseum.org/art/collection/search#!/search?material=Paintings&showOnly=withImage%7Copenaccess&sortBy=Relevance&sortOrder=asc&perPage=20&offset=0&pageSize=0">Met Museum</a> (CC0 items have the CC0 logo under the image)</p>
</li>
<li>
<p><a href="https://www.nationalmuseum.se/">National Museum Sweden</a> (CC-PD items have the CC-PD mark in the lower left of the item's detail view)</p>
</li>
<li>
<p><a href="https://art.thewalters.org/">The Walters Art Museum</a> (Public domain items are listed as "CC Creative Commons License" which links to a CC0 rights page)</p></li>
<li>
<p><a href="https://www.artic.edu/collection?q=test&is_public_domain=1">Art Institute of Chicago</a> (CC0 items say CC0 in the lower left of the painting in the art detail page)</p>
</li>
<li>
<p><a href="http://www.clevelandart.org/art/collection/search?only-open-access=1&filter-type=Painting">Cleveland Museum of Art</a> (CC0 items have the CC0 logo near the download button.)</p>
</li>
<li>
<p><a href="http://parismuseescollections.paris.fr/en/recherche/image-libre/true/avec-image/true/denominations/peinture-166168?mode=mosaique&solrsort=ds_created%20desc">Paris Musées</a> (CC0 items have the CC0 logo near the download button.)</p>
</li>
<li>
<p><a href="https://www.si.edu/search/collection-images?edan_q=&amp;edan_fq[0]=object_type%3A&quot;Paintings&quot;">The Smithsonian</a> (CC0 items say CC0 under the Usage header in the item details.)</p>
</li>
<li>
<p><a href="http://dams.birminghammuseums.org.uk/asset-bank/action/viewDefaultHome">Birmingham Museums</a> (CC0 items say CC0 in the Usage Rights section.)</p>
</li>
</ul>
<h2>Cover image step-by-step</h2>
<ol>
<li>
<p>Locate an appropriate high-resolution public domain work to use as the cover image background. Name this unchanged file <code class="path">DRAFT-ROOT/images/cover.source.jpg</code> (or .png, or .bmp, or whatever the original file format is).</p>
</li>
<li>
<p>Crop or scale the source image to create a 1400w × 2100h image that will be the actual cover background. Name this file <code class="path">DRAFT-ROOT/images/cover.jpg</code> and save it at 75% compression (if that looks good enough).</p>
</li>
<li>
<p>If you used <code class="progam">se create-draft</code> to initialize your repository, then <code class="path">DRAFT-ROOT/images/cover.svg</code> is initialized with the work title and author and what should be the correct font size. If not, copy the cover image template from <code class="path">TOOLSET-ROOT/se/data/templates/cover.svg</code> into the same directory as <code class="path">cover.jpg</code>. Open your working copy of <code class="path">DRAFT-ROOT/images/cover.svg</code> with a text editor and edit the work name and author, and remove any unused template CSS.</p>
</li>
<li>
<p>Finally, generate <code class="path">DRAFT-ROOT/src/epub/images/cover.svg</code> by running <code class="program">se build-images</code>. (This script also generates the titlepage images, if available.)</p>
</li>
</ol>
</section>
<section id="titlepage-image">
<h2>The titlepage image</h2>
<p><code class="path">create-draft</code> creates a titlepage image template for you that is correctly sized and arranged, and no more editing should be necessary. If you prefer to create one by hand, here are the various requirements for titlepage images.</p>
<p>To edit <code class="path">DRAFT-ROOT/images/titlepage.svg</code>, simply open it with your favorite text editor.</p>
<p>Only use a text editor to edit <code class="path">cover.svg</code>, not an SVG editing program like Inkscape. <abbr class="initialism">SVG</abbr> editors like Inkscape often reformat <abbr class="initialism">SVG</abbr>s and insert all sorts of useless metadata.</p>
<p>You must have the free <a href="https://github.com/theleagueof/league-spartan">League Spartan</a> and <a href="https://github.com/theleagueof/sorts-mill-goudy">Sorts Mill Goudy Italic</a> font installed on your system for the titlepage to render and build correctly.</p>
<h3>Titlepage image SVG rules</h3>
<ul>
<li>
<p>The title, author, and the names of other contributors are in League Spartan font with 5px letter spacing in ALL CAPS.</p>
</li>
<li>
<p>Do not include subtitles in the titlepage. For example, the titlepage would contain “THE MAN WHO WAS THURSDAY”, but not “THE MAN WHO WAS THURSDAY: A NIGHTMARE”.</p>
</li>
<li>
<p>If there are other contributors besides the author (for example a translator or illustrator), their names are preceded by “translated by” or “illustrated by”, set in lowercase Sorts Mill Goudy Italic font.</p>
</li>
<li>
<p>Only include the author, translator, and illustrator on the titlepage. Do not include other contributors like writers of introductions or annotators.</p>
</li>
<li>
<p>The titlepage canvas must have a padding of 50px vertically and 100px horizontally. Text must not enter the padding area.</p>
</li>
<li>
<p>The titlepage viewbox width must be exactly 1400px wide.</p>
</li>
<li>
<p>The titlepage viewbox height must <em>precisely fit the titlepage contents, plus 50px padding</em>. Don’t simply edit the template titlepage and leave the viewbox the same; you must customize the viewbox to fit. You can do this by either copying-and-pasting a viewbox from a completed Standard Ebooks ebook that has the same dimensions as yours, or by doing some simple math to calculate the correct height.</p>
</li>
<li>
<p>Title lines:</p>
<ul>
<li>
<p>Title lines are each 80px tall.</p>
</li>
<li>
<p>You may split the title into as many lines as necessary to fit.</p>
</li>
<li>
<p>Title lines are separated by a 20px margin between each line.</p>
</li>
</ul>
</li>
<li>
<p>Author lines:</p>
<ul>
<li>
<p>The first author line begins 100px below the last title line.</p>
</li>
<li>
<p>Each author line is 60px tall.</p>
</li>
<li>
<p>If an author line must be split, the next line begins 20px below the previous one.</p>
</li>
<li>
<p>For works with multiple authors, subsequent author lines begin 20px below the last author line.</p>
</li>
</ul>
</li>
<li>
<p>Contributor lines (like translator, illustrator):</p>
<ul>
<li>
<p>Contributors are both a “contributor descriptor”, like “translated by”, followed by the name on a new line.</p>
</li>
<li>
<p>The first contributor descriptor line begins 150px below the last author line.</p>
</li>
<li>
<p>Contributor descriptor lines are 40px tall, all lowercase, in the Sorts Mill Goudy Italic font.</p>
</li>
<li>
<p>The contributor name begins 20px below the contributor descriptor line.</p>
</li>
<li>
<p>The contributor name is 40px tall, ALL CAPS, in the League Spartan font.</p>
</li>
<li>
<p>If there is more than one contributor of the same type (like multiple translators), they are listed on one line. If there are two, separate them with AND. If there are more than two, separate them with commas, and AND after the final comma. <a href="/ebooks/hermann-hesse/siddhartha/gunther-olesch_anke-dreher_amy-coulter_stefan-langer_semyon-chaichenets">Example.</a></p>
<li>
<p>If there is more than one contributor type (like both a translator and an illustrator), the next contributor descriptor begins 80px after the last contributor name.</p>
</li>
</ul>
</li>
</ul>
<h3>Titlepage diagram</h3>
<figure>
<img alt="Spacing in a Standard Ebooks titlepage image" src="/images/titlepage-layout.png">
</figure>
<aside class="alert">
<p>Standard Ebooks is a brand-new project&mdash;this manual is a pre-alpha, and much of it is incomplete. If you have a question, need clarification, or run in to an issue not yet covered here, please <a href="https://groups.google.com/forum/#!forum/standardebooks">contact us</a> so we can update this manual.</p>
</aside>
</section>
</article>
</main>
<?= Template::Footer() ?>

20
www/contribute/index.php
View file

@ -26,7 +26,7 @@ require_once('Core.php');
</ul>
</section>
<section id="editors-and-readers">
<h2>Editors and readers of existing ebooks</h2>
<h2>Readers of existing ebooks</h2>
<ul>
<li>
<p><a href="/contribute/report-errors">Report a typo, formatting error, or typography error in any Standard Ebook.</a></p>
@ -35,7 +35,7 @@ require_once('Core.php');
<p><a href="/contribute/tips-for-editors-and-proofreaders">Tips for editors and proofreaders.</a></p>
</li>
<li>
<p><a href="/contribute/typography">The Standard Ebooks Typography Manual.</a></p>
<p><b><a href="/manual">The Standard Ebooks Manual of Style.</a></b></p>
</li>
</ul>
</section>
@ -55,29 +55,17 @@ require_once('Core.php');
<p><a href="/contribute/producing-an-ebook-step-by-step">A technical step-by-step guide to producing a new ebook, from start to finish.</a></p>
</li>
<li>
<p><a href="/contribute/typography">The Standard Ebooks Typography Manual.</a></p>
</li>
<li>
<p><a href="/contribute/semantics">The Standard Ebooks XHTML Structure and Semantics Manual.</a></p>
</li>
<li>
<p><a href="/contribute/metadata">The Standard Ebooks Metadata Manual.</a></p>
</li>
<li>
<p><a href="/contribute/art">The Standard Ebooks Art Manual for cover art and titlepages.</a></p>
<p><b><a href="/manual">The Standard Ebooks Manual of Style.</a></b></p>
</li>
<li>
<p><a href="/contribute/a-basic-standard-ebooks-source-folder">Descriptions of the files in a fresh Standard Ebooks source folder.</a></p>
</li>
<li>
<p><a href="/contribute/toolset">Guidelines for contributing to the Standard Ebooks toolset.</a></p>
<p><a href="https://github.com/standardebooks/tools">The Standard Ebooks toolset on GitHub.</a></p>
</li>
<li>
<p><a href="https://github.com/standardebooks">All Standard Ebooks ebook source files on GitHub.</a></p>
</li>
<li>
<p><a href="https://github.com/standardebooks/tools">The Standard Ebooks toolset on GitHub.</a></p>
</li>
</ul>
</section>
</article>

808
www/contribute/manual.php
View file

@ -1,808 +0,0 @@
<?
require_once('Core.php');
?><?= Template::Header(['title' => 'Style Manual', 'js' => true, 'highlight' => 'contribute', 'description' => 'The working draft of the new Standard Ebooks Style Manual.']) ?>
<main>
<article class="manual">
<h1>Style Manual</h1>
<aside class="alert">
<p>This manual is an incomplete draft. Do not use this for production work. Formatting is a work-in-progress.</p>
</aside>
<h2>Table of Contents</h2>
<p>Coming soon...</p>
<section>
<h2>XHTML and CSS code formatting style</h2>
<p>The <code class="path">clean</code> tool in the Standard Ebooks toolset formats XHTML code according to our style guidelines. The vast majority of the time its output is correct and no further modifications to code style are necessary.</p>
<section>
<h3>XHTML formatting</h3>
<ol>
<li>
<p>The first line of all XHTML files is:</p>
<figure>
<code class="html">&lt;?xml version="1.0" encoding="utf-8"?&gt;</code>
</figure>
</li>
<li>
<p>The second line of all XHTML files is (replace <code class="html">LANG</code> with the <a href="https://en.wikipedia.org/wiki/IETF_language_tag">appropriate language tag</a> for the file):</p>
<figure>
<code class="html">&lt;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: https://standardebooks.org/vocab/1.0" xml:lang="LANG"&gt;</code>
</figure>
</li>
<li>
<p>Tabs are used for indentation.</p>
</li>
<li>
<p>Tag names are lowercase.</p>
</li>
<li>
<p>Tags whose content is <a href="https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content">phrasing content</a> are on a single line, with no whitespace between the opening and closing tags and the content.</p>
<figure class="wrong">
<code class="html">&lt;p&gt;
It was a dark and stormy night...
&lt;/p&gt;</code>
</figure>
<figure class="corrected">
<code class="html">&lt;p&gt;It was a dark and stormy night...&lt;/p&gt;</code>
</figure>
</li>
</ol>
<section>
<h3>Attributes</h3>
<ol>
<li>
<p>Attributes are in alphabetical order.</p>
</li>
<li>
<p>Attributes, their namespaces, and their values are lowercase, except for values which are IETF language tags, where subtags are capitalized.</p>
<figure class="wrong">
<code class="html">&lt;section EPUB:TYPE="CHAPTER" XML:LANG="EN-US"&gt;...&lt;/section&gt;</code>
</figure>
<figure class="corrected">
<code class="html">&lt;section epub:type="chapter" xml:lang="en-US"&gt;...&lt;/section&gt;</code>
</figure>
</li>
<li>
<p>The string <code class="html">utf-8</code> is lowercase.</p>
</li>
</ol>
</section>
</section>
<section>
<h3>CSS formatting</h3>
<ol>
<li>
<p>The first two lines of all CSS files are:</p>
<figure>
<code class="css">@charset "utf-8";
@namespace epub "http://www.idpf.org/2007/ops";</code>
</figure>
</li>
<li>
<p>Tabs are used for indentation.</p>
</li>
<li>
<p>Selectors, properties, and values are lowercase.</p>
</li>
</ol>
<section>
<h3>Selectors</h3>
<ol>
<li>
<p>Selectors are each on their own line, directly followed by a comma or a brace with no whitespace inbetween.</p>
</li>
<li>
<p>Complete selectors are separated by exactly one blank line.</p>
<figure class="wrong">
<code class="css">abbr.name{
white-space: nowrap;
}
strong{
font-weight: normal;
font-variant: small-caps;
}</code>
</figure>
<figure class="corrected">
<code class="css">abbr.name{
white-space: nowrap;
}
strong{
font-weight: normal;
font-variant: small-caps;
}</code>
</figure>
</li>
<li>
<p>Closing braces are on their own line.</p>
</li>
</ol>
</section>
<section>
<h3>Properties</h3>
<ol>
<li>
<p>Properties are each on their own line (even if the selector only has one property) and indented with a single tab.</p>
<figure class="wrong">
<code class="css">abbr.name{ white-space; nowrap; }</code>
</figure>
<figure class="corrected">
<code class="css">abbr.name{
white-space: nowrap;
}</code>
</figure>
</li>
<li>
<p>Properties are in alphabetical order, <em>where possible</em>.</p>
<p>This isn’t always possible if you’re attempting to override a previous style in the same selector, and in some other cases.</p>
</li>
<li>
<p>Properties are directly followed by a colon, then a single space, then the property value.</p>
</li>
<li>
<p>Property values are directly followed by a semicolon, even if it's the last value in a selector.</p>
</li>
</ol>
</section>
</section>
</section>
<section>
<h2>Filesystem layout</h2>
<section>
<h3>How to name files</h3>
<ol>
<li>
<p>Works that are divided into larger parts (sometimes called "parts", "books", "volumes", "sections", etc.) have their part divisions contained in individual files named after the type of part, followed by a number starting at <code class="html">1</code>.</p>
<figure class="text">
<p class="corrected"><code class="path">book-1.xhtml</code></p>
<p class="corrected"><code class="path">book-2.xhtml</code></p>
<p class="corrected"><code class="path">part-1.xhtml</code></p>
<p class="corrected"><code class="path">part-2.xhtml</code></p>
</figure>
</li>
<li>
<p>Works that are composed of chapters, short stories, essays, or other short- to medium-length sections have each of those sections in an individual file.</p>
<ol>
<li>
<p>Chapters <em>not</em> contained in separate volumes are named <code class="path">chapter-N.xhtml</code>, where <code class="path">N</code> is the chapter number starting at <code class="html">1</code>.</p>
</li>
<li>
<p>Chapters contained in separate volumes, where the chapter number starts at 1 for each separate volume, are named <code class="path">chapter-X-N.xhtml</code>, where <code class="path">X</code> is the part number starting at <code class="html">1</code>, and <code class="path">N</code> is the chapter number <em>within the part</em>, starting at <code class="html">1</code>.</p>
<figure class="text">
<table>
<thead>
<tr>
<td><p>Example</p></td>
<td><p>Filename</p></td>
</tr>
</thead>
<tbody>
<tr>
<td>Part 1</td>
<td><code class="path">part-1.xhtml</code></td>
</tr>
<tr>
<td>Chapter 1</td>
<td><code class="path">chapter-1-1.xhtml</code></td>
</tr>
<tr>
<td>Chapter 2</td>
<td><code class="path">chapter-1-2.xhtml</code></td>
</tr>
<tr>
<td>Chapter 3</td>
<td><code class="path">chapter-1-3.xhtml</code></td>
</tr>
<tr>
<td>Part 2</td>
<td><code class="path">part-2.xhtml</code></td>
</tr>
<tr>
<td>Chapter 1</td>
<td><code class="path">chapter-2-1.xhtml</code></td>
</tr>
<tr>
<td>Chapter 2</td>
<td><code class="path">chapter-2-2.xhtml</code></td>
</tr>
<tr>
<td>Chapter 3</td>
<td><code class="path">chapter-2-3.xhtml</code></td>
</tr>
</tbody>
</table>
</figure>
</li>
<li>
<p>Chapters contained in separate volumes, where the chapter number does not re-start at 1 in each volume, are named <code class="path">chapter-N.xhtml</code>, where <code class="path">N</code> is the chapter number, starting at <code class="html">1</code>.</p>
<figure class="text">
<table>
<thead>
<tr>
<td><p>Example</p></td>
<td><p>Filename</p></td>
</tr>
</thead>
<tbody>
<tr>
<td>Part 1</td>
<td><code class="path">part-1.xhtml</code></td>
</tr>
<tr>
<td>Chapter 1</td>
<td><code class="path">chapter-1.xhtml</code></td>
</tr>
<tr>
<td>Chapter 2</td>
<td><code class="path">chapter-2.xhtml</code></td>
</tr>
<tr>
<td>Chapter 3</td>
<td><code class="path">chapter-3.xhtml</code></td>
</tr>
<tr>
<td>Part 2</td>
<td><code class="path">part-2.xhtml</code></td>
</tr>
<tr>
<td>Chapter 4</td>
<td><code class="path">chapter-4.xhtml</code></td>
</tr>
<tr>
<td>Chapter 5</td>
<td><code class="path">chapter-5.xhtml</code></td>
</tr>
<tr>
<td>Chapter 6</td>
<td><code class="path">chapter-6.xhtml</code></td>
</tr>
</tbody>
</table>
</figure>
</li>
</ol>
<li>
<p>Files containing a short story, essay, or other short work in a larger collection, are named with the URL-safe title of the work, excluding any subtitles.</p>
<figure class="text">
<table>
<thead>
<tr>
<td><p>Example</p></td>
<td><p>Filename</p></td>
</tr>
</thead>
<tbody>
<tr>
<td><p>A short story named "The Variable Man"</p></td>
<td><code class="path">the-variable-man.xhtml</code></td>
</tr>
<tr>
<td><p>A short story named "The Sayings of Limpang-Tung (The God of Mirth and of Melodious Minstrels)"</p></td>
<td><code class="path">the-sayings-of-limpang-tung.xhtml</code></td>
</tr>
</tbody>
</table>
</figure>
</li>
<li>
<p>Works that are composed of extremely short sections, like a volume of short poems, are in a single file containing all of those short sections. The filename is the URL-safe name of the work.</p>
<figure class="text">
<p class="corrected"><code class="path">north-of-boston.xhtml</code></p>
</figure>
</li>
<li>
<p>Frontmatter and backmatter sections have filenames that are named after the type of section, regardless of what the actual title of the section is.</p>
<figure class="text">
<table>
<thead>
<tr>
<td><p>Example</p></td>
<td><p>Filename</p></td>
</tr>
</thead>
<tbody>
<tr>
<td><p>A preface titled "Note from the author"</p></td>
<td><code class="path">preface.xhtml</code></td>
</tr>
</tbody>
</table>
</figure>
<ol>
<li>
<p>If an ebook contains more than one section of the same type (for example multiple prefaces), the filename is followed by <code class="html">-N</code>, where <code class="html">N</code> is a number representing the order of the section, starting at <code class="html">1</code>.</p>
<figure class="text">
<table>
<thead>
<tr>
<td><p>Example</p></td>
<td><p>Filename</p></td>
</tr>
</thead>
<tbody>
<tr>
<td><p>The first preface in an ebook, titled "Preface to the 1850 Edition"</p></td>
<td><code class="path">preface-1.xhtml</code></td>
</tr>
<tr>
<td><p>The second preface in an ebook, titled "Preface to the Charles Dickens Edition"</p></td>
<td><code class="path">preface-2.xhtml</code></td>
</tr>
</tbody>
</table>
</figure>
</li>
</ol>
</li>
</ol>
</section>
</section>
<section>
<h2>Semantic inflection</h2>
<p>The epub spec allows for <a href="http://www.idpf.org/accessibility/guidelines/content/semantics/epub-type.php">semantic inflection</a>, which is a way of adding pertinent semantic metadata to certain elements. For example, you may want to convey that the contents of a certain <code class="html">&lt;section&gt;</code> are actually a part of a chapter. You would do that by using the <code class="html">epub:type</code> attribute:</p>
<figure>
<code class="html">&lt;section epub:type="chapter"&gt;...&lt;/section&gt;</code>
</figure>
<ol>
<li>
<p>The epub spec includes a <a href="http://www.idpf.org/epub/vocab/structure/">list of supported keywords</a> that you can use in the <code class="html">epub:type</code> attribute. Use this vocabulary first, even if other vocabularies contain the same keyword.</p>
</li>
<li>
<p>If there's no appropriate keyword in the epub spec, next consult the <a href="http://www.daisy.org/z3998/2012/vocab/structure/">z3998 vocabulary</a>.</p>
<p>Keywords using this vocabulary are preceded by the <code class="html">z3998</code> namespace.</p>
<figure>
<code class="html">&lt;blockquote epub:type="z3998:letter"&gt;...&lt;/blockquote&gt;</code>
</figure>
</li>
<li>
<p>If the z3998 vocabulary doesn't have an appropriate keyword, next consult the <a href="/vocab/1.0">Standard Ebooks vocabulary</a>.</p>
<p>Keywords using this vocabulary are preceded by the <code class="html">se</code> namespace.</p>
<p>Unlike other vocabularies, the Standard Ebooks vocabulary is organized heirarchically. A complete vocabulary entry begins with the root vocabulary entry, with subsequent children separated by <code class="html">.</code>.</p>
<figure>
<code class="html">The &lt;i epub:type="se:name.vessel.ship"&gt;&lt;abbr class="initialism"&gt;HMS&lt;/abbr&gt; Bounty&lt;/i&gt;.</code>
</figure>
</li>
<li>
<p>The <code class="html">epub:type</code> attribute can have multiple keywords separated by spaces, even if the vocabularies are different.</p>
<figure>
<code class="html">&lt;section epub:type="chapter z3998:letter"&gt;...&lt;/section&gt;</code>
</figure>
</li>
</ol>
</section>
<section>
<h2>General XHTML patterns</h2>
<section>
<h3>The id attribute</h3>
<section>
<h4>ids of &lt;section&gt;s</h4>
<ol>
<li>
<p>Each <code class="html">&lt;section&gt;</code> has an <code class="html">id</code> attribute identical to the filename containing the <code class="html">&lt;section&gt;</code>, without the trailing extension.</p>
</li>
<li>
<p>In files containing multiple <code class="html">&lt;section&gt;</code>s, each <code class="html">&lt;section&gt;</code> has an <code class="html">id</code> attribute identical to what the filename <em>would</em> be if the section was in an individual file, without the trailing extension.</p>
</li>
</ol>
</section>
<section>
<h4>ids of other elements</h4>
<p>Generally, elements that are not <code class="html">&lt;section&gt;</code>s do not have an <code class="html">id</code> attribute. However an <code class="html">id</code> attribute might be necessary if a particular element is referenced in a link in a different location in the ebook; for example, if a certain paragraph is linked from an endnote.</p>
<ol>
<li>
<p>If an element requires an <code class="html">id</code> attribute, the attribute's value is the name of the tag followed by <code class="path">-N</code>, where <code class="path">N</code> is the sequence number of the tag start at <code class="html">1</code>.</p>
<figure class="corrected">
<code class="html">&lt;p&gt;See &lt;a href="#p-4"&gt;this paragraph&lt;/a&gt; for more details.&lt;/p&gt;
&lt;p&gt;...&lt;/p&gt;
&lt;p&gt;...&lt;/p&gt;
&lt;p id="p-4"&gt;...&lt;/p&gt;
&lt;p&gt;...&lt;/p&gt;</code>
</figure>
</li>
</ol>
</section>
</section>
<section>
<h3>&lt;title&gt; tags</h3>
<ol>
<li>
<p>The <code class="html">&lt;title&gt;</code> tag contains an appropriate description of the local file only. It does not contain the book title.</p>
</li>
</ol>
<section>
<h4>Titles of files that are an individual chapter or part division</h4>
<ol>
<li>
<p>Convert chapter or part numbers that are in Roman numerals to decimal numbers. Do not convert other Roman numerals that may be in the chapter title.</p>
<figure>
<code class="html">&lt;title&gt;Chapter 10&lt;/title&gt;</code>
</figure>
</li>
<li>
<p>If a chapter or part has no subtitle, the <code class="html">&lt;title&gt;</code> tag contains <code class="html">Chapter</code> followed by the chapter number.</p>
<figure>
<code class="html">&lt;title&gt;Chapter 4&lt;/title&gt;</code>
</figure>
</li>
<li>
<p>If a chapter or part has a subtitle, the <code class="html">&lt;title&gt;</code> tag contains <code class="html">Chapter</code>, followed by the chapter number, followed by a colon and a single space, followed by the subtitle.</p>
<figure>
<code class="html">&lt;title&gt;Chapter 4: The Reign of Louis XVI&lt;/title&gt;</code>
</figure>
</li>
</ol>
</section>
<section>
<h4>Titles of files that are not chapter or part divisions</h4>
<ol>
<li>
<p>Files that are not a chapter or a part division, like a preface, introduction, or epigraph, have a <code class="html">&lt;title&gt;</code> tag that contains the complete title of the section.</p>
<figure>
<code class="html">&lt;title&gt;Preface&lt;/title&gt;</code>
</figure>
</li>
<li>
<p>If a file contains a section with a subtitle, the <code class="html">&lt;title&gt;</code> tag contains the title, followed by a colon and a single space, followed by the subtitle.</p>
<figure>
<code class="html">&lt;title&gt;Quevedo and His Works: With an Essay on the Picaresque Novel&lt;/title&gt;</code>
</figure>
</li>
</ol>
</section>
</section>
<section>
<h3>Ordered/numbered and unordered lists</h3>
<p>All <code class="html">&lt;li&gt;</code> children of <code class="html">&lt;ol&gt;</code> and <code class="html">&lt;ul&gt;</code> tags have at least one direct child block-level tag. This is usually a <code class="html">&lt;p&gt;</code> tag. (But not necessarily; for example, a <code class="html">&lt;blockquote&gt;</code> tag might also be appropriate.)</p>
<figure class="wrong">
<code class="html">&lt;ul&gt;
&lt;li&gt;Don’t forget to feed the pigs.&lt;/li&gt;
&lt;/ul&gt;</code>
</figure>
<figure class="corrected">
<code class="html">&lt;ul&gt;
&lt;li&gt;
&lt;p&gt;Don’t forget to feed the pigs.&lt;/p&gt;
&lt;/li&gt;
&lt;/ul&gt;</code>
</figure>
</section>
</section>
<section>
<h2>Sectioning</h2>
<ol>
<li>
<p>Structural divisions in an ebook are each contained in their own <code class="html">&lt;section&gt;</code> tag.</p>
</li>
<li>
<p>In <code class="html">&lt;section&gt;</code>s that have titles, the first child element is an <code class="html">&lt;h#&gt;</code> or a <code class="html">&lt;header&gt;</code> element containing the section's title.</p>
</li>
<li>
<p>Typically an epub is divided into many different files. However, these files must be "recomposable" into a single HTML file by the <code class="path">recompose-epub</code> tool.</p>
<p>To achieve recomposability, individual files that contain subsections also contain all of the direct parent <code class="html">&lt;section&gt;</code> tags, with <code class="html">id</code> and <code class="html">epub:type</code> attributes identical to those parents.</p>
<p>For example, consider an ebook containing both a file named <code class="path">part-1.xhtml</code>, the first part, and a file named <code class="path">chapter-1-1.xhtml</code>, the first chapter of the first part. <code class="path">chapter-1-1.xhtml</code> contains a <code class="html">&lt;section&gt;</code> element for <em>both</em> the parent part, <em>and</em> the actual chapter:</p>
<figure class="corrected">
<code class="html">&lt;section id="part-1" epub:type="part"&gt;
&lt;section id="chapter-1-1" epub:type="chapter"&gt;
&lt;h3 epub:type="title z3998:roman">I&lt;/h3&gt;
...
&lt;/section&gt;
&lt;/section&gt;</code>
</figure>
</li>
</ol>
</section>
<section>
<h2>Parts of an ebook and their order</h2>
<section>
<h3>Frontmatter</h3>
<p>Frontmatter includes these parts of a book, in no particular order:</p>
<ul>
<li>
<p>Titlepage: An SE template containing an image with the title, author, and translator.</p>
</li>
<li>
<p>Imprint: An SE template containing information about Standard Ebooks and links to the source transcription and scans used to produce this ebook.</p>
</li>
<li>
<p>Dedication: A dedication from the author.</p>
</li>
<li>
<p>Epigraph: An opening poem or quotation.</p>
</li>
<li>
<p>Acknowledgements: A list of people that the author wishes to thank.</p>
</li>
<li>
<p>Foreword: An introduction to the text, written by someone besides the author.</p>
</li>
<li>
<p>Preface: An introduction to the text but standing outside of the text itself, written by the author. Often describes how a book came into being or to establish the author's credentials. "About the book as a book."</p>
</li>
<li>
<p>Introduction: An introduction to the text written, by the author. "About the content of the book."</p>
</li>
<li>
<p>Prologue: An opening to the text that establishes setting or mood, usually in the voice of the text.</p>
</li>
</ul>
<p>Note that in a Standard Ebooks ebook, the copyright page is part of the backmatter and not the frontmatter.</p>
</section>
<section>
<h3>Backmatter</h3>
<p>Backmatter includes these parts of a book, in no particular order:</p>
<ul>
<li>
<p>Epilogue: A conclusion to the text, usually in the voice of the text..</p>
</li>
<li>
<p>Afterword: A note from the author to conclude the text, outside of the text itself.</p>
</li>
<li>
<p>Endnotes: Any supplementary notes referenced in the text.</p>
</li>
<li>
<p>Colophon: A description of publishing details regarding the specific edition of the text, including credits or contributors.</p>
</li>
<li>
<p>Copyright page: Usually considered frontmatter in print texts, but considered backmatter in Standard Ebooks ebooks.</p>
</li>
</ul>
</section>
<section>
<h3>Ordering of sections</h3>
<ol>
<li>
<p>The first section of an ebook is <code class="path">titlepage.xhtml</code>. This file is auto-generated by <code class="path">create-draft</code>.</p>
</li>
<li>
<p>The second section of an ebook is <code class="path">imprint.xhtml</code>. The imprint contains links to the source transcription and scans used to produce the Standard Ebooks edition.</p>
</li>
<li>
<p>Any frontmatter relevant to the text follows.</p>
</li>
<li>
<p>If there is frontmatter, then a half title page follows.</p>
<section>
<h4>Half title page patterns</h4>
<p>The half title page contains the work title and subtitle.</p>
<ol>
<li>
<p>Half title pages without subtitles:</p>
<figure>
<code class="html full">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;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: https://standardebooks.org/vocab/1.0" xml:lang="en-GB"&gt;
&lt;head&gt;
&lt;title&gt;Half Title&lt;/title&gt;
&lt;link href="../css/core.css" rel="stylesheet" type="text/css"/&gt;
&lt;link href="../css/local.css" rel="stylesheet" type="text/css"/&gt;
&lt;/head&gt;
&lt;body epub:type="frontmatter"&gt;
&lt;section id="halftitlepage" epub:type="halftitlepage"&gt;
&lt;h1 epub:type="fulltitle"&gt;Don Quixote&lt;/h1&gt;
&lt;/section&gt;
&lt;/body&gt;
&lt;/html&gt;</code>
</figure>
</li>
<li>
<p>Half title pages with subtitles:</p>
<figure>
<code class="css full">section[epub|type~="halftitlepage"] span[epub|type~="subtitle"]{
display: block;
font-size: .75em;
font-weight: normal;
}</code>
<code class="html full">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;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: https://standardebooks.org/vocab/1.0" xml:lang="en-GB"&gt;
&lt;head&gt;
&lt;title&gt;Half Title&lt;/title&gt;
&lt;link href="../css/core.css" rel="stylesheet" type="text/css"/&gt;
&lt;link href="../css/local.css" rel="stylesheet" type="text/css"/&gt;
&lt;/head&gt;
&lt;body epub:type="frontmatter"&gt;
&lt;section id="halftitlepage" epub:type="halftitlepage"&gt;
&lt;h1 epub:type="fulltitle"&gt;
&lt;span epub:type="title"&gt;The Book of Wonder&lt;/span&gt;
&lt;span epub:type="subtitle"&gt;A Chronicle of Little Adventures at the Edge of the World&lt;/span&gt;
&lt;/h1&gt;
&lt;/section&gt;
&lt;/body&gt;
&lt;/html&gt;</code>
</figure>
</li>
</ol>
</section>
</li>
<li>
<p>Bodymatter (the main text) follows the frontmatter and half title page.</p>
</li>
<li>
<p>After the bodymatter, backmatter within the text follows, for example an afterword, epilogue, or conclusion.</p>
</li>
<li>
<p>Endnotes follow the text's backmatter. Endnotes files are named <code class="path">endnotes.xhtml</code>.</p>
</li>
<li>
<p>The colophon follows.</p>
</li>
<li>
<p>The uncopyright page follows the colophon.</p>
</li>
</ol>
</section>
</section>
<section>
<h2>Headers</h2>
<ol>
<li>
<p><code class="html">&lt;h#&gt;</code> tags (i.e., <code class="html">&lt;h1&gt;</code>–<code class="html">&lt;h6&gt;</code>) are used for headers of sections that are structural divisions of a document.</p>
<p><code class="html">&lt;h#&gt;</code> tags <em>are not</em> used for headers of components that are not in the table of contents. For example, they would not be used to mark up the title of a short poem in a chapter, where the poem itself is not a structural component of the larger ebook.</p>
</li>
<li>
<p>A section containing an <code class="html">&lt;h#&gt;</code> appears in the table of contents.</p>
</li>
<li>
<p>The book's title is implicitly at the <code class="html">&lt;h1&gt;</code> level, even if not present in the ebook. Because of the implicit <code class="html">&lt;h1&gt;</code>, all other sections begin at <code class="html">&lt;h2&gt;</code>.</p>
</li>
<li>
<p>Each <code class="html">&lt;h#&gt;</code> tag uses the correct number for the section's heading level in the overall book, <em>not</em> the section's heading level in the individual file.</p>
<p>For example, given an ebook with a file named <code class="path">part-2.xhtml</code> containing:</p>
<figure>
<code class="html">&lt;section id="part-2" epub:type="part"&gt;
&lt;h2 epub:type="title"&gt;Part &lt;span epub:type="z3998:roman"&gt;II&lt;/span&gt;&lt;/h2&gt;
&lt;/section&gt;</code>
</figure>
<p>Consider this example for the file <code class="path">chapter-2-3.xhtml</code>:</p>
<figure class="wrong">
<code class="html">&lt;section id="part-2" epub:type="part"&gt;
&lt;section id="chapter-2-3" epub:type="chapter"&gt;
&lt;h1 epub:type="title z3998:roman"&gt;III&lt;/h1&gt;
...
&lt;/section&gt;
&lt;/section&gt;</code>
</figure>
<figure class="corrected">
<code class="html">&lt;section id="part-2" epub:type="part"&gt;
&lt;section id="chapter-2-3" epub:type="chapter"&gt;
&lt;h3 epub:type="title z3998:roman"&gt;III&lt;/h3&gt;
...
&lt;/section&gt;
&lt;/section&gt;</code>
</figure>
</li>
<li>
<p>Each <code class="html">&lt;h#&gt;</code> tag has a direct parent <code class="html">&lt;section&gt;</code> tag.</p>
</li>
</ol>
<section>
<h3>Header HTML patterns</h3>
<ol>
<li>
<p>Sections without titles:</p>
<figure class="corrected">
<code class="html">&lt;h2 epub:type="title z3998:roman"&gt;XI&lt;/h2&gt;</code>
</figure>
</li>
<li>
<p>Sections with titles but no ordinal (i.e. chapter) numbers:</p>
<figure class="corrected">
<code class="html">&lt;h2 epub:type="title"&gt;A Daughter of Albion&lt;/h2&gt;</code>
</figure>
</li>
<li>
<p>Sections with titles and ordinal (i.e. chapter) numbers:</p>
<figure>
<code class="css full">span[epub|type~="subtitle"]{
display: block;
font-weight: normal;
}</code>
<code class="html full">&lt;h2 epub:type="title"&gt;
&lt;span epub:type="z3998:roman"&gt;XI&lt;/span&gt;
&lt;span epub:type="subtitle"&gt;Who Stole the Tarts?&lt;/span&gt;
&lt;/h2&gt;</code>
</figure>
</li>
<li>
<p>Sections titles and subtitles but no ordinal (i.e. chapter) numbers:</p>
<figure>
<code class="css full">span[epub|type~="subtitle"]{
display: block;
font-weight: normal;
}</code>
<code class="html full">&lt;h2 epub:type="title"&gt;
&lt;span&gt;An Adventure&lt;/span&gt;
&lt;span epub:type="subtitle"&gt;(A Driver’s Story)&lt;/span&gt;
&lt;/h2&gt;</code>
</figure>
</li>
<li>
<p>Sections that require titles, but that are not in the table of contents:</p>
<figure>
<code class="css full">header{
font-variant: small-caps;
margin: 1em;
text-align: center;
}</code>
<code class="html full">&lt;header&gt;
&lt;p&gt;The Title of a Short Poem&lt;/p&gt;
&lt;/header&gt;</code>
</figure>
</li>
</ol>
</section>
</section>
<section>
Play CSS:
[epub|type~="z3998:drama"]{
border-collapse: collapse;
}
[epub|type~="z3998:drama"] tr:first-child td{
padding-top: 0;
}
[epub|type~="z3998:drama"] tr:last-child td{
padding-bottom: 0;
}
[epub|type~="z3998:drama"] td{
vertical-align: top;
padding: .5em;
}
[epub|type~="z3998:drama"] td:last-child{
padding-right: 0;
}
[epub|type~="z3998:drama"] td:first-child{
padding-left: 0;
}
[epub|type~="z3998:drama"] td[epub|type~="z3998:persona"]{
hyphens: none;
text-align: right;
width: 20%;
}
[epub|type~="z3998:drama"] td p{
text-indent: 0;
}
table[epub|type~="z3998:drama"],
[epub|type~="z3998:drama"] table{
margin: 1em auto;
}
[epub|type~="z3998:stage-direction"]{
font-style: italic;
}
[epub|type~="z3998:stage-direction"]::before{
content: "(";
font-style: normal;
}
[epub|type~="z3998:stage-direction"]::after{
content: ")";
font-style: normal;
}
[epub|type~="z3998:persona"]{
font-variant: all-small-caps;
}
</section>
</article>
</main>
<?= Template::Footer() ?>

323
www/contribute/metadata.php
View file

@ -1,323 +0,0 @@
<?
require_once('Core.php');
?><?= Template::Header(['Metadata Manual' => 'title', 'js' => true, 'highlight' => 'contribute', 'description' => 'The Standard Ebooks Metadata Manual, containing requirements and directives for the epub metadata file.']) ?>
<main>
<article>
<h1>Metadata Manual</h1>
<aside class="alert">
<p>Standard Ebooks is a brand-new project&mdash;this manual is a pre-alpha, and much of it is incomplete. If you have a question, need clarification, or run in to an issue not yet covered here, please <a href="https://groups.google.com/forum/#!forum/standardebooks">contact us</a> so we can update this manual.</p>
</aside>
<h2>General principles</h2>
<p>Metadata in a Standard Ebooks epub is stored in the <code class="path">./src/epub/content.opf</code> file. The file contains some boilerplate that you won’t have to touch, and a lot of information that you <em>will</em> have to touch as you produce your ebook.</p>
<p>You should follow the general structure of the <code class="path">content.opf</code> file created by <code class="program">se create-draft</code>. Don't rearrange the order of anything in there and you should be fine.</p>
<h2>The <code class="html">&lt;dc:identifier&gt;</code> element</h2>
<p>The <code class="html">&lt;dc:identifier&gt;</code> element contains the unique identifier for this ebook. That identifier is always the Standard Ebooks URL for that ebook, prefaced by <code class="html">url:</code>.</p>
<figure>
<code class="html">&lt;dc:identifier id="uid"&gt;url:https://standardebooks.org/ebooks/anton-chekhov/short-fiction/constance-garnett&lt;/dc:identifier&gt;</code>
</figure>
<h3>Forming the SE identifier</h3>
<p>The SE identifier is formed by the following algorithm. A string can be made URL-safe using the <code class="program">make-url-safe</code> tool.</p>
<ol>
<li>
<p>Start with the URL-safe author of the work, as it appears on the titlepage. If there is more than one author, continue appending subsequent URL-safe authors, separated by an underscore. Do not alpha-sort the author name.</p>
</li>
<li>
<p>Append a forward slash, then the URL-safe title of the work. Again, do not alpha-sort the title.</p>
</li>
<li>
<p>If the work is translated, append a forward slash, then the URL-safe translator. If there is more than one translator, continue appending subsequent URL-safe translators, separated by an underscore. Do not alpha-sort translator names.</p>
</li>
<li>
<p>If the work is illustrated, append a forward slash, then the URL-safe illustrator. If there is more than one illustrator, continue appending subsequent URL-safe illustrators, separated by an underscore. Do not alpha-sort illustrator names.</p>
</li>
<li>
<p>Finally, <em>do not</em> append a trailing forward slash.</p>
</li>
</ol>
<h2>The <code class="html">&lt;dc:date&gt;</code>, <code class="html">&lt;meta property="dcterms:modified"&gt;</code>, and <code class="html">&lt;meta property="se:revision-number"&gt;</code> elements</h2>
<p>There are several elements in the metadata describing the publication date, updated date, and revision number of the ebook. Generally you don’t have to update these by hand; instead, use the <code class="program">prepare-release</code> tool to update them automatically both in <code class="path">content.opf</code> and in <code class="path">colophon.xhtml</code>.</p>
<ul>
<li>
<p><code class="html">&lt;dc:date&gt;</code> is a timestamp representing the first publication date of this ebook file. Once the ebook is released to the public, this value doesn’t change.</p>
</li>
<li>
<p><code class="html">&lt;meta property="dcterms:modified"&gt;</code> is a timestamp representing the last time this ebook file was modified. This changes often.</p>
</li>
<li>
<p><code class="html">&lt;meta property="se:revision-number"&gt;</code> is a special SE extension representing the revision number of this ebook file. During production, this number will be 0. When the ebook is first released to the public, the number will increment to 1. Each time <code class="html">&lt;meta property="dcterms:modified"&gt;</code> changes, the revision number must be incremented.</p>
</li>
</ul>
<h2>The ebook title</h2>
<p>Usually titles are fairly easy to represent with the <code class="html">&lt;dc:title&gt;</code> element.</p>
<h3>Books without subtitles</h3>
<ul>
<li>
<p>Add a <code class="html">&lt;dc:title&gt;</code> element to contain the title.</p>
</li>
<li>
<p>Add an accompanying <code class="html">file-as</code> element with the title alpha-sorted, even if the <code class="html">file-as</code> value is the same as the title.</p>
</li>
</ul>
<p>These examples shows how to mark up a simple title like <i><a href="/ebooks/abraham-merritt/the-moon-pool">The Moon Pool</a></i> or <i><a href="/ebooks/anton-chekhov/short-fiction/constance-garnett">Chekhov’s Short Fiction</a></i>.</p><code class="html full">&lt;dc:title id="title"&gt;The Moon Pool&lt;/dc:title&gt; &lt;meta property="file-as" refines="#title"&gt;Moon Pool, The&lt;/meta&gt;</code> <code class="html full">&lt;dc:title id="title"&gt;Short Fiction&lt;/dc:title&gt; &lt;meta property="file-as" refines="#title"&gt;Short Fiction&lt;/meta&gt;</code>
<h3>Books with subtitles</h3>
<ul>
<li>
<p>Add a <code class="html">&lt;meta property="title-type"&gt;</code> element with the value of <code class="html">main</code> to identify the main part of the title.</p>
</li>
<li>
<p>Add a second <code class="html">&lt;dc:title&gt;</code> element to contain the subtitle, and refine it with <code class="html">&lt;meta property="title-type"&gt;</code> set to <code class="html">subtitle</code>.</p>
</li>
<li>
<p>Add a third <code class="html">&lt;dc:title&gt;</code> element to contain the complete title on one line, with the main title and subtitle separated by a colon and space. Refine it with <code class="html">&lt;meta property="title-type"&gt;</code> set to <code class="html">extended</code>.</p>
</li>
<li>
<p>All three of these <code class="html">&lt;dc:title&gt;</code> elements must have an accompanying <code class="html">file-as</code> element, even if the <code class="html">file-as</code> value is the same as the title.</p>
</li>
</ul>
<p>This example shows how to mark up <i><a href="/ebooks/g-k-chesterton/the-man-who-was-thursday">The Man Who Was Thursday: A Nightmare</a></i>.</p><code class="html full">&lt;dc:title id="title"&gt;The Man Who Was Thursday&lt;/dc:title&gt; &lt;meta property="file-as" refines="#title"&gt;Man Who Was Thursday, The&lt;/meta&gt; &lt;meta property="title-type" refines="#title"&gt;main&lt;/meta&gt; &lt;dc:title id="subtitle"&gt;A Nightmare&lt;/dc:title&gt; &lt;meta property="file-as" refines="#subtitle"&gt;Nightmare, A&lt;/meta&gt; &lt;meta property="title-type" refines="#subtitle"&gt;subtitle&lt;/meta&gt; &lt;dc:title id="fulltitle"&gt;The Man Who Was Thursday: A Nightmare&lt;/dc:title&gt; &lt;meta property="file-as" refines="#fulltitle"&gt;Man Who Was Thursday, The&lt;/meta&gt; &lt;meta property="title-type" refines="#fulltitle"&gt;extended&lt;/meta&gt;</code>
<h3>Books with a more popularly-known alternative title</h3>
<p>Some books are commonly referred to by a shorter name than their actual title. For example, <i><a href="/ebooks/mark-twain/the-adventures-of-huckleberry-finn">The Adventures of Huckleberry Finn</a></i> is often simply known as <i>Huck Finn</i>.</p>
<ul>
<li>
<p>Add an additional <code class="html">&lt;dc:title&gt;</code> element to contain the common title, and refine it with <code class="html">&lt;meta property="title-type"&gt;</code> set to <code class="html">short</code>.</p>
</li>
<li>
<p>Do not include a <code class="html">file-as</code> element for the short title.</p>
</li>
</ul><code class="html full">&lt;dc:title id="title-short"&gt;Huck Finn&lt;/dc:title&gt; &lt;meta property="title-type" refines="#title-short"&gt;short&lt;/meta&gt;</code>
<h2>Ebook subjects</h2>
<p>The <code class="html">&lt;dc:subject&gt;</code> elements allow us to categorize the ebook. We use the Library of Congress categories assigned to the book for this purpose.</p>
<p>If you’re working on a book that has a Project Gutenberg transcription, you can almost always find these categorizations in the ebook’s “bibrec” tab, saving you effort.</p>
<p>If your ebook doesn’t have a Project Gutenberg page, then you can search the <a href="https://catalog.loc.gov">Library of Congress catalog</a> to find the categories for your ebook.</p>
<ul>
<li>
<p>Each <code class="html">&lt;dc:subject&gt;</code> has the <code class="html">id</code> attribute set to <code class="html">subject-#</code>, where # is a number starting at 1, without leading zeros, that increments with each subject.</p>
</li>
<li>
<p>Arrange the <code class="html">&lt;dc:subject&gt;</code> elements sequentially in a block.</p>
</li>
<li>
<p>After the block of <code class="html">&lt;dc:subject&gt;</code> elements, include a block of <code class="html">&lt;meta property="authority"&gt;</code> and <code class="html">&lt;meta property="term"&gt;</code> elements with values representing the source and particular ID of the subject. <code class="html">authority</code> is almost always <code class="html">LCSH</code> (Library of Congress Subject Heading).</p>
</li>
<li>
<p>The <code class="html">&lt;meta property="authority"&gt;</code> element must refine each individual <code class="html">&lt;dc:subject&gt;</code> element.</p>
</li>
</ul>
<p>This example shows how to mark up the subjects for <i><a href="/ebooks/david-lindsay/a-voyage-to-arcturus">A Voyage to Arcturus</a></i>:</p><code class="html full">&lt;dc:subject id="subject-1"&gt;Science fiction&lt;/dc:subject&gt; &lt;dc:subject id="subject-2"&gt;Psychological fiction&lt;/dc:subject&gt; &lt;dc:subject id="subject-3"&gt;Quests (Expeditions) -- Fiction&lt;/dc:subject&gt; &lt;dc:subject id="subject-4"&gt;Life on other planets -- Fiction&lt;/dc:subject&gt; &lt;meta property="meta-auth" refines="#subject-1"&gt;https://www.gutenberg.org/ebooks/1329&lt;/meta&gt; &lt;meta property="meta-auth" refines="#subject-2"&gt;https://www.gutenberg.org/ebooks/1329&lt;/meta&gt; &lt;meta property="meta-auth" refines="#subject-3"&gt;https://www.gutenberg.org/ebooks/1329&lt;/meta&gt; &lt;meta property="meta-auth" refines="#subject-4"&gt;https://www.gutenberg.org/ebooks/1329&lt;/meta&gt;</code>
<h2>SE subjects</h2>
<p>Along the Library of Congress categories, we include a custom list of SE subjects in the ebook metadata. Unlike Library of Congress categories, SE subjects are purposefully broad. They’re more like subject categories you’d find a medium-sized bookstore, as opposed to the precise, detailed, heirarchical Library of Congress categories.</p>
<p>It’s your task to select appropriate SE subjects for your ebook. Usually just one or two of these categories will suffice.</p>
<p>If you strongly feel like your book deserves a new category, please contact us to discuss it.</p>
<p>Below is a list of all of the recognized SE subjects:</p>
<ul>
<li>
<p><code class="tag">Adventure</code></p>
</li>
<li>
<p><code class="tag">Autobiography</code></p>
</li>
<li>
<p><code class="tag">Childrens</code></p>
</li>
<li>
<p><code class="tag">Comedy</code></p>
</li>
<li>
<p><code class="tag">Drama</code></p>
</li>
<li>
<p><code class="tag">Fantasy</code></p>
</li>
<li>
<p><code class="tag">Fiction</code></p>
</li>
<li>
<p><code class="tag">Horror</code></p>
</li>
<li>
<p><code class="tag">Memoir</code></p>
</li>
<li>
<p><code class="tag">Mystery</code></p>
</li>
<li>
<p><code class="tag">Nonfiction</code></p>
</li>
<li>
<p><code class="tag">Philosophy</code></p>
</li>
<li>
<p><code class="tag">Poetry</code></p>
</li>
<li>
<p><code class="tag">Satire</code></p>
</li>
<li>
<p><code class="tag">Science Fiction</code></p>
</li>
<li>
<p><code class="tag">Shorts</code></p>
</li>
<li>
<p><code class="tag">Spirituality</code></p>
</li>
<li>
<p><code class="tag">Travel</code></p>
</li>
</ul>
<h3>Required subjects for specific kinds of ebooks</h3>
<ul>
<li>
<p>Ebooks that are collections of short stories must have the SE subject <code class="tag">Shorts</code>.</p>
</li>
<li>
<p>Ebooks that are young adult or children’s books must have the SE subject <code class="tag">Childrens</code>.</p>
</li>
</ul>
<h2>Ebook descriptions</h2>
<p>An ebook has two kinds of descriptions: a short <code class="html">&lt;dc:description&gt;</code> element, and a much longer <code class="html">&lt;meta property="se:long-description"&gt;</code> element.</p>
<h3>The short description</h3>
<p>The <code class="html">&lt;dc:description&gt;</code> element contains a short, single-sentence summary of the ebook.</p>
<ul>
<li>
<p>The description must be a single complete sentence ending in a period, not a sentence fragment or restatment of the title. Do not use more than one sentence.</p>
</li>
<li>
<p>The description must be typogrified, i.e. it must contain Unicode curly quotes, em-dashes, and the like.</p>
</li>
</ul>
<h3>The long description</h3>
<p>The <code class="html">&lt;meta property="se:long-description"&gt;</code> element contains a much longer description of the ebook.</p>
<ul>
<li>
<p>The long description must be a non-biased, encyclopedia-like description of the ebook, including any relevant publication history, backstory, or historical notes. It must be as detailed as possible, without giving away plot spoilers. It must not impart the producer’s opinions of the book. Think along the lines of a Wikipedia-like summary of the book and its history, <em>but under no circumstances can you copy and paste from Wikipedia!</em></p>
</li>
<li>
<p>The long descriptions must be typogrified, i.e. it must contain Unicode curly quotes, em-dashes, and the like.</p>
</li>
<li>
<p>The long description must be in <em>escaped</em> HTML, with the HTML beginning on its own line after the <code class="html">&lt;meta property="se:long-description"&gt;</code> element.</p>
<p>An easy way to escape your HTML is to compose your long description in regular HTML, then insert it into the <code class="html">&lt;meta property="se:long-description"&gt;</code> element surrounded by a <code class="html">&lt;![CDATA[ ... ]]&gt;</code> element. Once you’re done, run the <code class="path">clean</code> tool, which will remove the <code class="html">&lt;![CDATA[ ... ]]&gt;</code> element and escape the contained HTML for you.</p>
</li>
</ul>
<h2>The <code class="html">&lt;dc:language&gt;</code> element</h2>
<p>The <code class="html">&lt;dc:language&gt;</code> element follows the long description block. It contains the IETF language tag for the language that the work is in. Usually this is either <code class="ietf">en-US</code> or <code class="ietf">en-GB</code>.</p>
<h2>The <code class="html">&lt;dc:source&gt;</code> elements</h2>
<p>The <code class="html">&lt;dc:source&gt;</code> elements represent URLs to sources for both the transcription we based this ebook off of, and page scans of the print sources used to correct or work on the transcriptions.</p>
<ul>
<li>
<p>Where possible, these URLs should use https.</p>
</li>
<li>
<p>A Standard Ebooks ebook typically contains more than one <code class="html">&lt;dc:source&gt;</code> element, and can contain more than one such element if multiple sources for page scans were used.</p>
</li>
</ul>
<h2>The <code class="html">&lt;meta property="se:production-notes"&gt;</code> elements</h2>
<p>This element can be used by the ebook producers to convey production notes relevant to the production process. For example, a producer might note that page scans were not available, so an editorial decision was made to add commas to sentences deemed to be transcription typos.</p>
<p>If there are no production notes, remove this element.</p>
<h2>The <code class="html">&lt;meta property="se:word-count"&gt;</code> and <code class="html">&lt;meta property="se:reading-ease.flesch"&gt;</code> elements</h2>
<p>These elements are automatically computed by the <code class="program">prepare-release</code> tool. Don’t compute them by hand.</p>
<h2>SE-specific metadata for the ebook</h2>
<p>Next, Standard Ebooks also includes two additional custom metadata items about the ebook:</p>
<ol>
<li>
<p><code class="html">&lt;meta property="se:url.encyclopedia.wikipedia"&gt;</code> contains the Wikipedia URL for this ebook. If there isn’t one, remove this element.</p>
</li>
<li>
<p><code class="html">&lt;meta property="se:url.vcs.github"&gt;</code> contains the GitHub URL for this ebook. This is calculated by taking the string “https://github.com/standardebooks/” and appending the ebook identifier (calculated above), without “https://standardebooks.org/ebooks/”, and with forward slashes replaced by underscores.</p>
</li>
</ol>
<h2>Author metadata</h2>
<p>Next, we include the author metadata block.</p>
<p>The author metadata block always has the ID of “author”. If there is more than one author, the first author is “author-1”, the second “author-2”, and so on. Each block of the following, in this order:</p>
<ol>
<li>
<p><code class="html">&lt;dc:creator id="author"&gt;</code>: the author’s name as it appears on the cover.</p>
</li>
<li>
<p><code class="html">&lt;meta property="file-as" refines="#author"&gt;</code>: the author’s name as filed alphabetically. Include this even if it’s identical to <code class="html">&lt;dc:creator&gt;</code>.</p>
</li>
<li>
<p><code class="html">&lt;meta property="se:name.person.full-name" refines="#author"&gt;</code>: the author’s full name, with any initials or middle names expanded. If this is identical to <code class="html">&lt;dc:creator&gt;</code>, remove this element.</p>
</li>
<li>
<p><code class="html">&lt;meta property="alternate-script" refines="#author"&gt;</code>: the author’s name as it appears on the cover, but transliterated into their native alphabet if applicable. For example, Anton Chekhov’s name would be contained here in the Cyrillic alphabet. Remove this element if not applicable.</p>
</li>
<li>
<p><code class="html">&lt;meta property="se:url.encyclopedia.wikipedia" refines="#author"&gt;</code>: the URL of the author’s Wikipedia page. Remove this element if not applicable.</p>
</li>
<li>
<p><code class="html">&lt;meta property="se:url.authority.nacoaf" refines="#author"&gt;</code>: the URL of the author’s Library of Congress Names Database page.</p>
<ul>
<li>
<p>This is easily found by visiting the person’s Wikipedia page and looking at the very bottom in the “Authority Control” section, under “LCCN”.</p>
</li>
<li>
<p>If you can’t find it in Wikipedia, you can find it directly by visiting <a href="http://id.loc.gov/authorities/names.html">http://id.loc.gov/authorities/names.html</a>.</p>
</li>
<li>
<p>Note that the canonical URLs <em>do not</em> include a trailing <code class="path">.html</code> (the LoC site performs a silent redirect when you load it to append <code class="path">.html</code> to the URL it considers canonical). Remove this element if not applicable.</p>
</li>
</ul>
</li>
<li>
<p><code class="html">&lt;meta property="role" refines="#author" scheme="marc:relators"&gt;</code>: the <a href="http://www.loc.gov/marc/relators/relacode.html">MARC relator tag</a> for the roles the author played in creating this book. You will always have one element with the value of <code class="marc">aut</code>. You can have additional elements for additional values, if applicable. For example, if the author also illustrated the book, you would include an additional element with the value of <code class="marc">ill</code>.</p>
</li>
</ol>
<h3>An example of a complete author metadata block</h3><code class="html full">&lt;dc:creator id="author"&gt;Anton Chekhov&lt;/dc:creator&gt; &lt;meta property="file-as" refines="#author"&gt;Chekhov, Anton&lt;/meta&gt; &lt;meta property="se:name.person.full-name" refines="#author"&gt;Anton Pavlovich Chekhov&lt;/meta&gt; &lt;meta property="alternate-script" refines="#author"&gt;Анто́н Па́влович Че́хов&lt;/meta&gt; &lt;meta property="se:url.encyclopedia.wikipedia" refines="#author"&gt;https://en.wikipedia.org/wiki/Anton_Chekhov&lt;/meta&gt; &lt;meta property="se:url.authority.nacoaf" refines="#author"&gt;http://id.loc.gov/authorities/names/n79130807&lt;/meta&gt; &lt;meta property="role" refines="#author" scheme="marc:relators"&gt;aut&lt;/meta&gt;</code>
<h2>Translator metadata</h2>
<p>If the work is translated, the translator metadata block follows.</p>
<p>The translator metadata block always has the ID of “translator”. If there is more than one translator, the first translator is “translator-1”, the second “translator-2”, and so on. Each block is identical to the author metadata block, but using <code class="html">&lt;dc:contributor id="translator"&gt;</code> instead of <code class="html">&lt;dc:creator&gt;</code>. The <a href="http://www.loc.gov/marc/relators/relacode.html">MARC relator tag</a> will be <code class="marc">trl</code>. Translators often annotate the work; if this is the case, also include the <a href="http://www.loc.gov/marc/relators/relacode.html">MARC relator tag</a> <code class="marc">ann</code>.</p>
<h2>Illustrator metadata</h2>
<p>If the work is illustrated by a person who is not the author, the illustrator metadata block follows.</p>
<p>The illustrator metadata block always has the ID of “illustrator”. If there is more than one author, the first illustrator is “illustrator-1”, the second “illustrator-2”, and so on. Each block is identical to the author metadata block, but using <code class="html">&lt;dc:contributor id="illustrator"&gt;</code> instead of <code class="html">&lt;dc:creator&gt;</code>. The <a href="http://www.loc.gov/marc/relators/relacode.html">MARC relator tag</a> will be <code class="marc">ill</code>.</p>
<h2>Cover artist metadata</h2>
<p>The cover artist metadata block follows.</p>
<p>The cover artist metadata block always has the ID of “artist”. Each block is identical to the author metadata block, but using <code class="html">&lt;dc:contributor id="artist"&gt;</code> instead of <code class="html">&lt;dc:creator&gt;</code>. The <a href="http://www.loc.gov/marc/relators/relacode.html">MARC relator tag</a> will be <code class="marc">art</code>.</p>
<h2>Transcriber metadata</h2>
<p>If you based this ebook on a transcription by someone else, like Project Gutenberg, then transcriber blocks follow. The first transcriber is “transcriber-1”, the second “transcriber-2”, and so on. Usually, trancribers only have the following two elements:</p>
<ol>
<li>
<p><code class="html">&lt;meta property="file-as" refines="#transcriber-1"&gt;</code></p>
</li>
<li>
<p><code class="html">&lt;meta property="role" refines="#transcriber-1" scheme="marc:relators"&gt;</code> with the value of <code class="marc">trc</code>.</p>
</li>
</ol>
<h2>Producer metadata</h2>
<p>This block is for information about you, the producer of this Standard Ebook. It contains the same type of elements as the author block, but with <code class="html">&lt;dc:contributor id="producer-1"&gt;</code>.</p>
<ol>
<li>
<p>You can include the <code class="html">&lt;meta property="se:url.homepage" refines="#producer-1"&gt;</code> element with a link to your personal homepage. This must be a link to a personal homepage only; no products, services, or other endorsements, commercial or otherwise.</p>
</li>
<li>
<p>Your MARC relator roles will usually be the following:</p>
<ul>
<li>
<p><code class="marc">bkp</code>: you are the producer of this ebook.</p>
</li>
<li>
<p><code class="marc">blw</code>: you wrote the blurb (the long description).</p>
</li>
<li>
<p><code class="marc">cov</code>: you selected the cover art.</p>
</li>
<li>
<p><code class="marc">mrk</code>: you wrote HTML markup for this ebook.</p>
</li>
<li>
<p><code class="marc">pfr</code>: you proofread the ebook.</p>
</li>
<li>
<p><code class="marc">tyg</code>: you reviewed the typography of the ebook.</p>
</li>
</ul>
</li>
</ol>
<h2>The <code class="html">&lt;manifest&gt;</code> element</h2>
<p>The <code class="html">&lt;manifest&gt;</code> element is a required part of the epub spec. This should usually be generated by the <code class="program">print-manifest</code> tool and copy-and-pasted into the <code class="path">content.opf</code> file. It must be in alphabetical order, which is handled for you by the <code class="program">print-manifest-and-spine</code> tool.</p>
<h2>The <code class="html">&lt;spine&gt;</code> element</h2>
<p>The <code class="html">&lt;spine&gt;</code> element is a required part of the epub spec that defines the reading order of the files in the ebook. You can use the <code class="program">print-spine</code> tool to generate a draft of the spine. The tool makes a best guess as to the spine order, but it cannot be 100% correct; please review the output and adjust the reading order accordingly.</p>
</article>
</main>
<?= Template::Footer() ?>

2
www/contribute/producers.php
View file

@ -19,7 +19,7 @@ require_once('Core.php');
<p>Contact the <a href="https://groups.google.com/forum/#!forum/standardebooks">Standard Ebooks mailing list</a> to pitch the ebook you’ve selected, <em>before you begin production</em>.</p>
</li>
<li>
<p>Carefully review the entirety of the Standard Ebooks <a href="/contribute/typography">Typography Manual</a>, <a href="/contribute/semantics">Semantics Manual</a>, and <a href="/contribute/metadata">Metadata Manual</a>.</p>
<p>Carefully review the entirety of the <a href="/manual">Standard Ebooks Manual of Style</a>.</p>
<li>
<p>Once we’ve OK’d your selection and you’ve read the style manuals, you can get started! Follow the steps in our <a href="/contribute/producing-an-ebook-step-by-step">step-by-step guide to producing an ebook</a> to take your ebook from start to finish.</p>
</li>

286
www/contribute/producing-an-ebook-step-by-step.php
View file

@ -1,25 +1,22 @@
<?
require_once('Core.php');
?><?= Template::Header(['title' => 'Producing an Ebook, Step by Step', 'js' => true, 'highlight' => 'contribute', 'description' => 'A detailed step-by-step description of the complete process of producing an ebook for the Standard Ebooks project, start to finish.']) ?>
<main>
?><?= Template::Header(['title' => 'Producing an Ebook, Step by Step', 'manual' => true, 'highlight' => 'contribute', 'description' => 'A detailed step-by-step description of the complete process of producing an ebook for the Standard Ebooks project, start to finish.']) ?>
<main class="manual">
<article id="producing-an-ebook">
<h1>Producing an Ebook, Step by Step</h1>
<aside class="alert">
<p>Our toolset is GNU/Linux-based, and producing an ebook from scratch currently requires working knowledge of the epub file format and of Unix-like systems like Mac or Linux.</p>
<p>Our toolset doesn’t yet work natively on Windows, but there are <a href="https://www.howtogeek.com/170870/5-ways-to-run-linux-software-on-windows/">many ways to run Linux from within Windows</a>.</p>
<p>If you don’t have this kind of technical expertise, you can still contribute! <a href="/contribute/">Check out our contributors page for details.</a></p>
</aside>
<p>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).</p>
<p>Our toolset is GNU/Linux-based, and producing an ebook from scratch currently requires working knowledge of the epub file format and of Unix-like systems like Mac or Linux.</p>
<p>Our toolset doesn’t yet work natively on Windows, but there are <a href="https://www.howtogeek.com/170870/5-ways-to-run-linux-software-on-windows/">many ways to run Linux from within Windows</a>.</p>
<p>If you don’t have this kind of technical expertise, you can still contribute! <a href="/contribute/">Check out our contributors page for details.</a></p>
<ol class="full">
<li>
<h2>Download and set up the Standard Ebooks production toolset</h2>
<p>The Standard Ebooks project has a toolset that will help you produce an ebook. <a href="https://github.com/standardebooks/tools">Read how to install them here.</a></p>
<p>Make sure you take a moment to put the <code class="program">se</code> executable that’s installed with the toolset on your shell’s <code class="path">$PATH</code>. How to do that varies depending on what shell you’re using.</p>
</li>
<li>
<h2>Make sure the toolset is up-to-date</h2>
<p>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.</p>
<code class="terminal"><span>pipx upgrade standardebooks</span></code>
<h2>Set up the Standard Ebooks toolset and make sure it’s up-to-date</h2>
<p>The Standard Ebooks project has a toolset that will help you produce an ebook. The toolset installs the <code class="bash"><b>se</b></code> command, which has various subcommands related to creating Standard Ebooks. You can <a href="https://github.com/standardebooks/tools">read the complete installation instructions</a>, or if you already have <a href="https://pipxproject.github.io/pipx/installation/"><code class="bash"><b>pipx</b></code> installed</a>, run:</p>
<code class="terminal"><span><b>pipx</b> install standardebooks</span></code>
<p>The toolset changes frequently, so if you’ve installed the toolset in the past, make sure to update the toolset before you start a new ebook:</p>
<code class="terminal"><span><b>pipx</b> upgrade standardebooks</span></code>
<p>Once the toolset is installed, you can check which version you have with:</p>
<code class="terminal"><span><b>se</b> --version</span></code>
</li>
<li>
<h2>Select an ebook to produce</h2>
@ -29,7 +26,7 @@ require_once('Core.php');
<p>There may be different versions of the same publication on Gutenberg, and <em>the best one might not be the one with the most downloads</em>. 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 <i>20,000 Leagues Under the Seas</i>. The most-downloaded version is an <a href="https://www.gutenberg.org/ebooks/164" rel="nofollow">old translation widely criticized as being slapdash and inaccurate</a>. The less popular version is a <a href="https://www.gutenberg.org/ebooks/2488">fresh, modern translation dedicated to the public domain</a>.</p>
</li>
<li>
<p>Gutenberg usually offers both an HTML version and an epub version of the same ebook. Note that <em>one is not always exactly the same as the other!</em> 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 <code class="html">&lt;em&gt;</code> tags that the epub version is often missing.</p>
<p>Gutenberg usually offers both an HTML version and an epub version of the same ebook. Note that <em>one is not always exactly the same as the other!</em> 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 <code class="html"><span class="p">&lt;</span><span class="nt">em</span><span class="p">&gt;</span></code> elements that the epub version is often missing.</p>
</li>
</ul>
<p>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.</p>
@ -61,26 +58,26 @@ require_once('Core.php');
<p>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!</p>
</li>
</ul>
<p>You’ll enter a link to the page scans you used in the <code class="path">content.opf</code> metadata as a <code class="html">&lt;dc:source&gt;</code> element.</p>
<p>You’ll enter a link to the page scans you used in the <code class="path">content.opf</code> metadata as a <code class="html"><span class="p">&lt;</span><span class="nt">dc:source</span><span class="p">&gt;</span></code> element.</p>
</li>
<li>
<h2>Create a Standard Ebooks epub skeleton</h2>
<p>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.</p>
<p>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. <code class="program">se create-draft</code> will create a basic Standard Ebooks epub folder structure, initialize a <code class="program">git</code> repository within it, and prefill a few fields in <code class="path">content.opf</code> (the file that contains the ebook’s metadata).</p>
<p>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. <code class="bash"><b>se</b> create-draft</code> will create a basic Standard Ebooks epub folder structure, initialize a Git repository within it, and prefill a few fields in <code class="path">content.opf</code> (the file that contains the ebook’s metadata).</p>
<ol>
<li>
<h3>With the <code class="program">--pg-url</code> option</h3>
<p>You can pass <code class="program">se create-draft</code> the URL for the Project Gutenberg ebook, and it’ll try to download the ebook into <code class="path">./src/epub/text/body.xhtml</code> and prefill a lot of metadata for you:</p><code class="terminal"><span>se create-draft --author="Robert Louis Stevenson" --title="The Strange Case of Dr. Jekyll and Mr. Hyde" --pg-url="https://www.gutenberg.org/ebooks/43"</span> <span>cd robert-louis-stevenson_the-strange-case-of-dr-jekyll-and-mr-hyde/</span></code>
<p>Because Project Gutenberg ebooks are produced in different ways by different people, <code class="program">se create-draft</code> has to make some guesses and it might guess wrong. Make sure to carefully review the data it prefills into <code class="path">./src/epub/text/body.xhtml</code>, <code class="path">./src/epub/text/colophon.xhtml</code>, and <code class="path">./src/epub/content.opf</code>.</p>
<h3>With the <code class="bash">--pg-url</code> option</h3>
<p>You can pass <code class="bash"><b>se</b> create-draft</code> the URL for the Project Gutenberg ebook, and it’ll try to download the ebook into <code class="path">./src/epub/text/body.xhtml</code> and prefill a lot of metadata for you:</p><code class="terminal"><span><b>se</b> create-draft --author=<i>"Robert Louis Stevenson"</i> --title=<i>"The Strange Case of Dr. Jekyll and Mr. Hyde"</i> --pg-url=<i>"https://www.gutenberg.org/ebooks/43"</i></span> <span><b>cd</b> <u>robert-louis-stevenson_the-strange-case-of-dr-jekyll-and-mr-hyde/</u></span></code>
<p>Because Project Gutenberg ebooks are produced in different ways by different people, <code class="bash"><b>se</b> create-draft</code> has to make some guesses and it might guess wrong. Make sure to carefully review the data it prefills into <code class="path">./src/epub/text/body.xhtml</code>, <code class="path">./src/epub/text/colophon.xhtml</code>, and <code class="path">./src/epub/content.opf</code>.</p>
<p>In particular, make sure that the Project Gutenberg license is stripped from <code class="path">./src/epub/text/body.xhtml</code>, and that the original transcribers in <code class="path">./src/epub/text/colophon.xhtml</code> and <code class="path">./src/epub/content.opf</code> are presented correctly.</p>
</li>
<li>
<h3>Without the <code class="program">--pg-url</code> option</h3>
<p>If you prefer to do things by hand, that’s an option too.</p><code class="terminal"><span>se create-draft --author="Robert Louis Stevenson" --title="The Strange Case of Dr. Jekyll and Mr. Hyde"</span> <span>cd robert-louis-stevenson_the-strange-case-of-dr-jekyll-and-mr-hyde/</span></code>
<p>Now that we have the skeleton up, we’ll download Gutenberg’s HTML file for <i>Jekyll</i> directly into <code class="path">text/</code> folder and name it <code class="path">body.xhtml</code>.</p><code class="terminal"><span>wget -O src/epub/text/body.xhtml https://www.gutenberg.org/files/43/43-h/43-h.htm</span></code>
<p>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 <code class="program">file -I</code>.)</p><code class="terminal"><span>file -bi src/epub/text/body.xhtml</span></code>
<p>The output is <code class="program">text/html; charset=iso-8859-1</code>. That’s the wrong encoding!</p>
<p>We can convert that to UTF-8 with <code class="program">iconv</code>:</p><code class="terminal"><span>iconv --from-code="ISO-8859-1" --to-code="UTF-8" &lt; src/epub/text/body.xhtml &gt; src/epub/text/tmp</span> <span>mv src/epub/text/tmp src/epub/text/body.xhtml</span></code>
<h3>Without the <code class="bash">--pg-url</code> option</h3>
<p>If you prefer to do things by hand, that’s an option too.</p><code class="terminal"><span><b>se</b> create-draft --author=<i>"Robert Louis Stevenson"</i> --title=<i>"The Strange Case of Dr. Jekyll and Mr. Hyde"</i></span> <span><b>cd</b> <u>robert-louis-stevenson_the-strange-case-of-dr-jekyll-and-mr-hyde/</u></span></code>
<p>Now that we have the skeleton up, we’ll download Gutenberg’s HTML file for <i>Jekyll</i> directly into <code class="path">text/</code> folder and name it <code class="path">body.xhtml</code>.</p><code class="terminal"><span><b>wget</b> -O src/epub/text/body.xhtml <i>"https://www.gutenberg.org/files/43/43-h/43-h.htm"</i></span></code>
<p>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 <code class="bash"><b>file</b> -I</code>.)</p><code class="terminal"><span><b>file</b> -bi <u>src/epub/text/body.xhtml</u></span></code>
<p>The output is <code class="bash">text/html; charset=iso-8859-1</code>. That’s the wrong encoding!</p>
<p>We can convert that to UTF-8 with <code class="bash"><b>iconv</b></code>:</p><code class="terminal"><span><b>iconv</b> --from-code=<i>"ISO-8859-1"</i> --to-code=<i>"UTF-8"</i> &lt; <u>src/epub/text/body.xhtml</u> &gt; src/epub/text/tmp</span> <span><b>mv</b> <u>src/epub/text/tmp</u> <u>src/epub/text/body.xhtml</u></span></code>
</li>
</ol>
</li>
@ -101,57 +98,60 @@ require_once('Core.php');
<p>This edition of <i>Jekyll</i> includes a table of contents; remove that too. Standard Ebooks uses the <abbr class="initialism">ToC</abbr> generated by the ereader, and doesn’t include one in the readable text.</p>
</li>
<li>
<p>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 <code class="program">se create-draft</code> with the <code class="program">--pg-url</code> option, then it may have already stripped the license for you and included some Gutenberg metadata.</p>
<p>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 <code class="bash"><b>se</b> create-draft</code> with the <code class="bash">--pg-url</code> option, then it may have already stripped the license for you and included some Gutenberg metadata.</p>
</li>
</ul>
<p>Now our source file looks something like this:</p>
<code class="html full">&lt;h2&gt; STORY OF THE DOOR &lt;/h2&gt;
&lt;p&gt; 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 &lt;!--snip all the way to the end...--&gt; proceed to seal up my confession, I bring the life of that unhappy Henry Jekyll to an end. &lt;/p&gt;</code>
<figure><code class="html full"><span class="p">&lt;</span><span class="nt">h2</span><span class="p">&gt;</span> STORY OF THE DOOR <span class="p">&lt;/</span><span class="nt">h2</span><span class="p">&gt;</span>
<span class="p">&lt;</span><span class="nt">p</span><span class="p">&gt;</span> 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
<span class="c">&lt;!--snip all the way to the end...--&gt;</span>
proceed to seal up my confession, I bring the life of that unhappy Henry Jekyll to an end. <span class="p">&lt;/</span><span class="nt">p</span><span class="p">&gt;</span></code></figure>
<p>Now that we’ve removed all the cruft from the top and bottom of the file, we’re ready for our first commit.</p>
<p>Please use the following commit message for consistency with the rest of our ebooks:</p><code class="terminal"><span>git add -A</span> <span>git commit -m "Initial commit"</span></code>
<p>Please use the following commit message for consistency with the rest of our ebooks:</p><code class="terminal"><span><b>git</b> add -A</span> <span><b>git</b> commit -m <i>"Initial commit"</i></span></code>
</li>
<li>
<h2>Split the source text at logical divisions</h2>
<p>The file we downloaded contains the entire work. <i>Jekyll</i> 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.</p>
<p>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 <i><a href="/ebooks/robert-louis-stevenson/treasure-island">Treasure Island</a></i>.</p>
<p>To split the work, we use <code class="program">se split-file</code>. <code class="program">se split-file</code> takes a single file and breaks it in to a new file every time it encounters the markup <code class="html">&lt;!--se:split--&gt;</code>. <code class="program">se split-file</code> automatically includes basic header and footer markup in each split file.</p>
<p>Notice that in our source file, each chapter is marked with an <code class="html">h2</code> tag. We can use that to our advantage and save ourselves the trouble of adding the <code class="html">&lt;!--se:split--&gt;</code> markup by hand:</p><code class="terminal"><span>perl -pi -e "s/&lt;h2/&lt;\!--se:split--&gt;&lt;h2/g" src/epub/text/body.xhtml</span></code>
<p>To split the work, we use <code class="bash"><b>se</b> split-file</code>. <code class="bash"><b>se</b> split-file</code> takes a single file and breaks it in to a new file every time it encounters the markup <code class="html"><span class="c">&lt;!--se:split--&gt;</span></code>. <code class="bash"><b>se</b> split-file</code> automatically includes basic header and footer markup in each split file.</p>
<p>Notice that in our source file, each chapter is marked with an <code class="html"><span class="p">&lt;</span><span class="nt">h2</span><span class="p">&gt;</span></code> tag. We can use that to our advantage and save ourselves the trouble of adding the <code class="html"><span class="c">&lt;!--se:split--&gt;</span></code> markup by hand:</p><code class="terminal"><span><b>perl</b> -pi -e <i>"s|&lt;h2|&lt;\!--se:split--&gt;&lt;h2|g"</i> <u>src/epub/text/body.xhtml</u></span></code>
<p>(Note the slash before the ! for compatibility with some shells.)</p>
<p>Now that we’ve added our markers, we split the file. <code class="program">se split-file</code> puts the results in our current directory and conveniently names them by chapter number.</p><code class="terminal"><span>se split-file src/epub/text/body.xhtml</span> <span>mv chapter* src/epub/text/</span></code>
<p>Once we’re happy that the source file has been split correctly, we can remove it.</p><code class="terminal"><span>rm src/epub/text/body.xhtml</span></code>
<p>Now that we’ve added our markers, we split the file. <code class="bash"><b>se</b> split-file</code> puts the results in our current directory and conveniently names them by chapter number.</p><code class="terminal"><span><b>se</b> split-file <u>src/epub/text/body.xhtml</u></span> <span><b>mv</b> chapter<i class="glob">*</i> <u>src/epub/text/</u></span></code>
<p>Once we’re happy that the source file has been split correctly, we can remove it.</p><code class="terminal"><span><b>rm</b> <u>src/epub/text/body.xhtml</u></span></code>
</li>
<li>
<h2>Clean up the source text</h2>
<p>If you open up any of the chapter files we now have in the <code class="path">src/epub/text/</code> folder, you’ll notice that the code isn’t very clean. Paragraphs are split over multiple lines, indentation is all wrong, and so on.</p>
<p>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 <code class="html">&amp;mdash;</code>. This is because Gutenberg uses plain HTML, which allows entities, but epub uses XHTML, which doesn’t.</p>
<p>We can fix all of this pretty quickly using <code class="program">se clean</code>. <code class="program">se clean</code> accepts as its argument the root of a Standard Ebook directory, and with the <code class="program">--single-lines</code> option it’ll remove the hard line wrapping that Gutenberg is fond of. We’re already in the root, so we pass it <code class="path">.</code>.</p><code class="terminal"><span>se clean --single-lines .</span></code>
<p>Things look much better now, but we’re not perfect yet. If you open a chapter you’ll notice that the <code class="html">&lt;p&gt;</code> and <code class="html">&lt;h2&gt;</code> tags have a space between the tag and the text. We can clean that up with a few <code class="program">perl</code> commands.</p><code class="terminal"><span>perl -pi -e "s/&lt;(p|h2)&gt;\s+/&lt;\1&gt;/g" src/epub/text/chapter*</span> <span>perl -pi -e "s/\s+&lt;\/(p|h2)&gt;/&lt;\/\1&gt;/g" src/epub/text/chapter*</span></code>
<p>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 <i>Jekyll</i>, notice that each chapter ends with some extra empty <code class="html">&lt;div&gt;</code>s and <code class="html">&lt;p&gt;</code>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.</p>
<p>We can fix all of this pretty quickly using <code class="bash"><b>se</b> clean</code>. <code class="bash"><b>se</b> clean</code> accepts as its argument the root of a Standard Ebook directory, and with the <code class="bash">--single-lines</code> option it’ll remove the hard line wrapping that Gutenberg is fond of. We’re already in the root, so we pass it <code class="path">.</code>.</p><code class="terminal"><span><b>se</b> clean --single-lines <u>.</u></span></code>
<p>Things look much better now, but we’re not perfect yet. If you open a chapter you’ll notice that the <code class="html"><span class="p">&lt;</span><span class="nt">p</span><span class="p">&gt;</span></code> and <code class="html"><span class="p">&lt;</span><span class="nt">h2</span><span class="p">&gt;</span></code> tags have a space between the tag and the text. We can clean that up with a few <code class="bash"><b>perl</b></code> commands.</p><code class="terminal"><span><b>perl</b> -pi -e <i>"s|&lt;(p|h2)&gt;\s+|&lt;\1&gt;|g"</i> src/epub/text/chapter<i class="glob">*</i></span> <span><b>perl</b> -pi -e <i>"s|\s+&lt;/(p|h2)&gt;|&lt;/\1&gt;|g"</i> src/epub/text/chapter<i class="glob">*</i></span></code>
<p>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 <i>Jekyll</i>, notice that each chapter ends with some extra empty <code class="html"><span class="p">&lt;</span><span class="nt">div</span><span class="p">&gt;</span></code>s and <code class="html"><span class="p">&lt;</span><span class="nt">p</span><span class="p">&gt;</span></code>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.</p>
<p>Now our chapter 1 source looks like this:</p>
<code class="html full">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;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: https://standardebooks.org/vocab/1.0" xml:lang="en-US"&gt;
&lt;head&gt;
&lt;title&gt;Chapter 1&lt;/title&gt;
&lt;link href="../css/core.css" rel="stylesheet" type="text/css"/&gt;
&lt;link href="../css/local.css" rel="stylesheet" type="text/css"/&gt;
&lt;/head&gt;
&lt;body epub:type="bodymatter z3998:fiction"&gt;
&lt;section id="chapter-1" epub:type="chapter"&gt;
&lt;h2&gt;STORY OF THE DOOR&lt;/h2&gt;
&lt;p&gt;Mr. Utterson the lawyer was a man of a rugged countenance...&lt;/p&gt;
&lt;!--snip all the way to the end...--&gt;
&lt;p&gt;"With all my heart," said the lawyer. "I shake hands on that, Richard."&lt;/p&gt;
&lt;/section&gt;
&lt;/body&gt;
&lt;/html&gt;</code>
<p>If you look carefully, you’ll notice that the <code class="html">&lt;html&gt;</code> tag has the <code class="html">xml:lang="en-US"</code> attribute, even though our source text uses British spelling! We have to change the <code class="html">xml:lang</code> attribute for the source files to match the actual language, which in this case is en-GB. Let’s do that now:</p><code class="terminal"><span>perl -pi -e "s|en-US|en-GB|g" src/epub/text/chapter*</span></code>
<figure><code class="html full"><span class="cp">&lt;?xml version="1.0" encoding="utf-8"?&gt;</span>
<span class="p">&lt;</span><span class="nt">html</span> <span class="na">xmlns</span><span class="o">=</span><span class="s">"http://www.w3.org/1999/xhtml"</span> <span class="na">xmlns:epub</span><span class="o">=</span><span class="s">"http://www.idpf.org/2007/ops"</span> <span class="na">epub:prefix</span><span class="o">=</span><span class="s">"z3998: http://www.daisy.org/z3998/2012/vocab/structure/, se: https://standardebooks.org/vocab/1.0"</span> <span class="na">xml:lang</span><span class="o">=</span><span class="s">"en-US"</span><span class="p">&gt;</span>
<span class="p">&lt;</span><span class="nt">head</span><span class="p">&gt;</span>
<span class="p">&lt;</span><span class="nt">title</span><span class="p">&gt;</span>Chapter 1<span class="p">&lt;/</span><span class="nt">title</span><span class="p">&gt;</span>
<span class="p">&lt;</span><span class="nt">link</span> <span class="na">href</span><span class="o">=</span><span class="s">"../css/core.css"</span> <span class="na">rel</span><span class="o">=</span><span class="s">"stylesheet"</span> <span class="na">type</span><span class="o">=</span><span class="s">"text/css"</span><span class="p">/&gt;</span>
<span class="p">&lt;</span><span class="nt">link</span> <span class="na">href</span><span class="o">=</span><span class="s">"../css/local.css"</span> <span class="na">rel</span><span class="o">=</span><span class="s">"stylesheet"</span> <span class="na">type</span><span class="o">=</span><span class="s">"text/css"</span><span class="p">/&gt;</span>
<span class="p">&lt;/</span><span class="nt">head</span><span class="p">&gt;</span>
<span class="p">&lt;</span><span class="nt">body</span> <span class="na">epub:type</span><span class="o">=</span><span class="s">"bodymatter z3998:fiction"</span><span class="p">&gt;</span>
<span class="p">&lt;</span><span class="nt">section</span> <span class="na">id</span><span class="o">=</span><span class="s">"chapter-1"</span> <span class="na">epub:type</span><span class="o">=</span><span class="s">"chapter"</span><span class="p">&gt;</span>
<span class="p">&lt;</span><span class="nt">h2</span><span class="p">&gt;</span>STORY OF THE DOOR<span class="p">&lt;/</span><span class="nt">h2</span><span class="p">&gt;</span>
<span class="p">&lt;</span><span class="nt">p</span><span class="p">&gt;</span>Mr. Utterson the lawyer was a man of a rugged countenance...<span class="p">&lt;/</span><span class="nt">p</span><span class="p">&gt;</span>
<span class="c">&lt;!--snip all the way to the end...--&gt;</span>
<span class="p">&lt;</span><span class="nt">p</span><span class="p">&gt;</span>"With all my heart," said the lawyer. "I shake hands on that, Richard."<span class="p">&lt;/</span><span class="nt">p</span><span class="p">&gt;</span>
<span class="p">&lt;/</span><span class="nt">section</span><span class="p">&gt;</span>
<span class="p">&lt;/</span><span class="nt">body</span><span class="p">&gt;</span>
<span class="p">&lt;/</span><span class="nt">html</span><span class="p">&gt;</span></code></figure>
<p>If you look carefully, you’ll notice that the <code class="html"><span class="p">&lt;</span><span class="nt">html</span><span class="p">&gt;</span></code> tag has the <code class="html"><span class="na">xml:lang</span><span class="o">=</span><span class="s">"en-US"</span></code> attribute, even though our source text uses British spelling! We have to change the <code class="html"><span class="na">xml:lang</span></code> attribute for the source files to match the actual language, which in this case is en-GB. Let’s do that now:</p><code class="terminal"><span><b>perl</b> -pi -e <i>"s|en-US|en-GB|g"</i> src/epub/text/chapter<i class="glob">*</i></span></code>
<p>Note that we <em>don’t</em> change the language for the metadata or front/back matter files, like <code class="path">content.opf</code>, <code class="path">titlepage.xhtml</code>, or <code class="path">colophon.xhtml</code>. Those must always be in American spelling, so they’ll always have the en-US language tag.</p>
</li>
<li>
<h2>Typogrify the source text and perform the second commit</h2>
<p>Now that we have a clean starting point, we can start getting the <em>real</em> work done. <code class="program">se typogrify</code> can do a lot of the heavy lifting necessary to bring an ebook up to Standard Ebooks typography standards.</p>
<p>Like <code class="program">se clean</code>, <code class="program">se typogrify</code> accepts as its argument the root of a Standard Ebook directory.</p><code class="terminal"><span>se typogrify .</span></code>
<p>Among other things, <code class="program">se typogrify</code> does the following:</p>
<p>Now that we have a clean starting point, we can start getting the <em>real</em> work done. <code class="bash"><b>se</b> typogrify</code> can do a lot of the heavy lifting necessary to bring an ebook up to Standard Ebooks typography standards.</p>
<p>Like <code class="bash"><b>se</b> clean</code>, <code class="bash"><b>se</b> typogrify</code> accepts as its argument the root of a Standard Ebook directory.</p><code class="terminal"><span><b>se</b> typogrify .</span></code>
<p>Among other things, <code class="bash"><b>se</b> typogrify</code> does the following:</p>
<ul>
<li>
<p>Converts straight quotes to curly quotes;</p>
@ -166,124 +166,133 @@ require_once('Core.php');
<p>Normalizes spacing in em-, en-, and double-em-dashes, as well as between nested quotation marks, and adds word joiners.</p>
</li>
</ul>
<p>You can run <code class="program">se typogrify</code> as 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.</p>
<p>While <code class="program">se typogrify</code> does 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 <i>Jekyll</i>, you’ll notice that the chapter titles are in all caps. The SE standard requires chapter titles to be in title case, and <code class="program">se titlecase</code> can do that for us.</p>
<p><code class="program">se titlecase</code> accepts 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 <code class="program">se titlecase</code> on selected text.</p>
<p>You can run <code class="bash"><b>se</b> typogrify</code> as 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.</p>
<p>While <code class="bash"><b>se</b> typogrify</code> does 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 <i>Jekyll</i>, you’ll notice that the chapter titles are in all caps. The SE standard requires chapter titles to be in title case, and <code class="bash"><b>se</b> titlecase</code> can do that for us.</p>
<p><code class="bash"><b>se</b> titlecase</code> accepts 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 <code class="bash"><b>se</b> titlecase</code> on selected text.</p>
<h3>Typography checklist</h3>
<p>There are many things that <code class="program">se typogrify</code> isn’t well suited to do automatically. Check <a href="/contribute/typography">our complete typography manual</a> to see exactly how to format the work. Below is a brief, but incomplete, list of common issues that arise in ebooks:</p>
<p>There are many things that <code class="bash"><b>se</b> typogrify</code> isn’t well suited to do automatically. Check <a href="/manual/latest/8-typography">our complete typography manual</a> to see exactly how to format the work. Below is a brief, but incomplete, list of common issues that arise in ebooks:</p>
<ul>
<li>
<p><a href="/contribute/typography#coordinates">Typography rules for coordinates</a>. Use the prime and double prime glyphs for coordinates. These regexes helps match and replace coordinates: <code class="regex">|([0-9])+’|\1′|g</code>, <code class="regex">|([0-9])+”|\1″|g</code></p>
<p><a href="/manual/latest/8-typography#8.8.1">Typography rules for coordinates</a>. Use the prime and double prime glyphs for coordinates. These regexes helps match and replace coordinates: <code class="regex">|([0-9])+’|\1′|g</code>, <code class="regex">|([0-9])+”|\1″|g</code></p>
</li>
<li>
<p><a href="/contribute/typography#ampersands-in-names">Typography rules for ampersands in names</a>. This regex helps match candidates: <code class="regex">[a-zA-Z]\.?\s*&amp;\s*[a-zA-Z]</code></p>
<p><a href="/manual/latest/8-typography#8.7.3">Typography rules for ampersands in names</a>. This regex helps match candidates: <code class="regex">[a-zA-Z]\.?\s*&amp;\s*[a-zA-Z]</code></p>
</li>
<li>
<p><a href="/contribute/typography#text-in-all-caps">Typography rules for text in all caps</a>. Text in all caps is almost never correct, and should either be converted to lowercase with the <code class="html">&lt;em&gt;</code> tag (for spoken emphasis), <code class="html">&lt;strong&gt;</code> (for extreme spoken emphasis), or <code class="html">&lt;b&gt;</code> (for unsemantic small caps, like in storefront signs). This case-sensitive regex helps find candidates: <code class="regex">(?&lt;!en-)(?&lt;!z3998:roman">)(?&lt;![A-Z])[A-Z]{2,}(?!")</code></p>
<p><a href="/manual/latest/8-typography#8.3.3">Typography rules for text in all caps</a>. Text in all caps is almost never correct, and should either be converted to lowercase with the <code class="html"><span class="p">&lt;</span><span class="nt">em</span><span class="p">&gt;</span></code> tag (for spoken emphasis), <code class="html"><span class="p">&lt;</span><span class="nt">strong</span><span class="p">&gt;</span></code> (for extreme spoken emphasis), or <code class="html"><span class="p">&lt;</span><span class="nt">b</span><span class="p">&gt;</span></code> (for unsemantic small caps, like in storefront signs). This case-sensitive regex helps find candidates: <code class="regex">(?<span class="p">&lt;</span>!en-)(?<span class="p">&lt;</span>!z3998:roman">)(?<span class="p">&lt;</span>![A-Z])[A-Z]{2,}(?!")</code></p>
</li>
<li>
<p>Sometimes <code class="program">se typogrify</code> doesn’t close quotation marks near em-dashes correctly. Try to find such instances with this regex: <code class="regex">—[’”][^&lt;\s]</code></p>
<p>Sometimes <code class="bash"><b>se</b> typogrify</code> doesn’t close quotation marks near em-dashes correctly. Try to find such instances with this regex: <code class="regex">—[’”][^<span class="p">&lt;</span>\s]</code></p>
</li>
<li>
<p><a href="/contribute/typography#dashes">Two-em dashes should be used for elision</a>.</p>
<p><a href="/manual/latest/8-typography#8.7.7">Two-em dashes should be used for elision</a>.</p>
</li>
<li>
<p>Commas and periods should generally be inside quotation marks, not outside. This regex helps find them: <code class="regex">[’”][,.]</code></p>
</li>
</ul>
<h3>The second commit</h3>
<p>Once you’ve run <code class="program">se typogrify</code> and you’ve searched the work for the common issues above, you can perform your second commit.</p><code class="terminal"><span>git add -A</span> <span>git commit -m "Typogrify"</span></code>
<p>Once you’ve run <code class="bash"><b>se</b> typogrify</code> and you’ve searched the work for the common issues above, you can perform your second commit.</p><code class="terminal"><span><b>git</b> add -A</span> <span><b>git</b> commit -m <i>"Typogrify"</i></span></code>
</li>
<li>
<h2>Convert footnotes to endnotes and add a list of illustrations</h2>
<p>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.</p>
<p>The endnotes file and the format for endnote links are <a href="/contribute/semantics#endnotes">standardized in the semantics manual</a>.</p>
<p>If you find that you accidentally mis-ordered an endnote, never fear! <code class="program">se reorder-endnotes</code> will allow you to quickly rearrange endnotes in your ebook.</p>
<p>If you find that you accidentally mis-ordered an endnote, never fear! <code class="bash"><b>se</b> reorder-endnotes</code> will allow you to quickly rearrange endnotes in your ebook.</p>
<p>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 <abbr class="initialism">LoI</abbr> file is also <a href="/contribute/semantics#loi">standardized in the semantics manual</a>.</p>
<p><i>Jekyll</i> doesn’t have any footnotes, endnotes, or illustrations, so we skip this step.</p>
</li>
<li>
<h2>Converting British quotation to American quotation</h2>
<p>If the work you’re producing uses <a href="http://www.thepunctuationguide.com/british-versus-american-style.html">British quotation style</a> (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. <em>Skip this step if your work is already in American style.</em></p>
<p><code class="program">se british2american</code> attempts to automate the conversion. Your work must already be typogrified (the previous step in this guide) for the script to work.</p><code class="terminal"><span>se british2american .</span></code>
<p>While <code class="program">se british2american</code> tries its best, thanks to the quirkiness of English punctuation rules it’ll invariably mess some stuff up. Proofreading is required after running the conversion.</p>
<p>After you’ve run the conversion, do another commit.</p><code class="terminal"><span>git add -A</span> <span>git commit -m "Convert from British-style quotation to American style"</span></code>
<p><code class="bash"><b>se</b> british2american</code> attempts to automate the conversion. Your work must already be typogrified (the previous step in this guide) for the script to work.</p><code class="terminal"><span><b>se</b> british2american <u>.</u></span></code>
<p>While <code class="bash"><b>se</b> british2american</code> tries its best, thanks to the quirkiness of English punctuation rules it’ll invariably mess some stuff up. Proofreading is required after running the conversion.</p>
<p>After you’ve run the conversion, do another commit.</p><code class="terminal"><span><b>git</b> add -A</span> <span><b>git</b> commit -m <i>"Convert from British-style quotation to American style"</i></span></code>
<p>This regex is useful for spotting incorrectly converted quotes next to em dashes: <code class="regex">“[^”‘]+’⁠—(?=[^”]*?&lt;/p&gt;;)</code>
</li>
<li>
<h2>Add semantics</h2>
<p>Part of the Standard Ebooks project is adding meaningful semantics wherever possible in the text. <code class="program">se semanticate</code> does a little of that for us—for example, for some common abbreviations—but much of it has to be done by hand.</p>
<p>Part of the Standard Ebooks project is adding meaningful semantics wherever possible in the text. <code class="bash"><b>se</b> semanticate</code> does a little of that for us—for example, for some common abbreviations—but much of it has to be done by hand.</p>
<p>Adding semantics means two things:</p>
<ol>
<li>
<p>Using meaningful tags to mark up the work: <code class="html">&lt;em&gt;</code> when conveying emphatic speech instead of <code class="html">&lt;i&gt;</code>, <code class="html">&lt;abbr&gt;</code> to wrap abbreviations, <code class="html">&lt;section&gt;</code> to mark structural divisions, using the <code class="html">xml:lang</code> attribute to specify the language of a word or passage, and so on.</p>
<p>Using meaningful tags to mark up the work: <code class="html"><span class="p">&lt;</span><span class="nt">em</span><span class="p">&gt;</span></code> when conveying emphatic speech instead of <code class="html"><span class="p">&lt;</span><span class="nt">i</span><span class="p">&gt;</span></code>, <code class="html"><span class="p">&lt;</span><span class="nt">abbr</span><span class="p">&gt;</span></code> to wrap abbreviations, <code class="html"><span class="p">&lt;</span><span class="nt">section</span><span class="p">&gt;</span></code> to mark structural divisions, using the <code class="html"><span class="na">xml:lang</span></code> attribute to specify the language of a word or passage, and so on.</p>
</li>
<li>
<p>Using the <a href="http://www.idpf.org/epub/30/spec/epub30-contentdocs.html#sec-xhtml-semantic-inflection">epub3 semantic inflection language</a> to add deeper meaning to tags.</p>
<p>Currently we use a mix of <a href="http://www.idpf.org/epub/vocab/structure/">epub3 structural semantics</a>, <a href="http://www.daisy.org/z3998/2012/vocab/structure/">z3998 structural semantics</a> for when the epub3 vocabulary isn’t enough, and our own <a href="/vocab/1.0">SE semantics</a> for when z3998 isn’t enough.</p>
</li>
</ol>
<p>Use <code class="program">se semanticate</code> to do some common cases for you:</p><code class="terminal"><span>se semanticate .</span></code>
<p><code class="program">se semanticate</code> tries its best to correctly add semantics, but sometimes it’s wrong. For that reason you should review the changes it made before accepting them:</p><code class="terminal"><span>git difftool</span></code>
<p>Use <code class="bash"><b>se</b> semanticate</code> to do some common cases for you:</p><code class="terminal"><span><b>se</b> semanticate <u>.</u></span></code>
<p><code class="bash"><b>se</b> semanticate</code> tries its best to correctly add semantics, but sometimes it’s wrong. For that reason you should review the changes it made before accepting them:</p><code class="terminal"><span><b>git</b> difftool</span></code>
<p>Beyond that, adding semantics is mostly a by-hand process. See our <a href="/contribute/semantics">semantics manual</a> for a detailed list of the kinds of semantics we expect in a Standard Ebook.</p>
<p>Here’s a short list of some of the more common semantic issues you’ll encounter:</p>
<ul>
<li>
<p>Semantics for italics: <code class="html">&lt;em&gt;</code> should be used for when a passage is emphasized, as in when dialog is shouted or whispered. <code class="html">&lt;i&gt;</code> is used for all other italics, <a href="/contribute/semantics#semantic-inflection">with the appropriate semantic inflection</a>. Older transcriptions usually use just <code class="html">&lt;i&gt;</code> for both, so you must change them manually if necessary.</p>
<p>Semantics for italics: <code class="html"><span class="p">&lt;</span><span class="nt">em</span><span class="p">&gt;</span></code> should be used for when a passage is emphasized, as in when dialog is shouted or whispered. <code class="html"><span class="p">&lt;</span><span class="nt">i</span><span class="p">&gt;</span></code> is used for all other italics, <a href="/contribute/semantics#semantic-inflection">with the appropriate semantic inflection</a>. Older transcriptions usually use just <code class="html"><span class="p">&lt;</span><span class="nt">i</span><span class="p">&gt;</span></code> for both, so you must change them manually if necessary.</p>
</li>
<li>
<p><a href="/contribute/typography#chapters">Semantics rules for chapter titles</a>.</p>
<p><a href="/manual/latest/8-typography#8.1">Semantics rules for chapter titles</a>.</p>
</li>
<li>
<p><a href="/contribute/semantics#abbreviations">Semantics rules for abbreviations</a>. Abbreviations should always be wrapped in the <code class="html">&lt;abbr&gt;</code> tag and with the correct <code class="html">class</code> attribute.</p>
<p>Specifically, see the <a href="/contribute/typography#initials">typography rules for initials</a>. Wrap people’s initials in <code class="html">&lt;abbr class="name"&gt;</code>. This regex helps match initials: <code class="regex">[A-Z]\.\s*([A-Z]\.\s*)+</code></p>
<p><a href="/manual/latest/8-typography#8.10">Semantics rules for abbreviations</a>. Abbreviations should always be wrapped in the <code class="html"><span class="p">&lt;</span><span class="nt">abbr</span><span class="p">&gt;</span></code> tag and with the correct <code class="html"><span class="na">class</span></code> attribute.</p>
<p>Specifically, see the <a href="/manual/latest/8-typography#8.10.6">typography rules for initials</a>. Wrap people’s initials in <code class="html"><span class="p">&lt;</span><span class="nt">abbr</span> <span class="na">class<span class="o">=</span><span class="s">"name"</span><span class="p">&gt;</span></code>. This regex helps match initials: <code class="regex">[A-Z]\.\s*([A-Z]\.\s*)+</code></p>
</li>
<li>
<p><a href="/contribute/typography#times">Typography rules for times</a>. Wrap a.m. and p.m. in <code class="html">&lt;abbr class="time"&gt;</code> and add a no-break space between digits and a.m. or p.m.</p>
<p><a href="/manual/latest/8-typography#8.11">Typography rules for times</a>. Wrap a.m. and p.m. in <code class="html"><span class="p">&lt;</span><span class="nt">abbr</span> <span class="na">class<span class="o">=</span><span class="s">"time"</span><span class="p">&gt;</span></code> and add a no-break space between digits and a.m. or p.m.</p>
</li>
<li>
<p>Words or phrases in foreign languages should always be marked up with <code class="html">&lt;i xml:lang="TAG"&gt;</code>, where TAG is an <a href="https://en.wikipedia.org/wiki/IETF_language_tag">IETF language tag</a>. <a href="https://r12a.github.io/app-subtags/">This app can help you look them up</a>. If the text uses fictional or unspecific languages, use the “x-” prefix and make up a subtag yourself.</p>
<p>Words or phrases in foreign languages should always be marked up with <code class="html"><span class="p">&lt;</span><span class="nt">i</span> <span class="na">xml:lang<span class="o">=</span><span class="s">"TAG"</span><span class="p">&gt;</span></code>, where TAG is an <a href="https://en.wikipedia.org/wiki/IETF_language_tag">IETF language tag</a>. <a href="https://r12a.github.io/app-subtags/">This app can help you look them up</a>. If the text uses fictional or unspecific languages, use the “x-” prefix and make up a subtag yourself.</p>
</li>
<li>
<p>Semantics for poetry, verse, and song: Many Gutenberg productions use the <code class="html">&lt;pre&gt;</code> tag to format poetry, verse, and song. This is, of course, semantically incorrect. <a href="/contribute/semantics#poetry">See the Poetry section of our semantics manual</a> for templates on how to semantically format poetry, verse, and song.</p>
<p>Semantics for poetry, verse, and song: Many Gutenberg productions use the <code class="html"><span class="p">&lt;</span><span class="nt">pre</span><span class="p">&gt;</span></code> tag to format poetry, verse, and song. This is, of course, semantically incorrect. <a href="/contribute/semantics#poetry">See the Poetry section of our semantics manual</a> for templates on how to semantically format poetry, verse, and song.</p>
</li>
</ul>
<p>After you’ve added semantics according to the <a href="/contribute/semantics">semantics manual</a>, do another commit.</p><code class="terminal"><span>git add -A</span> <span>git commit -m "Semanticate"</span></code>
<p>After you’ve added semantics according to the <a href="/contribute/semantics">semantics manual</a>, do another commit.</p><code class="terminal"><span><b>git</b> add -A</span> <span><b>git</b> commit -m <i>"Semanticate"</i></span></code>
</li>
<li>
<h2>Set <code class="html"><span class="p">&lt;</span><span class="nt">title</span><span class="p">&gt;</span></code> elements</h2>
<p>After you’ve added semantics and correctly marked up <a href="/manual/latest/7-high-level-structural-patterns#7.2">section headers</a>, it’s time to update the <code class="html"><span class="p">&lt;</span><span class="nt">title</span><span class="p">&gt;</span></code> elements in each chapter to match <a href="/manual/latest/5-general-xhtml-patterns#5.4">their expected values</a>.</p>
<p>The <code class="bash"><b>se</b> print-title</code> tool takes a well-marked-up section header from a file, and prints the expected value for the <code class="html"><span class="p">&lt;</span><span class="nt">title</span><span class="p">&gt;</span></code> element to the terminal. It also has the <code class="bash">--in-place</code> optoin, which will allow us to update all the chapters at once:</p>
<code class="terminal"><span><b>se</b> print-title --in-place src/epub/text/<i class="glob">*</i></span></code>
<p>Once you’ve verified the titles look good, commit:</p>
<code class="terminal"><span><b>git</b> add -A</span> <span><b>git</b> commit -m <i>"Add titles"</i></span></code>
</li>
</li>
<li>
<h2>Modernize spelling and hyphenation</h2>
<p>Many older works use outdated spelling and hyphenation that would distract a modern reader. (For example, “to-night” instead of “tonight”). <code class="program">se modernize-spelling</code> automatically removes hyphens from words that used to be compounded, but aren’t anymore in modern English spelling.</p>
<p><em>Do</em> run this tool on prose. <em>Don’t</em> run this tool on poetry.</p><code class="terminal"><span>se modernize-spelling .</span></code>
<p>Many older works use outdated spelling and hyphenation that would distract a modern reader. (For example, “to-night” instead of “tonight”). <code class="bash"><b>se</b> modernize-spelling</code> automatically removes hyphens from words that used to be compounded, but aren’t anymore in modern English spelling.</p>
<p><em>Do</em> run this tool on prose. <em>Don’t</em> run this tool on poetry.</p><code class="terminal"><span><b>se</b> modernize-spelling <u>.</u></span></code>
<p>After you run the tool, <em>you must check what the tool did to confirm that each removed hyphen is correct</em>. 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.</p>
<p>Here’s a real-world example of where <code class="program">se modernize-spelling</code> made the wrong choice: In <i><a href="/ebooks/oscar-wilde/the-picture-of-dorian-gray">The Picture of Dorian Gray</a></i> chapter 11, Oscar Wilde writes:</p>
<p>Here’s a real-world example of where <code class="bash"><b>se</b> modernize-spelling</code> made the wrong choice: In <i><a href="/ebooks/oscar-wilde/the-picture-of-dorian-gray">The Picture of Dorian Gray</a></i> chapter 11, Oscar Wilde writes:</p>
<blockquote>
<p>He possessed a gorgeous cope of crimson silk and gold-thread damask…</p>
</blockquote>
<p><code class="program">se modernize-spelling</code> would replace the dash in <code class="html">gold-thread</code> so that it reads <code class="html">goldthread</code>. Well <code class="html">goldthread</code> is 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, <em>not</em> a golden fabric thread! In this case, <code class="program">se modernize-spelling</code> made an incorrect replacement, and we have to change it back.</p>
<p><code class="program">git</code> provides a handy way for us to visualize these differences:</p><code class="terminal"><span>git difftool</span></code>
<p><code class="bash"><b>se</b> modernize-spelling</code> would replace the dash in <code class="html">gold-thread</code> so that it reads <code class="html">goldthread</code>. Well <code class="html">goldthread</code> is 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, <em>not</em> a golden fabric thread! In this case, <code class="bash"><b>se</b> modernize-spelling</code> made an incorrect replacement, and we have to change it back.</p>
<p><code class="bash"><b>git</b></code> provides a handy way for us to visualize these differences:</p><code class="terminal"><span><b>git</b> difftool</span></code>
<p>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.</p>
<p>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 <code class="program">git</code> history can be easily searched by people looking to revert changes.</p><code class="terminal"><span>git commit -am "[Editorial] Modernize hyphenation and spelling"</span></code>
<p>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 <code class="bash"><b>git</b></code> history can be easily searched by people looking to revert changes.</p><code class="terminal"><span><b>git</b> commit -am <i>"[Editorial] Modernize hyphenation and spelling"</i></span></code>
</li>
<li>
<h2>Modernize spacing in select words</h2>
<p>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.</p>
<p>Note that we use <code class="program">se interactive-sr</code> to 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 <a href="/ebooks/anton-chekhov/short-fiction/constance-garnett/">Anton Chekhov’s short fiction</a> <em>should not</em> be corrected:</p>
<p>Note that we use <code class="bash"><b>se</b> interactive-sr</code> to 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 <a href="/ebooks/anton-chekhov/short-fiction/constance-garnett/">Anton Chekhov’s short fiction</a> <em>should not</em> be corrected:</p>
<blockquote>
<p>He wanted to think of some one part of nature as yet untouched...</p>
</blockquote>
<p>Use the following regular expression invocations to correct a certain set of such phrases:</p>
<code class="terminal"><span>se interactive-sr "/\v([Ss])ome one/\1omeone/" src/epub/text/*</span> <span>git commit -am "[Editorial] some one -&gt; someone"</span></code>
<code class="terminal"><span>se interactive-sr "/\v(&lt;[Aa])ny one/\1nyone/" src/epub/text/*</span> <span>git commit -am "[Editorial] any one -&gt; anyone"</span></code>
<code class="terminal"><span>se interactive-sr "/\v([Ee])very one(\s+of)@\!/\1veryone/" src/epub/text/*</span> <span>git commit -am "[Editorial] every one -&gt; everyone"</span></code>
<code class="terminal"><span>se interactive-sr "/\v([Ee])very thing/\1verything/" src/epub/text/*</span> <span>git commit -am "[Editorial] every thing -&gt; everything"</span></code>
<code class="terminal"><span>se interactive-sr "/\v(&lt;[Aa])ny thing/\1nything/" src/epub/text/*</span> <span>git commit -am "[Editorial] any thing -&gt; anything"</span></code>
<code class="terminal"><span>se interactive-sr "/\v([Ff])or ever(&gt;)/\1orever\2/" src/epub/text/*</span> <span>git commit -am "[Editorial] for ever -&gt; forever"</span></code>
<code class="terminal"><span>se interactive-sr "/\v(in\s+)@&lt;\!(&lt;[Aa])ny way/\2nyway/" src/epub/text/*</span> <span>git commit -am "[Editorial] any way -&gt; anyway"</span></code>
<code class="terminal"><span>se interactive-sr "/\v([Yy])our self/\1ourself/" src/epub/text/*</span> <span>git commit -am "[Editorial] your self -&gt; yourself"</span></code>
<code class="terminal"><span>se interactive-sr "/\v([Mm])ean time/\1eantime/" src/epub/text/*</span> <span>git commit -am "[Editorial] mean time -&gt; meantime"</span></code>
<code class="terminal"><span>se interactive-sr "/\v([Aa])ny how/\1nyhow/" src/epub/text/*</span> <span>git commit -am "[Editorial] any how -&gt; anyhow"</span></code>
<code class="terminal"><span>se interactive-sr "/\v([Aa])ny body/\1nybody/" src/epub/text/*</span> <span>git commit -am "[Editorial] any body -&gt; anybody"</span></code>
<code class="terminal"><span>se interactive-sr "/\v([Ee])very body/\1verybody/" src/epub/text/*</span> <span>git commit -am "[Editorial] every body -&gt; everybody"</span></code>
<code class="terminal"><span><b>se</b> interactive-sr <i>"/\v([Ss])ome one/\1omeone/"</i> src/epub/text/<i class="glob">*</i></span> <span><b>git</b> commit -am <i>"[Editorial] some one -&gt; someone"</i></span></code>
<code class="terminal"><span><b>se</b> interactive-sr <i>"/\v(&lt;[Aa])ny one/\1nyone/"</i> src/epub/text/<i class="glob">*</i></span> <span><b>git</b> commit -am <i>"[Editorial] any one -&gt; anyone"</i></span></code>
<code class="terminal"><span><b>se</b> interactive-sr <i>"/\v([Ee])very one(\s+of)@\!/\1veryone/"</i> src/epub/text/<i class="glob">*</i></span> <span><b>git</b> commit -am <i>"[Editorial] every one -&gt; everyone"</i></span></code>
<code class="terminal"><span><b>se</b> interactive-sr <i>"/\v([Ee])very thing/\1verything/"</i> src/epub/text/<i class="glob">*</i></span> <span><b>git</b> commit -am <i>"[Editorial] every thing -&gt; everything"</i></span></code>
<code class="terminal"><span><b>se</b> interactive-sr <i>"/\v(&lt;[Aa])ny thing/\1nything/"</i> src/epub/text/<i class="glob">*</i></span> <span><b>git</b> commit -am <i>"[Editorial] any thing -&gt; anything"</i></span></code>
<code class="terminal"><span><b>se</b> interactive-sr <i>"/\v([Ff])or ever(&gt;)/\1orever\2/"</i> src/epub/text/<i class="glob">*</i></span> <span><b>git</b> commit -am <i>"[Editorial] for ever -&gt; forever"</i></span></code>
<code class="terminal"><span><b>se</b> interactive-sr <i>"/\v(in\s+)@&lt;\!(&lt;[Aa])ny way/\2nyway/"</i> src/epub/text/<i class="glob">*</i></span> <span><b>git</b> commit -am <i>"[Editorial] any way -&gt; anyway"</i></span></code>
<code class="terminal"><span><b>se</b> interactive-sr <i>"/\v([Yy])our self/\1ourself/"</i> src/epub/text/<i class="glob">*</i></span> <span><b>git</b> commit -am <i>"[Editorial] your self -&gt; yourself"</i></span></code>
<code class="terminal"><span><b>se</b> interactive-sr <i>"/\v([Mm])ean time/\1eantime/"</i> src/epub/text/<i class="glob">*</i></span> <span><b>git</b> commit -am <i>"[Editorial] mean time -&gt; meantime"</i></span></code>
<code class="terminal"><span><b>se</b> interactive-sr <i>"/\v([Aa])ny how/\1nyhow/"</i> src/epub/text/<i class="glob">*</i></span> <span><b>git</b> commit -am <i>"[Editorial] any how -&gt; anyhow"</i></span></code>
<code class="terminal"><span><b>se</b> interactive-sr <i>"/\v([Aa])ny body/\1nybody/"</i> src/epub/text/<i class="glob">*</i></span> <span><b>git</b> commit -am <i>"[Editorial] any body -&gt; anybody"</i></span></code>
<code class="terminal"><span><b>se</b> interactive-sr <i>"/\v([Ee])very body/\1verybody/"</i> src/epub/text/<i class="glob">*</i></span> <span><b>git</b> commit -am <i>"[Editorial] every body -&gt; everybody"</i></span></code>
</li>
<li>
<h2>Create the cover image</h2>
@ -323,46 +332,46 @@ require_once('Core.php');
<p><code class="path">cover.jpg</code> is the scaled cover image that <code class="path">cover.svg</code> links to. This file is exactly 1400 × 2100. For <i>Jekyll</i>, this is a crop of <code class="path">cover.source.jpg</code> that includes just the lab equipment, and resized up to our target resolution.</p>
</li>
<li>
<p><code class="path">cover.svg</code> is the completed cover image with the title and author. <code class="program">se build-images</code> will take <code class="path">cover.svg</code>, embed <code class="path">cover.jpg</code>, convert the text to paths, and place the result in <code class="path">./src/epub/images/</code> for inclusion in the final epub.</p>
<p><code class="path">cover.svg</code> is the completed cover image with the title and author. <code class="bash"><b>se</b> build-images</code> will take <code class="path">cover.svg</code>, embed <code class="path">cover.jpg</code>, convert the text to paths, and place the result in <code class="path">./src/epub/images/</code> for inclusion in the final epub.</p>
</li>
</ul>
</li>
<li>
<h2>Create the titlepage image, build both the cover and titlepage, and commit</h2>
<p>Titlepage images for Standard Ebooks books are also standardized. See our the <a href="https://standardebooks.org/contribute/art">art manual</a> for details.</p>
<p><code class="program">se create-draft</code> already 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.</p>
<p>The source images for both the cover and the titlepage are kept in <code class="path">./images/</code>. 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. <code class="program">se build-images</code> does just that.</p><code class="terminal"><span>se build-images .</span></code>
<p><code class="program">se build-images</code> takes both <code class="path">./images/cover.svg</code> and <code class="path">./images/titlepage.svg</code>, converts text to paths, and embeds the cover jpg. The output goes to <code class="path">./src/epub/images/</code>.</p>
<p>Once we built the images successfully, perform a commit.</p><code class="terminal"><span>git add -A</span> <span>git commit -m "Add cover and titlepage images"</span></code>
<p><code class="bash"><b>se</b> create-draft</code> already 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.</p>
<p>The source images for both the cover and the titlepage are kept in <code class="path">./images/</code>. 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. <code class="bash"><b>se</b> build-images</code> does just that.</p><code class="terminal"><span><b>se</b> build-images <u>.</u></span></code>
<p><code class="bash"><b>se</b> build-images</code> takes both <code class="path">./images/cover.svg</code> and <code class="path">./images/titlepage.svg</code>, converts text to paths, and embeds the cover jpg. The output goes to <code class="path">./src/epub/images/</code>.</p>
<p>Once we built the images successfully, perform a commit.</p><code class="terminal"><span><b>git</b> add -A</span> <span><b>git</b> commit -m <i>"Add cover and titlepage images"</i></span></code>
</li>
<li>
<h2>Complete content.opf</h2>
<p><code class="path">content.opf</code> is 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.</p>
<p>The <code class="path">content.opf</code> is standardized. Please <a href="/contribute/metadata">see our extensive Metadata Manual</a> for details on how to fill out <code class="path">content.opf</code>.</p>
<p>As you complete the metadata, you’ll have to order the spine and the manifest in this file. Fortunately, Standard Ebooks tools for that too: <code class="program">se print-manifest</code> and <code class="program">se print-spine</code>. Run these on our source directory and, as you can guess, they’ll print out the <code class="html">&lt;manifest&gt;</code> and <code class="html">&lt;spine&gt;</code> tags for this work.</p>
<p>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 <code class="path">.DS_Store</code> files. Before continuing, you should <a href="https://duckduckgo.com/?q=mac+alternative+file+manager">find a better file manager program</a>, then delete all of that litter with the following command. Otherwise, <code class="program">se print-manifest</code> and <code class="program">se print-spine</code> will include that litter in its output and your epub won’t be valid.</p>
<code class="terminal"><span>find . -name ".DS_Store" -type f -delete</span></code>
<p>Since this is the first time we’re editing <code class="path">content.opf</code>, we’re OK with replacing both the manifest and spine tags with a guess at the correct contents. We can do this using the <code class="program">--in-place</code> option. If we have to update the manifest or spine later, we can omit the option to print to standard output instead of altering <code class="path">content.opf</code> directly.</p>
<p>As you complete the metadata, you’ll have to order the spine and the manifest in this file. Fortunately, Standard Ebooks tools for that too: <code class="bash"><b>se</b> print-manifest</code> and <code class="bash"><b>se</b> print-spine</code>. Run these on our source directory and, as you can guess, they’ll print out the <code class="html"><span class="p">&lt;</span><span class="nt">manifest</span><span class="p">&gt;</span></code> and <code class="html"><span class="p">&lt;</span><span class="nt">spine</span><span class="p">&gt;</span></code> elements for this work.</p>
<p>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 <code class="path">.DS_Store</code> files. Before continuing, you should <a href="https://duckduckgo.com/?q=mac+alternative+file+manager">find a better file manager program</a>, then delete all of that litter with the following command. Otherwise, <code class="bash"><b>se</b> print-manifest</code> and <code class="bash"><b>se</b> print-spine</code> will include that litter in its output and your epub won’t be valid.</p>
<code class="terminal"><span><b>find</b> <u>.</u> -name <i>".DS_Store"</i> -type f -delete</span></code>
<p>Since this is the first time we’re editing <code class="path">content.opf</code>, we’re OK with replacing both the manifest and spine elements with a guess at the correct contents. We can do this using the <code class="bash">--in-place</code> option. If we have to update the manifest or spine later, we can omit the option to print to standard output instead of altering <code class="path">content.opf</code> directly.</p>
<code class="terminal">
<span>se print-manifest --in-place .</span>
<span>se print-spine --in-place .</span>
<span><b>se</b> print-manifest --in-place <u>.</u></span>
<span><b>se</b> print-spine --in-place <u>.</u></span>
</code>
<p>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!</p><code class="terminal"><span>git add -A</span> <span>git commit -m "Complete content.opf"</span></code>
<p>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!</p><code class="terminal"><span><b>git</b> add -A</span> <span><b>git</b> commit -m <i>"Complete content.opf"</i></span></code>
</li>
<li>
<h2>Complete the table of contents</h2>
<p>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.</p>
<p>Once you’ve completed the <code class="html">&lt;spine&gt;</code> element in <code class="path">content.opf</code>, you can use <code class="program">se print-toc</code> to generate a table of contents for this ebook. Since this is the first time we’re generating a ToC for this ebook, use the <code class="program">--in-place</code> flag to replace the template ToC file with the generated ToC.</p>
<code class="terminal raw"><span>se print-toc --in-place .</span></code>
<p>Review the generated ToC in <code class="path">./src/epub/toc.xhtml</code> to make sure <code class="program">se print-toc</code> did the right thing. <code class="program">se print-toc</code> is 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 <code class="program">se print-toc</code>, but with your HTML code—be careful! You may have to make changes by hand for complex or unusual books.</p>
<p>Once you’ve completed the <code class="html"><span class="p">&lt;</span><span class="nt">spine</span><span class="p">&gt;</span></code> element in <code class="path">content.opf</code>, you can use <code class="bash"><b>se</b> print-toc</code> to generate a table of contents for this ebook. Since this is the first time we’re generating a ToC for this ebook, use the <code class="bash">--in-place</code> flag to replace the template ToC file with the generated ToC.</p>
<code class="terminal raw"><span><b>se</b> print-toc --in-place <u>.</u></span></code>
<p>Review the generated ToC in <code class="path">./src/epub/toc.xhtml</code> to make sure <code class="bash"><b>se</b> print-toc</code> did the right thing. <code class="bash"><b>se</b> print-toc</code> is 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 <code class="bash"><b>se</b> print-toc</code>, but with your HTML code—be careful! You may have to make changes by hand for complex or unusual books.</p>
<p>Once you’re done, commit:</p>
<code class="terminal"><span>git add -A</span> <span>git commit -m "Add ToC"</span></code>
<code class="terminal"><span><b>git</b> add -A</span> <span><b>git</b> commit -m <i>"Add ToC"</i></span></code>
</li>
<li>
<h2>Complete the colophon</h2>
<p><code class="program">se create-draft</code> put a skeleton <code class="path">colophon.xhtml</code> file in the <code class="path">./src/epub/text/</code> 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).</p>
<p><code class="bash"><b>se</b> create-draft</code> put a skeleton <code class="path">colophon.xhtml</code> file in the <code class="path">./src/epub/text/</code> 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).</p>
<p>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.</p>
<p>The release and updated dates should be the same for the first release, and they should match the dates in <code class="path">content.opf</code>. For now, leave them unchanged, as <code class="program">se prepare-release</code will automatically fill them in for you as we’ll describe later in this guide.</p><code class="terminal"><span>git add -A</span> <span>git commit -m "Complete the colophon"</span></code>
<p>The release and updated dates should be the same for the first release, and they should match the dates in <code class="path">content.opf</code>. For now, leave them unchanged, as <code class="bash"><b>se</b> prepare-release</code> will automatically fill them in for you as we’ll describe later in this guide.</p><code class="terminal"><span><b>git</b> add -A</span> <span><b>git</b> commit -m <i>"Complete the colophon"</i></span></code>
</li>
<li>
<h2>Complete the imprint</h2>
@ -371,15 +380,15 @@ require_once('Core.php');
<li>
<h2>Clean and lint before building</h2>
<p>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.</p>
<p>First, run <code class="program">se clean</code> one more time to both clean up the source files, and to alert you if there are XHTML parsing errors. Even though we ran <code class="program">se clean</code> before, it’s likely that in the course of production the ebook got in to less-than-perfect markup formatting. Remember you can run <code class="program">se clean</code> as many times as you want—it should always produce the same output.</p>
<code class="terminal"><span>se clean .</span></code>
<p>Now, run <code class="program">se lint</code>. If your ebook has any problems, you’ll see some output listing them. If everything’s OK, then <code class="program">se lint</code> will complete silently.</p>
<code class="terminal"><span>se lint .</span></code>
<p>First, run <code class="bash"><b>se</b> clean</code> one more time to both clean up the source files, and to alert you if there are XHTML parsing errors. Even though we ran <code class="bash"><b>se</b> clean</code> before, it’s likely that in the course of production the ebook got in to less-than-perfect markup formatting. Remember you can run <code class="bash"><b>se</b> clean</code> as many times as you want—it should always produce the same output.</p>
<code class="terminal"><span><b>se</b> clean <u>.</u></span></code>
<p>Now, run <code class="bash"><b>se</b> lint</code>. If your ebook has any problems, you’ll see some output listing them. If everything’s OK, then <code class="bash"><b>se</b> lint</code> will complete silently.</p>
<code class="terminal"><span><b>se</b> lint <u>.</u></span></code>
</li>
<li>
<h2>Build and proofread, proofread, proofread!</h2>
<p>At this point we’re just about ready to build our proofreading draft! <code class="program">se build</code> does this for us. We’ll run it with the <code class="program">--check</code> flag to make sure the epub we produced is valid, and with the <code class="program">--kindle</code> and <code class="program">--kobo</code> flag to build a file for Kindles and Kobos too. If you won’t be using a Kindle or Kobo, you can omit those flags.</p>
<code class="terminal"><span>se build --output-dir=$HOME/dist/ --kindle --kobo --check .</span></code>
<p>At this point we’re just about ready to build our proofreading draft! <code class="bash"><b>se</b> build</code> does this for us. We’ll run it with the <code class="bash">--check</code> flag to make sure the epub we produced is valid, and with the <code class="bash">--kindle</code> and <code class="bash">--kobo</code> flag to build a file for Kindles and Kobos too. If you won’t be using a Kindle or Kobo, you can omit those flags.</p>
<code class="terminal"><span><b>se</b> build --output-dir=$HOME/dist/ --kindle --kobo --check <u>.</u></span></code>
<p>If there are no errors, we’ll see five files in the brand-new <code class="path">~/dist/</code> folder in our home directory:</p>
<ul>
<li>
@ -398,7 +407,7 @@ require_once('Core.php');
<p><code class="path">thumbnail_xxxx_EBOK_portrait.jpg</code> is 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 images in side-loaded files; contact Amazon to complain.</p>
</li>
</ul>
<p>This is the step where you read the ebook and make adjustments to the text so that it conforms to our <a href="/contribute/typography">typography manual</a>.</p>
<p>This is the step where you read the ebook and make adjustments to the text so that it conforms to our <a href="/manual/latest/8-typography">typography manual</a>.</p>
<p>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:</p>
<ul>
<li>
@ -408,27 +417,34 @@ require_once('Core.php');
<p><a href="https://archive.org/">The Internet Archive</a> is another collection of scans of public domain books.</p>
</li>
</ul>
<p>If you end up using scans from one of these sources, you <em>must</em> mention it in the ebook’s colophon and as a <code class="html">&lt;dc:source&gt;</code> item in <code class="path">content.opf</code>.</p>
<p>If you end up using scans from one of these sources, you <em>must</em> mention it in the ebook’s colophon and as a <code class="html"><span class="p">&lt;</span><span class="nt">dc:source</span><span class="p">&gt;</span></code> item in <code class="path">content.opf</code>.</p>
<p>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. <a href="/contribute/report-errors-upstream">Instructions for how to do so are here.</a></p>
</li>
<li>
<h2>Initial publication</h2>
<p>Now that we’ve proofread the work and corrected any errors we’ve found, we’re ready to release the finished ebook!</p>
<p>It’s a good idea to run <code class="program">se typogrify</code> and <code class="program">se clean</code> one more time before releasing. Make sure to review the changes with <code class="program">git difftool</code> before accepting them—<code class="program">se typogrify</code> is usually right, but not always!</p>
<p>It’s a good idea to run <code class="bash"><b>se</b> typogrify</code> and <code class="bash"><b>se</b> clean</code> one more time before releasing. Make sure to review the changes with <code class="bash"><b>git</b> difftool</code> before accepting them—<code class="bash"><b>se</b> typogrify</code> is usually right, but not always!</p>
<ul>
<li>
<p><b>If you’re submitting your ebook to Standard Ebooks for review:</b></p>
<p><em>Don’t run <code class="program">se prepare-release</code> on an ebook you’re submitting for review!</em></p>
<p><em>Don’t run <code class="bash"><b>se</b> prepare-release</code> on an ebook you’re submitting for review!</em></p>
<p>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.</p>
</li>
<li>
<p><b>If you’re producing this ebook for yourself, not for release at Standard Ebooks:</b></p>
<p>Complete the initial publication by adding a release date, modification date, and final word count to <code class="path">content.opf</code> and <code class="path">colophon.xhtml</code>. <code class="program">se prepare-release</code> does all of that for us.</p>
<code class="terminal"><span>se prepare-release .</span></code>
<p>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.)</p><code class="terminal"><span>git add -A</span> <span>git commit -m "Initial publication"</span></code>
<p>Complete the initial publication by adding a release date, modification date, and final word count to <code class="path">content.opf</code> and <code class="path">colophon.xhtml</code>. <code class="bash"><b>se</b> prepare-release</code> does all of that for us.</p>
<code class="terminal"><span><b>se</b> prepare-release <u>.</u></span></code>
<p>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.)</p>
<code class="terminal">
<span><b>git</b> add -A</span>
<span><b>git</b> commit -m <i>"Initial publication"</i></span>
</code>
</li>
</ul>
<p>Finally, build everything again.</p><code class="terminal"><span>se build --output-dir=$HOME/dist/ --kindle --kobo --check .</span></code>
<p>Finally, build everything again.</p>
<code class="terminal">
<span><b>se</b> build --output-dir=$HOME/dist/ --kindle --kobo --check <u>.</u></span>
</code>
<p>If the build completed successfully, congratulations! You’ve just finished producing a Standard Ebook!</p>
</li>
</ol>

836
www/contribute/semantics.php
View file

@ -1,836 +0,0 @@
<?
require_once('Core.php');
?><?= Template::Header(['title' => 'Structure and Semantics Manual', 'js' => true, 'highlight' => 'contribute', 'description' => 'The Standard Ebooks Structure and Semantics Manual, containing details on semantic patterns used in ebook production.']) ?>
<main>
<article>
<h1>Structure and Semantics Manual</h1>
<aside class="alert">
<p>Standard Ebooks is a brand-new project&mdash;this manual is a pre-alpha, and much of it is incomplete. If you have a question, need clarification, or run in to an issue not yet covered here, please <a href="https://groups.google.com/forum/#!forum/standardebooks">contact us</a> so we can update this manual.</p>
</aside>
<section id="general">
<h2>General do’s and don’ts</h2>
<ul>
<li>
<p>Don’t wrap source code to a certain column width. This makes it difficult to search through source code for a particular sentence, because a line break could be anywhere. Instead, use the <code class="program">clean</code> tool in the <a href="https://github.com/standardebooks/tools">Standard Ebooks toolset</a> to format <abbr class="initialism">XHTML</abbr> source code, and the word wrap feature in your text editor to make long paragraphs readable in the source code.</p>
</li>
<li><p>You have the full vocabulary of <abbr class="initialism">HTML5</abbr> at your disposal, so use semantically-appropriate elements whenever possible. Don’t settle for a <code class="html">&lt;div&gt;</code> when a <code class="html">&lt;blockquote&gt;</code> or <code class="html">&lt;section&gt;</code> would be more descriptive.</p>
<figure class="text">
<p class="wrong">&lt;div class="quotation"&gt;</p>
<p class="corrected">&lt;blockquote&gt;</p>
</figure>
<li><p>Don’t style elements with inline <abbr class="initialism">CSS</abbr>. Prefer clever <abbr class="initialism">CSS</abbr> selectors first, then prefer <abbr class="initialism">CSS</abbr> classes.</p></li>
<li><p>When styling with <abbr class="initialism">CSS</abbr> classes, use semantic class names. Name classes based on what they’re styling, not based on a description of how their style looks.</p>
<figure class="text">
<p class="wrong">&lt;div class="small-caps"&gt;</p>
<p class="corrected">&lt;blockquote class="inscription"&gt;</p>
</figure>
</li>
<li>
<p>Don’t use <code class="html">&lt;pre&gt;</code> elements to format text requiring tricky spacing, like poetry. There should never be a <code class="html">&lt;pre&gt;</code> element in a Standard Ebook. See the <a href="#poetry">poetry section</a> for patterns to use to format poetry. Anything can be formatted with <abbr class="initialism">CSS</abbr> if you give it a little thought!</p>
</li>
</ul>
</section>
<section id="semantics-inflection">
<h2>Semantic inflection</h2>
<p>The epub spec allows for <a href="http://www.idpf.org/accessibility/guidelines/content/semantics/epub-type.php">semantic inflection</a>, which is a way of adding pertinent semantic metadata to certain elements. For example, you may want to convey that the contents of a certain <code class="html">&lt;section&gt;</code> are actually a part of a chapter. You would do that by using the <code class="html">epub:type</code> attribute:</p>
<figure>
<code class="html">&lt;section epub:type="chapter"&gt;...&lt;/section&gt;</code>
</figure>
<p>The epub spec includes a <a href="http://www.idpf.org/epub/vocab/structure/">list of supported keywords</a> that you can use in the <code class="html">epub:type</code> attribute. Many of these keywords apply to content divisions, like chapter breaks, prefaces, introductions, and so on.</p>
<p>An additional spec, the sexily-named <a href="http://www.daisy.org/z3998/2012/vocab/structure/">z39.98-2012 Structural Semantics vocabulary</a>, gives us a more robust vocabulary for adding semantic inflection. This vocabulary includes ways of marking fiction vs. non-fiction, letters, poetry, and so on. All Standard Ebooks include a reference to this vocabulary by default, so you should use it if the regular epub vocabulary isn’t enough.</p>
<p>Finally, Standard Ebooks <a href="/vocab/1.0">has its own vocabulary</a> to add even more finely grained semantics. For example, names of ships are italicized with the <code class="html">&lt;i&gt;</code> element. But to convey that the otherwise-meaningless <code class="html">&lt;i&gt;</code> element contains the name of a ship, we would add the Standard Ebooks semantic inflection of <code class="html">se:name.vessel.ship</code>:</p>
<figure>
<code class="html">They set sail on the &lt;abbr class="initialism"&gt;HMS&lt;/abbr&gt; &lt;i epub:type="se:name.vessel.ship"&gt;Bounty&lt;/i&gt;.</code>
</figure>
<p>In a perfect world, Standard Ebooks wouldn’t have to maintain its own list of semantic vocabulary. We’re actively looking for a suitable replacement&mdash;if you have a suggestion, <a href="/contribute/">get in touch</a>!</p>
<h3>Semantic inflection in Standard Ebooks</h3>
<p>Part of the Standard Ebooks mission is to add as much semantic information to ebooks as possible. To that end, use semantic inflection liberally and in detail. Since we have so many vocabulary options to use, use them in this order of preference:</p>
<ol>
<li>
<p><a href="http://www.idpf.org/epub/vocab/structure/">The built-in epub vocabulary</a>. If what you’re trying to mark up is here, use this first.</p>
</li>
<li>
<p><a href="http://www.daisy.org/z3998/2012/vocab/structure/">The z3998 vocabulary</a>. If something isn’t included in the regular epub vocabulary, stop here next.</p>
</li>
<li>
<p><a href="/vocab/1.0">The Standard Ebooks vocabulary</a>. If neither the regular epub vocabulary nor the z33998 vocabulary have a keyword you’re looking for, check our own vocabulary. You can also <a href="/contribute/">suggest additions to this vocabulary</a>.</p>
</li>
</ol>
</section>
<section id="style">
<h2>XHTML and CSS code formatting style</h2>
<h3>In XHTML</h3>
<p>The <code class="path">clean</code> tool does a good job of pretty-printing your XHTML according to our requirements, so make sure to run it often. In case you want to review the style requirements, they are:</p>
<ul>
<li><p>Use tabs for indentation.</p></li>
<li><p>Tags whose content is <a href="https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content">phrasing content</a> should be on a single line. So, don’t open a <code class="html">&lt;p&gt;</code> tag, then move to the next line for the tag’s contents; put it all on the same line.</p></li>
<li><p>Attributes should be in alphabetical order.</p></li>
</ul>
<h3>In CSS</h3>
<ul>
<li><p>Use tabs for indentation.</p></li>
<li><p>Always move to a new line for CSS properties. Even if the selector only has one property, don’t put the selector and the property on one line.</p></li>
<li><p>Where possible, properties should be in alphabetical order. (This isn’t always possible if you’re attempting to override a previous style in the same selector; in those cases that’s OK.)</p></li>
</ul>
</section>
<section id="abbreviations">
<h2>Abbreviation semantic patterns</h2>
<ul>
<li>
<p>There are three types of abbreviations:</p>
<p>An acronym is a term made up of initials and pronounced as one word: <abbr class="acronym">NASA</abbr>, <abbr class="acronym">SCUBA</abbr>, <abbr class="acronym">TASER</abbr>.</p>
<p>An initialism is a term made up of initials in which each initial is pronounced separately: <abbr class="initialism">ABC</abbr>, <abbr class="initialism">HTML</abbr>, <abbr class="initialism">CSS</abbr>.</p>
<p>A contraction is an abbreviation of a longer word: Mr., Mrs., lbs.</p>
</li>
<li>
<p>All abbreviations must be wrapped in an <code class="html">&lt;abbr&gt;</code> element.</p>
</li>
<li>
<p>All abbreviations that include periods (for example, <a href="/contribute/typography#latinisms">Latinisms</a>) <em>and</em> terminate a clause must include the “eoc” (end-of-clause) class in the <code class="html">&lt;abbr&gt;</code> element. Since a clause ending in an abbreviation omits the trailing period, it’s useful for us to know when such an abbreviation marks the end of a clause.</p>
<table>
<thead>
<tr>
<td>Result</td>
<td>Code</td>
</tr>
</thead>
<tbody>
<tr>
<td>
He wanted to meet at 6:40&nbsp;
<abbr class="time eoc">p.m.</abbr> I was excited to see him!</td>
<td>
<code class="html full">He wanted to meet at 6:40<span class="utf">nbsp</span>&lt;abbr class="time eoc"&gt;p.m.&lt;/abbr&gt; I was excited to see him!</code>
</td>
</tr>
</tbody>
</table>
</li>
<li>
<p>Certain abbreviations should be marked up with a semantic class:</p>
<ul>
<li>
<h3>Acronyms</h3>
<p>Any acronym (defined above) that doesn’t fit in the categories below.</p>
<figure><code class="html">&lt;abbr class="acronym"&gt;NASA&lt;/abbr&gt; received less funding than usual this year.</code></figure>
</li>
<li>
<h3>Initialisms</h3>
<p>Any initialism (defined above) that doesn’t fit in the categories below.</p>
<figure><code class="html">There are harder languages than &lt;abbr class="initialism"&gt;HTML&lt;/abbr&gt;.</code></figure>
</li>
<li>
<h3>Abbreviated compass directions</h3>
<p>For example: <abbr>N.</abbr>, <abbr>S.</abbr>, <abbr>S.W.</abbr></p>
<figure><code class="html">He traveled &lt;abbr class="compass"&gt;N. W.&lt;/abbr&gt;, then &lt;abbr class="compass eoc"&gt;E. S. E.&lt;/abbr&gt;</code></figure>
<p>This regex is helpful in finding compass directions: <code class="regex">[NESW]\.([NESW]\.)*?</code></p>
</li>
<li>
<h3>Compounds</h3>
<p>Molecular compounds.</p>
<figure><code class="html">&lt;abbr class="compound"&gt;H&lt;sub&gt;2&lt;/sub&gt;O&lt;/abbr&gt;</code></figure>
</li>
<li>
<h3>Academic degrees</h3>
<p>Academic degrees, <em>except</em> ones that, like PhD, include a lowercase letter: BA, BD, BFA, BM, BS, DB, DD, DDS, DO, DVM, JD, LHD, LLB, LLD, LLM, MA, MBA, MD, MFA, MS, MSN.</p>
<figure><code class="html">Judith Douglas, &lt;abbr class="degree"&gt;DDS&lt;/abbr&gt;.</code></figure>
</li>
<li>
<h3>Eras</h3>
<p>The abbreviations
<abbr class="era">AD</abbr>,
<abbr class="era">BC</abbr>,
<abbr class="era">CE</abbr>,
<abbr class="era">BCE</abbr>.</p>
<figure><code class="html">Julius Caesar was born around 100 &lt;abbr class="era"&gt;BC&lt;/abbr&gt;.</code></figure>
</li>
<li>
<h3>Initialized names</h3>
<p>A person’s initials, either first name, last name, or both.</p>
<figure><code class="html">&lt;abbr class="name"&gt;J. P.&lt;/abbr&gt; Morgan was a wealthy man.</code></figure>
</li>
<li>
<h3>State names and postal codes</h3>
<p>Abbreviated state names and postal codes: NY, Washington DC.</p>
<figure><code class="html">Washington &lt;abbr class="postal"&gt;DC&lt;/abbr&gt;</code></figure>
</li>
<li>
<h3>Temperatures</h3>
<p>Abbreviated temperature scales: F, C. Also see the <a href="/contribute/typography#temperatures">typography manual</a>.</p>
<figure><code class="html">It was 5°<span class="utf">hairsp</span>&lt;abbr class="temperature"&gt;C&lt;/abbr&gt; last night.</code></figure>
</li>
<li>
<h3>Times</h3>
<p>Time-related Latinisms: a.m., p.m. Also see the <a href="/contribute/typography#times">typography manual</a>.</p>
<figure><code class="html">5<span class="utf">nbsp</span>&lt;abbr class="time"&gt;p.m.&lt;/abbr&gt;</code></figure>
</li>
<li>
<h3>Timezones</h3>
<p>PST, CST, EST, etc.</p>
<figure><code class="html">5<span class="utf">nbsp</span>&lt;abbr class="time"&gt;p.m.&lt;/abbr&gt; &lt;abbr class="timezone"&gt;PST&lt;/abbr&gt;</code></figure>
</li>
</ul>
</li>
</ul>
</section>
<section id="titles">
<h2>The &lt;title&gt; tag</h2>
<p>The <code class="html">&lt;title&gt;</code> tag should contain an appropriate description of the local file only.</p>
<h3>Titles for files that are an individual chapter</h3>
<p>In most ebook productions, each chapter will be its own file. In that case, follow these rules:</p>
<ul>
<li><p>Don’t include the book title in individual chapter <code class="html">&lt;title&gt;</code> tags.</p></li>
<li><p>Convert chapter numbers that are in Roman numerals to decimal numbers:</p>
<code class="html full">&lt;title&gt;Chapter 10&lt;/title&gt;</code>
</li>
<li><p>If a chapter has a subtitle, add a colon after the chapter number and place the subtitle after that:</p>
<code class="html full">&lt;title&gt;Chapter 10: A Dark and Stormy Night&lt;/title&gt;</code>
</li>
<li><p>Subtitles may often contain subtags, like <code class="html">&lt;i&gt;</code>. Because <code class="html">&lt;title&gt;</code> can’t contain subtags, simply remove them when copying into <code class="html">&lt;title&gt;</code>:</p>
<code class="html full">&lt;title&gt;Chapter 8: Mobilis in Mobili&lt;/title&gt;</code></li>
</ul>
</section>
<section id="ids">
<h2>Ids</h2>
<p>Each <code class="html">&lt;section&gt;</code> should have an <code class="html">id</code> attribute corresponding to a URL-friendly version of the <code class="html">&lt;section&gt;</code>&rsquo;s name. For example:</p>
<code class="html full">&lt;section id="introduction" epub:type="introduction"&gt;
&lt;h2 epub:type="title"&gt;Introduction&lt;/h2&gt;
&lt;!--snip--&gt;
&lt;/section&gt;</code>
<p>Occasionally you might need to give other elements IDs, for example when an endnote references a specific line or paragraph in the work. In these cases, name the IDs by their tag name, then a dash, then a number representing the tag’s sequential numerical order from the beginning of the containing document.</p>
<code class="html full">&lt;section id="introduction" epub:type="introduction"&gt;
&lt;h2 epub:type="title"&gt;Introduction&lt;/h2&gt;
&lt;p&gt;Some text...&lt;/p&gt;
&lt;!--snip 10 more &lt;p&gt; tags--&gt;
&lt;p id="p-12"&gt;Some text...&lt;/p&gt;
&lt;/section&gt;</code>
</section>
<section id="lists">
<h2>Ordered/numbered and unordered lists</h2>
<p>All <code class="html">&lt;li&gt;</code> children of <code class="html">&lt;ol&gt;</code> and <code class="html">&lt;ul&gt;</code> tags <em>must</em> have at least one direct child block-level tag. This is usually a <code class="html">&lt;p&gt;</code> tag. (But not necessarily; for example, a <code class="html">&lt;blockquote&gt;</code> tag might also be appropriate.)</p>
<code class="html full">&lt;ul&gt;
&lt;li&gt;
&lt;p&gt;&lt;b&gt;Miss Oranthy Bluggage&lt;/b&gt;, the accomplished Strong-Minded Lecturer, will deliver her famous Lecture on “&lt;b&gt;Woman and Her Position&lt;/b&gt;,” at Pickwick Hall, next Saturday Evening, after the usual performances.&lt;/p&gt;
&lt;/li&gt;
&lt;/ul&gt;</code>
</section>
<section id="blockquotes">
<h2>Blockquotes</h2>
<p>In most prose works, we generally want to offset long quotations in the <code class="html">&lt;blockquote&gt;</code> element. However, we want to be able to distinguish when a quotation is from a real-life source (like a quotation from a Shakespeare play), and when the quotation is fictional within the context of the work. To make this distinction, we assume that the <code class="html">&lt;blockquote&gt;</code> inherits the <code class="html">z3998:fiction</code> or <code class="html">z3998:non-fiction</code> semantic inflection of its parent. Thus, if the <code class="html">&lt;blockquote&gt;</code> contents differ from that inherited semantic inflection, we specify whether it’s <code class="html">z3998:fiction</code> or <code class="html">z3998:non-fiction</code> in the blockquote element itself.</p>
<p>For example, if a <code class="html">&lt;blockquote&gt;</code> doesn’t have semantic inflection specified, and it’s within a <code class="html">&lt;section epub:type="z3998:fiction"&gt;</code> parent, then the <code class="html">&lt;blockquote&gt;</code> is <em>also</em> fictional within the context of the work.</p>
<p>In this first example from <i><a href="/ebooks/bram-stoker/dracula">Dracula</a></i>, we have a fictional character quoting a real-life source. Since <i>Dracula</i> is fiction but the quotation source <a href="https://en.wikipedia.org/wiki/Lenore_%28ballad%29">exists in the real world</a>, we include the <code class="html">z3998:non-fiction</code> semantic inflection:</p>
<code class="html full">&lt;section epub:type="chapter z3998:fiction"&gt;
&lt;p&gt;One of my companions whispered to another the line from Burger’s “Lenore”:―&lt;/p&gt;
&lt;blockquote epub:type="z3998:non-fiction"&gt;
&lt;p&gt;“&lt;span xml:lang="de"&gt;Denn die Todten reiten schnell&lt;/span&gt;”⁠—&lt;br/&gt;
(“For the dead travel fast.”)&lt;/p&gt;
&lt;/blockquote&gt;
&lt;/section&gt;</code>
<p>In this second example from <i><a href="/ebooks/jules-verne/twenty-thousand-leagues-under-the-seas/f-p-walter">Twenty Thousand Leagues Under the Seas</a></i>, a fictional character quotes another fictional character. We still use the <code class="html">&lt;blockquote&gt;</code> element, but since the work itself is fiction, the <code class="html">&lt;blockquote&gt;</code> “inherits” the semantic inflection of <code class="html">z3998:fiction</code>:</p>
<code class="html full">&lt;section epub:type="chapter z3998:fiction"&gt;
&lt;p&gt;Every morning, it was repeated under the same circumstances. It ran like this:&lt;/p&gt;
&lt;blockquote xml:lang="x-nemo"&gt;
&lt;p&gt;“Nautron respoc lorni virch.”&lt;/p&gt;
&lt;/blockquote&gt;
&lt;/section&gt;</code>
</section>
<section id="halftitlepages">
<h2>Half title pages</h2>
<p>When a work contains frontmatter like an epigraph or introduction, a half title page is required before the body matter begins.</p>
<h3>Half title pages without subtitles</h3>
<code class="html full">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;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: https://standardebooks.org/vocab/1.0" xml:lang="en-GB"&gt;
&lt;head&gt;
&lt;title&gt;Half Title&lt;/title&gt;
&lt;link href="../css/core.css" rel="stylesheet" type="text/css"/&gt;
&lt;link href="../css/local.css" rel="stylesheet" type="text/css"/&gt;
&lt;/head&gt;
&lt;body epub:type="frontmatter"&gt;
&lt;section id="halftitlepage" epub:type="halftitlepage"&gt;
&lt;h1 epub:type="fulltitle"&gt;Don Quixote&lt;/h1&gt;
&lt;/section&gt;
&lt;/body&gt;
&lt;/html&gt;</code>
<h3>Half title pages with subtitles</h3>
<code class="css full">section[epub|type~="halftitlepage"] span[epub|type~="subtitle"]{
display: block;
font-size: .75em;
font-weight: normal;
}</code>
<code class="html full">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;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: https://standardebooks.org/vocab/1.0" xml:lang="en-GB"&gt;
&lt;head&gt;
&lt;title&gt;Half Title&lt;/title&gt;
&lt;link href="../css/core.css" rel="stylesheet" type="text/css"/&gt;
&lt;link href="../css/local.css" rel="stylesheet" type="text/css"/&gt;
&lt;/head&gt;
&lt;body epub:type="frontmatter"&gt;
&lt;section id="halftitlepage" epub:type="halftitlepage"&gt;
&lt;h1 epub:type="fulltitle"&gt;
&lt;span epub:type="title"&gt;The Book of Wonder&lt;/span&gt;
&lt;span epub:type="subtitle"&gt;A Chronicle of Little Adventures at the Edge of the World&lt;/span&gt;
&lt;/h1&gt;
&lt;/section&gt;
&lt;/body&gt;
&lt;/html&gt;</code>
</section>
<section id="endnotes">
<h2>Footnotes and endnotes</h2>
<p>Since there’s no concept of a “page” in an ebook, the concept of “footnotes” isn’t very useful. (Where would a footnote go if there’s no bottom of the page?)</p>
<p>Modern ereading systems do, however, offer popup notes. Our task is to combine all footnotes present in a source text into a single endnotes file that provides popup notes to supported readers, and clearly listed notes for other readers.</p>
<p>Endnotes must be numbers that are sequential throughout the entire text. Since many books just used “*” to denote a footnote, when converting to endnotes we have to assign those a number.</p>
<h3>Linking to endnotes</h3>
<p>In the body text, you refer to an endnote using this pattern:</p>
<code class="html full">&lt;p&gt;This is some text followed by a reference to an endnote.&lt;a href="endnotes.xhtml#note-1" id="noteref-1" epub:type="noteref"&gt;1&lt;/a&gt;&lt;/p&gt;</code>
<ul>
<li><p>The <code class="html">id</code> attribute is always “noteref-N” where N is the number of the endnote.</p></li>
<li><p>The <code class="html">epub:type</code> attribute is set to “noteref”.</p></li>
<li><p>The endnote goes after ending punctuation.</p></li>
</ul>
<h3>The endnotes file</h3>
<p>The endnotes file is called <code class="path">endnotes.xhtml</code> and looks like this:</p>
<code class="html full">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;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: https://standardebooks.org/vocab/1.0" xml:lang="en-GB"&gt;
&lt;head&gt;
&lt;title&gt;Endnotes&lt;/title&gt;
&lt;link href="../css/core.css" rel="stylesheet" type="text/css"/&gt;
&lt;link href="../css/local.css" rel="stylesheet" type="text/css"/&gt;
&lt;/head&gt;
&lt;body epub:type="backmatter z3998:fiction"&gt;
&lt;section id="endnotes" epub:type="endnotes"&gt;
&lt;h2 epub:type="title"&gt;Endnotes&lt;/h2&gt;
&lt;ol&gt;
&lt;li id="note-1" epub:type="endnote"&gt;
&lt;p&gt;The first endnote goes here.&lt;/p&gt;
&lt;p&gt;Here's another line for the first endnote. &lt;a href="chapter-1.xhtml#noteref-1" epub:type="backlink"&gt;↩&lt;/a&gt;&lt;/p&gt;
&lt;/li&gt;
&lt;li id="note-2" epub:type="endnote"&gt;
&lt;p&gt;The second endnote goes here. &lt;a href="chapter-1.xhtml#noteref-2" epub:type="backlink"&gt;↩&lt;/a&gt;&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;/section&gt;
&lt;/body&gt;
&lt;/html&gt;</code>
<h3>An endnote dissected</h3>
<ul>
<li><p>Each individual endnote is a <code class="html">&lt;li&gt;</code> element containing one or more <code class="html">&lt;p&gt;</code> elements.</p></li>
<li><p>Each <code class="html">&lt;li&gt;</code> requires the following attributes:</p>
<ul>
<li><p><code class="html">id</code> is set to the string “note-” followed by the sequential endnote number, beginning with 1.</p></li>
<li><p><code class="html">epub:type</code> is set to “endnote”.</p></li>
</ul>
<li><p>The <code class="html">href</code> attribute points to the direct anchor reference to the endnote. </p></li>
<li><p>If an endnote contains a citation offset with a dash (for example, “&mdash;Ed.”), separate the citation from the text with a single space and enclose it in the <code class="html">&lt;cite&gt;</code> tag:</p>
<code class="html full">&lt;li id="note-1" epub:type="endnote"&gt;
&lt;p&gt;Here’s an endnote. &lt;cite&gt;&mdash;&lt;abbr class="eoc"&gt;Ed.&lt;/abbr&gt;&lt;/cite&gt; &lt;a href="chapter-1.xhtml#note-1" epub:type="backlink"&gt;↩&lt;/a&gt;&lt;/p&gt;
&lt;/li&gt;</code>
</li>
<li><p>The final <code class="html">&lt;p&gt;</code> element in an endnote contains a link back to the referring anchor. Don’t just point it to the file, make sure it points to the exact link that we came from. For example, <code class="path">chapter-1.xhtml#note-1</code>, <em>not</em> <code class="path">chapter-1.xhtml</code>. If the link is the last element in a longer <code class="html">&lt;p&gt;</code> tag, it must be preceded by one space character; if it is the only child of a <code class="html">&lt;p&gt;</code> tag (for example if the previous text was a <code class="html">&lt;blockquote&gt;</code>) then it can be on its own line. It must have the <code class="html">epub:type</code> set to <code class="html">backlink</code>. The text of the link is always the “↩” character.</p></li>
</ul>
</section>
<section id="thought-and-section-breaks">
<h2>Thought and section breaks</h2>
<p>In printed material, thought and section breaks are typically denoted with a large space between paragraphs, or by a symbol like “* * *”. In Standard Ebooks, use the <code class="html">&lt;hr/&gt;</code> element to denote thought and section breaks.</p>
</section>
<section id="chapter-headers">
<h2>Section header semantic patterns</h2>
<p>There’s a lot of ways authors choose to format chapter headers. Below are patterns for all of the types of chapter headers we’ve encountered so far. If nothing in this list fits the book you’re producing, <a href="/contribute/">contact us</a> and we’ll work on a new standard.</p>
<h3>General outline</h3>
<ul>
<li><p>The title of the book is an implied <code class="html">&lt;h1&gt;</code> element. Therefore, all chapters titles are <code class="html">&lt;h2&gt;</code> elements or lower.</p></li>
<li><p>It’s extremely rare to go down to <code class="html">&lt;h3&gt;</code> and below, but you may do so if, for example, the chapter is part of a volume whose title would occupy the <code class="html">&lt;h2&gt;</code> level. Otherwise, if you feel the need to use <code class="html">&lt;h3&gt;</code>, ask yourself if the header is a structural division of the document. For example, in a work of fiction where a fictional newspaper clipping is presented, the headline <em>would not</em> be set in an <code class="html">&lt;h3&gt;</code> element, because the clipping is part of the body text, not a structural division of the book.</p></li>
</ul>
<h3>Sections without titles</h3>
<code class="html full">&lt;h2 epub:type="title z3998:roman"&gt;XI&lt;/h2&gt;</code>
<h3>Sections with titles but no chapter numbers</h3>
<code class="html full">&lt;h2 epub:type="title"&gt;A Daughter of Albion&lt;/h2&gt;</code>
<h3>Sections with titles and chapter numbers</h3>
<code class="html full">&lt;h2 epub:type="title"&gt;
&lt;span epub:type="z3998:roman"&gt;XI&lt;/span&gt;
&lt;span epub:type="subtitle"&gt;Who Stole the Tarts?&lt;/span&gt;
&lt;/h2&gt;</code>
<code class="css full">span[epub|type~="subtitle"]{
display: block;
font-weight: normal;
}</code>
<h3>Sections with unnumbered titles and subtitles</h3>
<code class="html full">&lt;h2 epub:type="title"&gt;
&lt;span&gt;An Adventure&lt;/span&gt;
&lt;span epub:type="subtitle"&gt;(A Driver’s Story)&lt;/span&gt;
&lt;/h2&gt;</code>
<code class="css full">span[epub|type~="subtitle"]{
display: block;
font-weight: normal;
}</code>
<h3>Sections with bridgeheads</h3>
<p>Note that we include trailing punctuation at the end of the bridgehead. If it’s not present in the source text, add it.</p>
<p>Since the text in the bridgehead is italicized, we include <abbr class="initialism">CSS</abbr> to render actual <code class="html">&lt;i&gt;</code> elements contained in the bridgehead as normal text.</p>
<code class="html full">&lt;header&gt;
&lt;h2 epub:type="title z3998:roman"&gt;I&lt;/h2&gt;
&lt;p epub:type="bridgehead"&gt;Which treats of the character and pursuits of the famous gentleman Don Quixote of La Mancha.&lt;/p&gt;
&lt;/header&gt;</code>
<code class="css full">[epub|type~="bridgehead"]{
display: inline-block;
font-style: italic;
max-width: 60%;
text-align: justify;
text-indent: 0;
}
[epub|type~="bridgehead"] i{
font-style: normal;
}</code>
<h3>Sections with epigraph in section headers</h3>
<!-- Once RMSDK supports display: table; we can do this much nicer combination:
/* All epigraphs */
section > header blockquote[epub|type~="epigraph"],
section[epub|type~="epigraph"] > *{
display: table;
margin: auto;
max-width: 60%;
margin-top: 3em;
}
[epub|type~="epigraph"]{
font-style: italic;
hyphens: none;
}
[epub|type~="epigraph"] i{
font-style: normal;
}
[epub|type~="epigraph"] cite{
margin-top: 1em;
font-style: normal;
font-variant: small-caps;
}
[epub|type~="epigraph"] cite i{
font-style: italic;
}
/* Full-page epigraphs */
@supports(display: flex){
section[epub|type~="epigraph"]{
align-items: center;
box-sizing: border-box;
display: flex;
flex-direction: column;
justify-content: center;
min-height: calc(98vh - 3em);
padding-top: 3em;
}
section[epub|type~="epigraph"] > *{
margin: 0;
}
section[epub|type~="epigraph"] > * + *{
margin-top: 3rem;
}
}
-->
<code class="html full">&lt;header&gt;
&lt;h2 epub:type="title z3998:roman"&gt;XXVIII&lt;/h2&gt;
&lt;blockquote epub:type="epigraph"&gt;
&lt;p&gt;Brief, I pray for you; for you see, ’tis a busy time with me.&lt;/p&gt;
&lt;cite&gt;&lt;i epub:type="se:name.publication.play"&gt;Much Ado About Nothing&lt;/i&gt;&lt;/cite&gt;
&lt;/blockquote&gt;
&lt;/header&gt;</code>
<code class="css full">/* All epigraphs */
[epub|type~="epigraph"]{
font-style: italic;
hyphens: none;
}
[epub|type~="epigraph"] em,
[epub|type~="epigraph"] i{
font-style: normal;
}
[epub|type~="epigraph"] cite{
margin-top: 1em;
font-style: normal;
font-variant: small-caps;
}
[epub|type~="epigraph"] cite i{
font-style: italic;
}
/* End all epigraphs */
/* Epigraphs in section headers */
section &gt; header [epub|type~="epigraph"]{
display: inline-block;
margin: auto;
max-width: 80%;
text-align: left;
}
section &gt; header [epub|type~="epigraph"] + *{
margin-top: 3em;
}
@supports(display: table){
section &gt; header [epub|type~="epigraph"]{
display: table;
}
}
/* End epigraphs in section headers */</code>
</section>
<section id="epigraphs">
<h2>Full-page epigraphs</h2>
<p>Full-page epigraphs have the epigraph centered on the page, for ereaders who support advanced CSS. For all other ereaders, the epigraph is horizontally centered with a small margin above it.</p>
<p>Additional epigraphs on the same page can be represented with additional <code class="html">&lt;blockquote&gt;</code> elements.</p>
<code class="html full">&lt;body epub:type="frontmatter"&gt;
&lt;section id="epigraph" epub:type="epigraph"&gt;
&lt;blockquote&gt;
&lt;p&gt;“I was born in Boston, New England, and owe my first instructions in literature to the free grammar-schools established there. I therefore give one hundred pounds sterling to my executors, to be by them … paid over to the managers or directors of the free schools in my native town of Boston, to be by them … put out to interest, and so continued at interest forever, which interest annually shall be laid out in silver medals, and given as honorary rewards annually by the directors of the said free schools belonging to the said town, in such manner as to the discretion of the selectmen of the said town shall seem meet.”&lt;/p&gt;
&lt;/blockquote&gt;
&lt;/section&gt;
&lt;/body&gt;</code>
<code class="css full">/* All epigraphs */
[epub|type~="epigraph"]{
font-style: italic;
hyphens: none;
}
[epub|type~="epigraph"] em,
[epub|type~="epigraph"] i{
font-style: normal;
}
[epub|type~="epigraph"] cite{
margin-top: 1em;
font-style: normal;
font-variant: small-caps;
}
[epub|type~="epigraph"] cite i{
font-style: italic;
}
/* End all epigraphs */
/* Full-page epigraphs */
section[epub|type~="epigraph"]{
text-align: center;
}
section[epub|type~="epigraph"] &gt; *{
display: inline-block;
margin: auto;
margin-top: 3em;
max-width: 80%;
text-align: left;
}
@supports(display: flex){
section[epub|type~="epigraph"]{
align-items: center;
box-sizing: border-box;
display: flex;
flex-direction: column;
justify-content: center;
min-height: calc(98vh - 3em);
padding-top: 3em;
}
section[epub|type~="epigraph"] &gt; *{
margin: 0;
}
section[epub|type~="epigraph"] &gt; * + *{
margin-top: 3em;
}
}
/* End full-page epigraphs */</code>
</section>
<section id="letters">
<h2>Letters</h2>
<p>Letters require particular attention to styling and semantic tagging. While you are not required to exactly match the formatting of a letter in the source scans, you should make some attempt to create a version in visual sympathy with the source.</p>
<section id="id1">
<h3>General Outline</h3>
<ol>
<li>A letter, or portion of a letter, should be put in a <code class="html">&lt;blockquote&gt;</code> element.</li>
<li>The enclosing blockquote is given the semantic inflection of <code class="html">z3998:letter</code>, that is: <code class="html">&lt;blockquote epub:type="z3998:letter"&gt; ... &lt;/blockquote&gt;</code>.</li>
<li>Parts of a letter prior to the body of the text, for example the address from where it is written and the date, should be enclosed in a <code class="html">&lt;header&gt;</code> element.</li>
<li>The location and date of a letter are given the semantic inflection of <code class="html">se:letter.dateline</code>. The date can be tagged with a <code class="html">&lt;time&gt;</code> tag with a computer-readable date, for example: <code class="html">&lt;time datetime="1863-10-11"&gt;11th of October, 1863&lt;/time&gt;</code>.</li>
<li>The salutation (for example, “Dear Sir", or “My dearest Jane") is given the semantic inflection of <code class="html">z3998:salutation</code>. If the salutation is on a separate line to the body of the letter and a header block already exists, place the salutation within the header.</li>
<li>If the salutation is included within the first line of the letter (for example “My dear Mother, I was so happy to hear from you."), put the salutation inflection in a <code class="html">&lt;span&gt;</code> element, in this example: <code class="html">&lt;span epub:type="z3998:salutation"&gt;Dear Mother&lt;/span&gt;, I was so happy to hear from you.</code></li>
<li>If the name of the recipient of the letter is set out other than within a saluation (for example a letter headed “To: John Smith Esquire"), the name should be given the semantic inflection of <code class="html">z3998:recipient</code>. Sometimes this may occur at the end of a letter, particularly for more formal communications, in which case it should be placed within a footer block (see below).</li>
<li>The valediction and signature and any postscript should be contained in a <code class="html">&lt;footer&gt;</code> element.</li>
<li>The valediction (for example, “Yours Truly" or “With best regards") is given the semantic inflection of <code class="html">z3998:valediction</code>.</li>
<li>The sender’s name is given the semantic inflection of <code class="html">z3998:sender</code>. If the name appears to be a signature to the letter, it should be given a class of “signature". This will eventually be deprecated and is retained for legacy reasons.</li>
<li>Any postscript should also be included within the footer, and given the semantic inflection of <code class="html">z3998:postscript</code>.</li>
<li>If the letter is being read aloud by a character in a work of fiction, then each element and paragraph should begin with quotes, as is usual for the spoken word. If it is not being read aloud, then the quotes are not needed.</li>
</ol>
</section>
<section id="example-letter-1">
<h3>Example Letter 1:</h3>
<p>Here is a simple example, a child's letter drawn from <em>The Enchanted Castle</em> by E. Nesbit:</p>
<code class="html full">&lt;blockquote epub:type="z3998:letter"&gt;
&lt;p epub:type="z3998:salutation"&gt;Dearest Auntie,&lt;/p&gt;
&lt;p&gt;Please may we have some things for a picnic? Gerald will bring them. I would come myself, but I am a little tired. I think I have been growing rather fast.&lt;/p&gt;
&lt;footer&gt;
&lt;p epub:type="z3998:valediction"&gt;Your loving niece,&lt;/p&gt;
&lt;p class="signature" epub:type="z3998:sender"&gt;Mabel&lt;/p&gt;
&lt;p epub:type="z3998:postscript"&gt;P.S.⁠—Lots, please, because some of us are very hungry.&lt;/p&gt;
&lt;/footer&gt;
&lt;/blockquote&gt;</code>
<p>And here is a slightly more complex example, loosely based on a letter from <em>Pride and Prejudice</em> by Jane Austen:</p>
<code class="html full">&lt;blockquote epub:type="z3998:letter"&gt;
&lt;header&gt;
&lt;p epub:type="se:letter.dateline"&gt;Gracechurch-street, &lt;time datetime="08-02"&gt;August 2&lt;/time&gt;.&lt;/p&gt;
&lt;/header&gt;
&lt;p&gt;&lt;span epub:type="z3998:salutation"&gt;My dear Brother&lt;/span&gt;, At last I am able to send you some tidings of my niece, and such as, upon the whole, I hope will give you satisfaction. Soon after you left me on Saturday, I was fortunate enough to find out in what part of London they were. The particulars, I reserve till we meet. It is enough to know they are discovered, I have seen them both⁠—&lt;/p&gt;
&lt;p&gt;I shall write again as soon as anything more is determined on.&lt;/p&gt;
&lt;footer"&gt;
&lt;p epub:type="z3998:valediction"&gt;Yours, etc.&lt;/p&gt;
&lt;p class="signature" epub:type="z3998:sender"&gt;Edward Gardner&lt;/p&gt;
&lt;/footer&gt;
&lt;/blockquote&gt;</code>
<h3>CSS for letters:</h3>
<code class="css full">[epub|type~="z3998:letter"] header{
text-align: right;
}
footer{
margin-top: 1em;
text-align: right;
}
[epub|type~="z3998:salutation"] + p,
[epub|type~="z3998:letter"] header + p{
text-indent: 0;
}
[epub|type~="z3998:sender"],
[epub|type~="z3998:recipient"],
[epub|type~="z3998:salutation"]{
font-variant: small-caps;
}
[epub|type~="z3998:postscript"]{
margin-top: 1em;
text-indent: 0;
text-align: left;
}
.signature{
font-variant: small-caps;
}</code>
</section>
</section>
<section id="poetry">
<h2>Poetry, verse, and song semantic patterns</h2>
<p>Unfortunately there’s no great way to semantically format poetry in <abbr class="initialism">HTML</abbr>. We have to conscript unrelated elements for use in poetry.</p>
<h3>General outline</h3>
<ul>
<li><p>A stanza is represented by a <code class="html">&lt;p&gt;</code> element.</p></li>
<li><p>Each stanza contains <code class="html">&lt;span&gt;</code> elements, each one representing a line in the stanza. Delimiting lines in <code class="html">&lt;span&gt;</code> elements allows us to use <abbr class="initialism">CSS</abbr> to automatically indent long lines that wrap across the page.</p></li>
<li><p>Each line is followed by a <code class="html">&lt;br/&gt;</code> element, <em>except</em> for the last line in a stanza. Since <code class="html">&lt;span&gt;</code> is an inline element, unstyled <code class="html">&lt;span&gt;</code>s don’t have line breaks. Including a <code class="html">&lt;br/&gt;</code> emulates line breaks for readers that for some crazy reason might not support <abbr class="initialism">CSS</abbr>.</p></li>
<li><p>For indented lines, add the <code class="html">i1</code> class to the <code class="html">&lt;span&gt;</code> element. <em>Do not</em> use <span class="utf">nbsp</span> for indentation. You can indent to multiple levels by incrementing the class to <code class="html">i2</code>, <code class="html">i3</code>, and so on, and including the appropriate <abbr class="initialism">CSS</abbr>.</p></li>
<li><p>If the poem is a shorter part of a longer work, like a novel, then wrap the stanzas in a <code class="html">&lt;blockquote&gt;</code> element.</p></li>
<li><p>If the poem is a standalone composition and part of a larger collection of poetry, wrap it in an <code class="html">&lt;article&gt;</code> element instead. The semantics of <code class="html">&lt;article&gt;</code> imply that the poem can be pulled out of the collection as a standalone item.</p></li>
<li><p>Give the containing element the semantic inflection of <code class="html">z3998:poem</code>, <code class="html">z3998:verse</code>, or <code class="html">z3998:song</code>.</p></li>
</ul>
<h3>Complete <abbr class="initialism">HTML</abbr> and <abbr class="initialism">CSS</abbr> markup examples</h3>
<p>Note that below we include <abbr class="initialism">CSS</abbr> for the <code class="html">i2</code> class, even though it’s not used in the example; it’s included to demonstrate how to adjust the CSS for indentation levels after the first.</p>
<code class="css full">[epub|type~="z3998:poem"] p{
text-align: left;
text-indent: 0;
}
[epub|type~="z3998:poem"] p &gt; span{
display: block;
text-indent: -1em;
padding-left: 1em;
}
[epub|type~="z3998:poem"] p &gt; span + br{
display: none;
}
[epub|type~="z3998:poem"] p + p{
margin-top: 1em;
}
[epub|type~="z3998:poem"] + p{
text-indent: 0;
}
p span.i1{
text-indent: -1em;
padding-left: 2em;
}
p span.i2{
text-indent: -1em;
padding-left: 3em;
}</code>
<code class="html full">&lt;blockquote epub:type="z3998:poem"&gt;
&lt;p&gt;
&lt;span&gt;“How doth the little crocodile&lt;/span&gt;
&lt;br/&gt;
&lt;span class="i1"&gt;Improve his shining tail,&lt;/span&gt;
&lt;br/&gt;
&lt;span&gt;And pour the waters of the Nile&lt;/span&gt;
&lt;br/&gt;
&lt;span class="i1"&gt;On every golden scale!&lt;/span&gt;
&lt;/p&gt;
&lt;p&gt;
&lt;span&gt;“How cheerfully he seems to grin,&lt;/span&gt;
&lt;br/&gt;
&lt;span class="i1"&gt;How neatly spread his claws,&lt;/span&gt;
&lt;br/&gt;
&lt;span&gt;And welcome little fishes in&lt;/span&gt;
&lt;br/&gt;
&lt;span class="i1"&gt;&lt;em&gt;With gently smiling jaws!&lt;/em&gt;”&lt;/span&gt;
&lt;/p&gt;
&lt;/blockquote&gt;</code>
<h3>Elision in poetry</h3>
<p>If a poem is quoted with one or more lines removed, the removed lines are represented with a vertical ellipses (⋮, U+22EE) in <code class="html">&lt;span class="elision"&gt;</code>, styled like so:</p>
<code class="html full">&lt;blockquote epub:type="z3998:verse"&gt;
&lt;p&gt;
&lt;span&gt;O Lady! we receive but what we give,&lt;/span&gt;
&lt;br/&gt;
&lt;span&gt;And in our life alone does nature live:&lt;/span&gt;
&lt;br/&gt;
&lt;span&gt;Ours is her wedding garments, ours her shroud!&lt;/span&gt;
&lt;br/&gt;
&lt;span class="elision"&gt;⋮&lt;/span&gt;
&lt;br/&gt;
&lt;span class="i1"&gt;Ah! from the soul itself must issue forth&lt;/span&gt;
&lt;br/&gt;
&lt;span&gt;A light, a glory, a fair luminous cloud,&lt;/span&gt;
&lt;/p&gt;
&lt;/blockquote&gt;</code>
<code class="css full">span.elision{
margin: .5em;
margin-left: 3em;
}
/* If eliding within an epigraph, include this additional style: */
[epub|type~="epigraph"] span.elision{
font-style: normal;
}</code>
</section>
<section id="images">
<h2>Images</h2>
<ul>
<li><p>All <code class="html">&lt;img&gt;</code> tags are required to have an <code class="html">alt</code> attribute that uses prose to describe the image in detail; this is what screen reading software will be read aloud.</p>
<ul>
<li><p>Describe the image itself in words, which is not the same as writing a caption or describing its place in the book.</p></li>
<li><p>Alt text must be full sentences ended with periods or other appropriate punctuation. Sentence fragments, or complete sentences without ending punctuation, are not acceptable.</p></li>
</ul>
<p>For example:</p>
<figure class="text">
<p class="wrong">&lt;img alt="The illustration for chapter 10" src="..."&gt;</p>
<p class="wrong">&lt;img alt="Pierre's fruit-filled dinner" src="..."&gt;</p>
<p class="corrected">&lt;img alt="An apple and a pear inside a bowl, resting on a table." src="..."&gt;</p>
</figure>
<p>Note that the <code class="html">alt</code> text does not necessarily have to be the same as text in the image’s <code class="html">&lt;figcaption&gt;</code> element. You can use <code class="html">&lt;figcaption&gt;</code> to write a concise context-dependent caption.</p>
</li>
<li><p>Include an <code class="html">epub:type</code> attribute to denote the type of image. Common values are <code class="html">z3998:illustration</code> or <code class="html">z3998:photograph</code>.</p></li>
<li><p>For some images, it’s helpful to invert their colors when the ereader enters night mode. This is particularly true for black-and-white line art and woodcuts. (Note <em>black-and-white</em>, i.e. only two colors, <strong>not</strong> grayscale!) Include the <code class="html">se:image.color-depth.black-on-transparent</code> semantic in the <code class="html">&lt;img&gt;</code> tag’s <code class="html">epub:type</code> to enable color inversion in some ereaders.</p>
<p>For that sort of art, save the images as PNG files with a transparent background. You can make the background transparent by using the “Color to alpha” tool available in many image editing programs, like <a href="https://www.gimp.org/">the GIMP</a>.</p></li>
<li><p><code class="html">&lt;img&gt;</code> tags that are meant to be aligned on the block level should be contained in a parent <code class="html">&lt;figure&gt;</code> tag, with an optional <code class="html">&lt;figcaption&gt;</code> sibling.</p>
<ul>
<li><p>If contained in a <code class="html">&lt;figure&gt;</code> tag, the image’s <code class="html">id</code> attribute must be on the <code class="html">&lt;figure&gt;</code> tag.</p></li></ul>
</li>
<li><p>Some sources of illustrations may have scanned them directly from the page of an old book, resulting in yellowed, dingy-looking scans of grayscale art. In these cases, convert the image to grayscale to remove the yellow tint.</p></li>
</ul>
<h3>Complete <abbr class="initialism">HTML</abbr> and <abbr class="initialism">CSS</abbr> markup examples</h3>
<code class="css full">/* If the image is meant to be on its own page, use this selector... */
figure.full-page{
margin: 0;
max-height: 100%;
page-break-before: always;
page-break-after: always;
page-break-inside: avoid;
text-align: center;
}
/* If the image is meant to be inline with the text, use this selector... */
figure{
margin: 1em auto;
text-align: center;
}
/* In all cases, also include the below styles */
figure img{
display: block;
margin: auto;
max-width: 100%;
}
figure + p{
text-indent: 0;
}
figcaption{
font-size: .75em;
font-style: italic;
margin: 1em;
}</code>
<code class="html full">&lt;figure id="image-10"&gt;
&lt;img alt="An apple and a pear inside a bowl, resting on a table." src="../images/image-10.jpg" epub:type="z3998:photograph"/&gt;
&lt;figcaption&gt;The Monk’s Repast&lt;/figcaption&gt;
&lt;/figure&gt;</code>
<code class="html full">&lt;figure class="full-page" id="image-11"&gt;
&lt;img alt="A massive whale breaching the water, with a sailor floating in the water directly within the whale’s mouth." src="../images/image-11.jpg" epub:type="z3998:illustration"/&gt;
&lt;figcaption&gt;The Whale eats Sailor Jim.&lt;/figcaption&gt;
&lt;/figure&gt;</code>
</section>
<section id="loi">
<h2>List of Illustrations (the LoI)</h2>
<p>If an ebook has any illustrations that are major structural components of the work (even just one!), then we must include an <code class="path">loi.xhtml</code> file at the end of the ebook. This file lists the illustrations in the ebook, along with a short caption or description.</p>
<p>An illustration is a major structural component if, for example: it is an illustration of events in the book, like a full-page drawing or end-of-chapter decoration; it is essential to the plot, like a diagram of a murder scene or a map; or it is a component of the text, like photographs in a documentary narrative.</p>
<p>Illustration that are <em>not</em> major structural components would be, for example: drawings used to represent a person's signature, like an X mark; inline drawings representing text in alien languages; drawings used as layout elements to illustrate diagrams.</p>
<p>If the image has a <code class="html">&lt;figcaption&gt;</code> element, then use that caption in the LoI. If not, use the image’s <code class="html">alt</code> tag, which should be a short prose description of the image used by screen readers.</p>
<p>Links to the images should go directly to their IDs, not just the top of the containing file.</p>
<p>The code below is the template for a basic LoI skeleton. Please copy and paste the entire thing as a starting point for your own LoI:</p>
<code class="html full">&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;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: https://standardebooks.org/vocab/1.0" xml:lang="en-GB"&gt;
&lt;head&gt;
&lt;title&gt;List of Illustrations&lt;/title&gt;
&lt;link href="../css/core.css" rel="stylesheet" type="text/css"/&gt;
&lt;link href="../css/local.css" rel="stylesheet" type="text/css"/&gt;
&lt;/head&gt;
&lt;body epub:type="backmatter"&gt;
&lt;section id="loi" epub:type="loi"&gt;
&lt;nav epub:type="loi"&gt;
&lt;h2 epub:type="title"&gt;List of Illustrations&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;a href="preface.xhtml#the-edge-of-the-world"&gt;The Edge of the World&lt;/a&gt;
&lt;/li&gt;
&lt;!--snip all the way to the end--&gt;
&lt;/ol&gt;
&lt;/nav&gt;
&lt;/section&gt;
&lt;/body&gt;
&lt;/html&gt;
</code>
</section>
<aside class="alert">
<p>Standard Ebooks is a brand-new project&mdash;this manual is a pre-alpha, and much of it is incomplete. If you have a question, need clarification, or run in to an issue not yet covered here, please <a href="https://groups.google.com/forum/#!forum/standardebooks">contact us</a> so we can update this manual.</p>
</aside>
</article>
</main>
<?= Template::Footer() ?>

35
www/contribute/tips-for-editors-and-proofreaders.php
View file

@ -1,13 +1,13 @@
<?
require_once('Core.php');
?><?= Template::Header(['title' => 'Tips for Editors and Proofreaders', 'js' => true, 'highlight' => 'contribute', 'description' => 'A list of tips and tricks for people who’d like to proofread a Standard Ebooks ebook.']) ?>
?><?= Template::Header(['title' => 'Tips for Editors and Proofreaders', 'manual' => true, 'highlight' => 'contribute', 'description' => 'A list of tips and tricks for people who’d like to proofread a Standard Ebooks ebook.']) ?>
<main>
<article>
<h1>Tips for Editors and Proofreaders</h1>
<p>Advances in ereading devices and software have made proofreading ebooks a whole lot easier than in the past.</p>
<p>Most ereading software allows you to highlight text and add notes to those highlights. If you’re using a device like a Kindle or a phone or tablet with the Google Play Books app, try holding your finger on some text. It’ll become highlighted, and you can drag the highlight to include more text if you like.</p>
<p>That means the quickest way for you to proofread an ebook is to <a href="/help/how-to-use-our-ebooks">transfer it to your ereader</a> and start reading! Once you find an error, use the highlight feature to mark it, and keep on reading. Many errors, like mis-curled quotation marks or obvious spelling errors, don’t need a written note to accompany the highlight. But you should make a brief written note if the error wouldn’t be clear to a passing reader.</p>
<p>Once you’ve finished the ebook, use your ereader’s “view all notes” option to find all of your highlights in one place. Then you can either <a href="/contribute/report-errors">report them to us</a>, or if you’re technically-minded, correct them directly in the ebook’s <a href="http://github.com/standardebooks">GitHub repository</a>. Remember to read our <a href="/contribute/typography">typography manual</a> to make sure the error you found is covered.</p>
<p>Once you’ve finished the ebook, use your ereader’s “view all notes” option to find all of your highlights in one place. Then you can either <a href="/contribute/report-errors">report them to us</a>, or if you’re technically-minded, correct them directly in the ebook’s <a href="http://github.com/standardebooks">GitHub repository</a>. Remember to read the <a href="/manual">Standard Ebooks Manual of Style</a> to make sure the error you found is covered.</p>
<section id="common-errors">
<h2>Common errors to watch out for</h2>
<p>Lots of different errors can occur during the long and complex process of digitizing a print book, but here are some of the more common ones:</p>
@ -20,7 +20,7 @@ require_once('Core.php');
</figure>
</li>
<li><h3>Incorrect or archaic use of quotation marks</h3>
<p>Older texts frequently use quotation marks for names of books and periodicals, or for the names of pubs, inns, and other places. Our <a href="/contribute/typography">typography manual</a> requires that certain standalone media be in italics instead, and that place names <em>not</em> be set in quotes.</p>
<p>Older texts frequently use quotation marks for names of books and periodicals, or for the names of pubs, inns, and other places. Our <a href="/manual/latest/8-typography">typography manual</a> requires that certain standalone media be in italics instead, and that place names <em>not</em> be set in quotes.</p>
<figure class="text">
<p class="wrong">He read &ldquo;Candide&rdquo; while having a pint at the &ldquo;King’s Head.&rdquo;</p>
<p class="corrected">He read <i>Candide</i> while having a pint at the King’s Head.</p>
@ -29,10 +29,10 @@ require_once('Core.php');
<li>
<h3>Missing italics</h3>
<p>Often transcribers just don’t include italics at all in their work. A very quick visual scan of a HathiTrust or Google Books copy of the book you’re proofing should bring any sections in italics to your attention. Make sure to confirm them in the transcription, so that we’re not missing italics that should be there.</p>
</li>
<li>
<h3>Ending dialog with a double-em-dash</h3>
<p>Some authors were in the habit of showing a sudden break in dialog with an extra-wide double-em-dash. Our <a href="/contribute/typography">typography manual</a> requires that these be replaced by single em-dashes, so mark them for correction.</p>
<p>Some authors were in the habit of showing a sudden break in dialog with an extra-wide double-em-dash. Our <a href="/manual/latest/8-typography">typography manual</a> requires that these be replaced by single em-dashes, so mark them for correction.</p>
<figure class="text">
<p class="wrong">“Why, I never——” she cried.</p>
<p class="corrected">“Why, I never—” she cried.</p>
@ -45,7 +45,7 @@ require_once('Core.php');
<li>
<h3>Using &amp;c. instead of etc.</h3>
<p>&ldquo;etc.&rdquo; is an abbreviation of the Latin <i>et cetera</i>; In Latin, <i>et</i> means &ldquo;and&rdquo;, so older texts often abbreviated <i>et cetera</i> as &ldquo;&amp;c.&rdquo;</p>
<p>Our <a href="/contribute/typography">typography manual</a> requires a change from &amp;c. to etc., so make sure to mark these corrections.</p>
<p>Our <a href="/manual/latest/8-typography">typography manual</a> requires a change from &amp;c. to etc., so make sure to mark these corrections.</p>
</li>
<li>
<h3>Use of &ldquo;ibid.&rdquo; in footnotes or endnotes</h3>
@ -60,21 +60,16 @@ require_once('Core.php');
<li>
<h3>Section dividers as text instead of as markup</h3>
<p>There are lots of ways authors mark section breaks in text. A common way to do this is with three or more asterisks:</p>
<figure class="text">
<code class="html full">&lt;p&gt;Some text in the first section...&lt;/p&gt;
&lt;p&gt;***&lt;/p&gt;
&lt;p&gt;The second section begins...&lt;/p&gt;
</code>
</figure>
<figure><code class="html full"><span class="p">&lt;</span><span class="nt">p</span><span class="p">&gt;</span>Some text in the first section...<span class="p">&lt;/</span><span class="" ass="nt">p</span><span class="p">&gt;</span>
<span class="p">&lt;</span><span class="nt">p</span><span class="p">&gt;</span>***<span class="p">&lt;/</span><span class="nt">p</span><span class="p">&gt;</span>
<span class="p">&lt;</span><span class="nt">p</span><span class="p">&gt;</span>The second section begins...<span class="p">&lt;/</span><span class="nt">p</span><span class="p">&gt;</span></code></figure>
<p>In Standard Ebooks, sections must be marked with the <code class="html">&lt;hr/&gt;</code> tag:</p>
<figure class="text">
<code class="html full">&lt;p&gt;Some text in the first section...&lt;/p&gt;
&lt;hr/&gt;
&lt;p&gt;The second section begins...&lt;/p&gt;
</code>
</figure>
<p>As you’re reading, the <code class="html">&lt;hr/&gt;</code> tag appears as a short black line dividing sections.</p>
<p>Mark for correction any section breaks that don’t use the <code class="html">&lt;hr/&gt;</code> tag.</p>
<figure><code class="html full"><span class="p">&lt;</span><span class="nt">p</span><span class="p">&gt;</span>Some text in the first section...<span class="p">&lt;/</span><span class="nt">p</span><span class="p">&gt;</span>
<span class="p">&lt;</span><span class="nt">hr</span><span class="p">/&gt;</span>
<span class="p">&lt;</span><span class="nt">p</span><span class="p">&gt;</span>The second section begins...<span class="p">&lt;/</span><span class="nt">p</span><span class="p">&gt;</span></code></figure>
<p>As you’re reading, the <code class="html"><span class="p">&lt;</span><span class="nt">hr</span><span class="p">/&gt;</span></code> element appears as a short black line dividing sections.</p>
<p>Mark for correction any section breaks that don’t use the <code class="html"><span class="p">&lt;</span><span class="nt">hr</span><span class="p">/&gt;</span></code> element.</p>
</li>
</ul>
</section>

14
www/contribute/toolset.php
View file

@ -1,14 +0,0 @@
<?
require_once('Core.php');
?><?= Template::Header(['title' => 'Toolset Guidelines', 'highlight' => 'contribute', 'description' => 'Guidelines for programming language and code style used in the Standard Ebooks toolset.']) ?>
<main>
<article>
<h1>Toolset Guidelines</h1>
<p>You can <a href="https://github.com/standardebooks/tools">view our toolset on GitHub</a>.</p>
<p>Contributions should be in Python 3.</p>
<p>In general we follow a relaxed version of <a href="https://www.python.org/dev/peps/pep-0008/">PEP 8</a>. In particular, we use tabs instead of spaces, and there is no line length limit.</p>
<p>Always use the <code class="path">regex</code> module instead of the <code class="path">re</code> module.</p>
<p>At the minimum, scripts should use programs available for installation on Ubuntu 18.04 LTS systems, either via <code class="program">apt</code> or <code class="program">pip3</code>.</p>
</article>
</main>
<?= Template::Footer() ?>

859
www/contribute/typography.php
View file

@ -1,859 +0,0 @@
<?
require_once('Core.php');
?><?= Template::Header(['title' => 'Typography Manual', 'js' => true, 'highlight' => 'contribute', 'description' => 'The Standard Ebooks Typography Manual, containing details on specific typographic requirements for Standard Ebooks ebooks.']) ?>
<main>
<article>
<h1>Typography Manual</h1>
<aside class="alert">
<p>Standard Ebooks is a brand-new project&mdash;this manual is a pre-alpha, and much of it is incomplete. If you have a question, need clarification, or run in to an issue not yet covered here, please <a href="https://groups.google.com/forum/#!forum/standardebooks">contact us</a> so we can update this manual.</p>
</aside>
<h2>The Standard Ebooks Style Philosophy</h2>
<p>Standard Ebooks’ goal is to bring classic public domain literature into the digital era by making it accessible, attractive, and by maintaining a high standard of quality. To that end we’re not interested in slavishly reproducing the formatting quirks, transcription errors, publisher’s ephemera, or other inconsequential style decisions of the past. While we strive to be good custodians of the literature entrusted to the public, we recognize that the freedom of the public domain intersects with the Internet era in a way that allows us to present that literature in an attractive, modern, and high-quality way.</p>
<h2>Your task</h2>
<p>As an editor, proofreader, or producer of a Standard Ebook, part of your task is to take the source transcription of your ebook and apply this typography manual to it. This manual outlines various standardizations and modernizations to old typography practices, making older texts easier to read for modern readers.</p>
<p>Many of the rules below have been accepted standards for a hundred years or more. That means that many of the ebooks you produce may not need that much adjustment. The <code class="program">typogrify</code> tool in the <a href="https://github.com/standardebooks/tools">Standard Ebooks toolset</a> also automatically takes care of some (but not all!) of these rules. Typically, the older the source, the more of these rules you’ll have to check during production.</p>
<h2>Normalizing different formatting styles</h2>
<p>Our general rule is: <b>If it doesn’t affect the meaning of the work, then normalize it according to these standards.</b></p>
<section id="common-problems">
<h2>Common problems to keep an eye out for</h2>
<ul>
<li>
<p>Some sources use a two-em-dash to interrupt dialog. You should replace such two-em-dashes with a single em-dash according to the <a href="#dashes">section on dashes</a>.</p>
<figure class="text">
<p class="wrong">&ldquo;Why, I never&mdash;&mdash;&rdquo; she cried.</p>
<p class="corrected">&ldquo;Why, I never&mdash;&rdquo; she cried.</p>
</figure>
<p>Note that a two-em-dash is <em>also</em> used to signify a missing or purposefully obscured word. This is correct, but you should ensure that instead of two consecutive em-dashes, you use the two-em-dash glyph (⸺ or U+2E3A) for <em>partially</em>-obscured words, the three-em-dash glyph (⸻ or U+2E3B) for <em>completely</em>-obscured words, and a single em-dash for partially-obscured <em>years</em>.</p>
<figure class="text">
<p class="corrected">Sally J⸺ walked through the town of ⸻ in the year 19—.</p>
</figure>
</li>
<li>
<p>Small caps are commonly used instead of italics for emphasis in older texts, and some transcriptions use all caps instead of italics. These should generally be converted to regular case and wrapped in <code class="html">&lt;em&gt;</code> tags. If a text truly does call for extreme emphasis, the <code class="html">&lt;strong&gt;</code> tag can be used&mdash;but think twice about using it, and use it sparingly. See the <a href="#text-in-all-caps">section on text in all caps</a>.</p>
<figure class="text">
<p class="wrong">That donut was DELICIOUS!</p>
<p class="corrected">That donut was &lt;em&gt;delicious&lt;/em&gt;!</p>
</figure>
</li>
</ul>
</section>
<section id="general">
<h2>General</h2>
<ul>
<li>
<p>Our general style guide is the Chicago Manual of Style, 16th edition, with a few tweaks outlined below. Work following a different style guide should be converted to conform to ours, unless it changes the meaning of the work.</p>
</li>
<li>
<p><em>Do</em> convert from logical punctuation to American punctuation where possible.</p>
</li>
<li>
<p><em>Do</em> convert from British quotation to American quotation where possible. The <code class="program">british2american</code> script is helpful for automating most (but not all!) of this.</p>
</li>
</ul>
</section>
<section id="section-endings">
<h2>Section endings</h2>
<p>Some older books end with “The End”, “Fin”, or some other equivalent. Remove these.</p>
<p>Some books also end individual sections or chapters with “The end of such-and-such section”. Remove these as well.</p>
</section>
<section id="chapters">
<h2>Chapter names and titles</h2>
<ul>
<li>
<p>In the body text, always use Roman numerals for chapter numbers instead of Arabic numerals. But in an individual file’s <code class="html">&lt;title&gt;</code> tag, <em>do</em> use Arabic numbers instead of Roman numerals.</p>
<p><em>Do not</em> use the Unicode Roman numeral glyphs, as they are deprecated; use regular letters.</p>
</li>
<li>
<p>Convert all-caps or small-caps titles to title case. Use the <code class="program">se titlecase</code> script in the <a href="https://github.com/standardebooks/tools">Standard Ebooks toolset</a> for consistent titlecasing.</p>
</li>
<li>
<p>Remove trailing periods from chapter titles.</p>
</li>
<li>
<p>Omit the word “Chapter” from chapter titles.</p>
<p>Some ebooks should keep “Chapter” in titles if clarity is necessary: for example, <i><a href="/ebooks/mary-shelley/frankenstein/">Frankenstein</a></i> has “Chapter” in titles to differentiate between the “Letter” sections.</p>
<figure class="text">
<p class="wrong">Chapter 33</p>
<p class="corrected">XXXIII</p>
</figure>
</li>
</ul>
</section>
<section id="italics-or-quotes">
<h2>Italicizing or quoting newly-used words</h2>
<ul>
<li>
<p>When introducing new terms, italicize foreign or technical terms, but use quotation marks for terms composed of regular English.</p>
<figure class="text">
<p class="corrected">English whalers have given this the name “ice blink.”</p>
<p class="corrected">The soil consisted of that igneous gravel called <i>tuff</i>.</p>
</figure>
</li>
<li>
<p>Don’t italicize English neologisms in works where a special vocabulary is a regular part of the narrative; specifically, science fiction works that may necessarily contain made-up English technology words. However, <em>do</em> italicize “alien” language in such works.</p>
</li>
<li>
<p>Including <em>both</em> italics <em>and</em> quotes, outside of the context of quoted dialog, is usually not necessary. Use one or the other based on the rules above.</p>
</li>
</ul>
</section>
<section id="names-and-titles">
<h2>Names and titles: Italicize or quote?</h2>
<ul>
<li>
<p>Names and titles are usually <em>either</em> italicized <em>or</em> quoted, but almost never both. Pick one or the other based on the rules below.</p>
</li>
<li>
<p>Older work may pick the opposite of the rules below; change such texts to match this manual.</p>
</li>
<li>
<p>Older work may use quotation marks around proper names, like pub, bar, building, or company names. Remove those quotes.</p>
<figure class="text">
<p class="wrong">He read &ldquo;Candide&rdquo; while having a pint at the &ldquo;King’s Head.&rdquo;</p>
<p class="corrected">He read <i>Candide</i> while having a pint at the King’s Head.</p>
</figure>
</li>
<li>
<p>In general, italicize things that can stand alone. Specifically:</p>
<ul>
<li>
<p>Magazines</p>
</li>
<li>
<p>Plays</p>
</li>
<li>
<p>Books and novels <em>except</em> “holy texts,” like the Bible or books within the Bible</p>
</li>
<li>
<p>Long musical compositions, like operas</p>
</li>
<li>
<p>Music albums</p>
</li>
<li>
<p>Films</p>
</li>
<li>
<p>TV shows</p>
</li>
<li>
<p>Radio shows</p>
</li>
<li>
<p>Titles of artwork</p>
</li>
<li>
<p>Long poems and ballads, like the <i>Iliad</i></p>
</li>
<li>
<p>Pamphlets</p>
</li>
<li>
<p>Journals</p>
</li>
<li>
<p>Newspapers</p>
</li>
<li>
<p>Names of ships</p>
</li>
<li>
<p>Names of sculptures</p>
</li>
</ul>
</li>
<li>
<p>In general, quote things that are short or parts of longer work. Specifically:</p>
<ul>
<li>
<p>Short musical compositions, like pop songs</p>
</li>
<li>
<p>Chapter titles</p>
</li>
<li>
<p>Short stories</p>
</li>
<li>
<p>Novellas</p>
</li>
<li>
<p>Individual newspaper or journal articles</p>
</li>
<li>
<p>Essays</p>
</li>
<li>
<p>Short films</p>
</li>
<li>
<p>Episodes in a TV or radio series</p>
</li>
</ul>
</li>
</ul>
</section>
<section id="capitalization">
<h2>Capitalization</h2>
<section id="capitalization-general">
<h3>General</h3>
<ul>
<li>
<p>Some very old works frequently capitalize nouns that today we no longer capitalize. In general, only capitalize the beginnings of clauses, and proper nouns in the way that you would in modern English writing. Remove archaic capitalization unless doing so would change the meaning of the work.</p>
</li>
</ul>
</section>
<section id="text-in-all-caps">
<h3>Text in all caps</h3>
<ul>
<li>
<p>Text in all caps is almost never correct typography. Instead, convert such text to the correct case and surround it with a semantically-meaningful tag like <code class="html">&lt;em&gt;</code> (for emphasis), <code class="html">&lt;strong&gt;</code> (for strong emphasis, like shouting) or <code class="html">&lt;b&gt;</code> (for unsemantic formatting required by the text). Then, use <code class="css">font-weight: normal; font-variant: small-caps;</code> styling to render those tags in small caps.</p>
</li>
</ul>
<figure class="text">
<p class="corrected">The sign read &lt;b&gt;Bob’s Restaurant&lt;/b&gt;.</p>
<p class="corrected">&ldquo;&lt;strong&gt;Charge!&lt;/strong&gt;&rdquo; he cried.</p>
</figure>
</section>
<section>
<h3>Apostrophes</h3>
<p>When addressing something as an apostrophe, “O” is capitalized.</p>
<figure class="text">
<p class="corrected">I carried the bodies into the sea, O walker in the sea!</p>
</figure>
</section>
</section>
<section id="spacing">
<h2>Spacing</h2>
<ul>
<li>Sentences should be single-spaced. Convert double-spaced sentences to single-space.</li>
</ul>
</section>
<section id="italics">
<h2>Italics</h2>
<ul>
<li>
<p>Italics should generally be used for emphasis. Some older texts make frequent use of small caps for emphasis; change these to italics. Italics indicating emphasis must be wrapped with the <code class="html">&lt;em&gt;</code> tag.</p>
</li>
<li>
<p>Set individual letters that are read as letters in italics...</p>
<figure class="text">
<p class="corrected">He often rolled his <i>r</i>’s.</p>
</figure>
<p><em>Unless</em> referring to a name that happens to be a single letter or composed of single letters, or if that letter is standing in for a name...</p>
<figure class="text">
<p class="corrected">...due to the loss of what is known in New England as the “L”: that long deep roofed adjunct usually built at right angles to the main house...</p>
<p class="corrected">She was learning her A B Cs.</p>
</figure>
<p>Or if the letter is meant to be a comparison to a shape:</p>
<figure class="text">
<p class="corrected">His trident had the shape of an E.</p>
</figure>
<p>When using the ordinal “nth,” italicize the n, and do not include a hyphen:</p>
<figure class="text">
<p class="corrected">The <i>n</i>th degree.</p>
</figure>
</li>
<li>
<p>Words written to be read as sounds are set in italics using <code class="html">&lt;i&gt;</code>:</p>
<figure class="text">
<p class="corrected">He could hear the dog barking: <i>Ruff, ruff, ruff!</i></p>
</figure>
</li>
<li>
<p><a href="#names-and-titles">See here for italicizing names and titles</a>.</p>
</li>
</ul>
<section id="italics-language">
<h3>Italics for foreign languages</h3>
<ul>
<li>
<p>Set foreign words and phrases <em>that are not in the <a href="http://www.merriam-webster.com/">Merriam-Webster</a> dictionary</em> in italics. If the foreign word or phrase <em>is</em> in Merriam-Webster, <em>don’t</em> set it in italics.</p>
<figure class="text">
<p class="corrected">The pièce de résistance of the dessert course was a <i>mousse au chocolat</i>.</p>
</figure>
</li>
<li>
<p><em>Don’t</em> italicize foreign words in proper names, unless the name itself would be italicized according to the rules for <a href="#names-and-titles">italicizing or quoting names and titles</a>.</p>
<figure class="text">
<p class="wrong">She got off the metro at the <i>Place de Clichy</i> stop, next to the <i>Le Bon Petit Déjeuner</i> restaurant.</p>
<p class="corrected">“<i>Où est le métro?</i>” he asked, and she pointed to Place de Clichy, next to the Le Bon Petit Déjeuner restaurant.</p>
</figure>
</li>
<li>
<p>If a certain foreign word is used so frequently in the text that italicizing it would be distracting to the reader, then only italicize the first instance. However, wrap the following instances in <code class="html">&lt;span xml:lang="LANGUAGE"&gt;</code>.</p>
</li>
<li>
<p>Certain exceptions to italicizing foreign words can be made if a specific word is in Merriam-Webster, but in the producer’s opinion is still too obscure for the general reader and thus should be italicized anyway. In this case ask the Standard Ebooks editor-in-chief for how to proceed.</p>
</li>
</ul>
</section>
<section id="italics-punctuation">
<h3>Punctuation in italics</h3>
<ul>
<li>
<p>If italicizing a short phrase within a longer clause, don’t italicize trailing punctuation that may belong to the containing clause.</p>
<figure class="text">
<p class="wrong">“Look at <em>that!</em>” she shouted.</p>
<p class="corrected">“Look at <em>that</em>!” she shouted.</p>
</figure>
</li>
<li>
<p>However, if an entire clause is italicized for emphasis, then <em>do</em> include the trailing punctuation in the italics, <em>unless</em> that trailing punctuation is a comma at the end of some dialog.</p>
<table>
<thead>
<tr>
<td>Result</td>
<td>Code</td>
</tr>
</thead>
<tbody>
<tr>
<td>
<p>“<em>Charge!</em>” she shouted.</p>
</td>
<td><code class="html full">“&lt;em&gt;Charge!&lt;/em&gt;” she shouted.</code></td>
</tr>
<tr>
<td>
<p><em>“But I want to</em>,” she said.</p>
</td>
<td><code class="html full">“&lt;em&gt;But I want to&lt;/em&gt;,” she said.</code></td>
</tr>
</tbody>
</table>
</li>
</ul>
</section>
<section id="taxonomy">
<h3>Taxonomy</h3>
<ul>
<li>
<p>Binomial names (generic, specific, and subspecific) are italicized with the <code class="html">&lt;i&gt;</code> tag and with the <code class="html">z3998:taxonomy</code> semantic inflection.</p>
<table>
<thead>
<tr>
<td>Result</td>
<td>Code</td>
</tr>
</thead>
<tbody>
<tr>
<td>
<p>A bonobo monkey is <i>Pan paniscus</i>.</p>
</td>
<td><code class="html full">A bonobo monkey is &lt;i epub:type="z3998:taxonomy"&gt;Pan paniscus&lt;/i&gt;.</code></td>
</tr>
</tbody>
</table>
</li>
<li>
<p>Family, order, class, phylum or division, and kingdom names are capitalized but not italicized.</p>
<figure class="text">
<p class="corrected">A bonobo monkey is in the phylum Chordata, class Mammalia, order Primates.</p>
</figure>
</li>
<li>
<p>Modern usage requires that the second part in a binomial name be set in lowercase. Older texts may set it in uppercase. Use the style in the source text.</p>
</li>
</ul>
</section>
</section>
<section id="indentation">
<h2>Indentation</h2>
<ul>
<li>
<p>Body text in a new paragraph that directly follows earlier body text is indented by 1em.</p>
</li>
<li>
<p>The initial line of body text in a section, or any text following a visible break in text flow, like a header, a scene break, a figure, a block quotation, etc., is not indented.</p>
<p>For example: in a block quotation, there is a margin before the quotation and after the quotation. Thus, the first line of the quotation is not indented, and the first line of body text after the block quotation is also not indented.</p>
</li>
</ul>
</section>
<section id="punctuation">
<h2>Punctuation</h2>
<ul>
<li>
<p><a href="#italics-punctuation">See here for punctuation in italics</a>.</p>
</li>
</ul>
<section id="spaces">
<h3>Spaces</h3>
<ul>
<li>
<p>Use single spaces between sentences.</p>
</li>
</ul>
</section>
<section id="quotation-marks">
<h3>Quotation marks</h3>
<ul>
<li>
<p>“Curly” or typographer’s quotes should always be used.</p>
<figure class="text">
<p class="corrected">“Don’t do it!” she shouted.</p>
</figure>
</li>
<li>
<p>Quotation marks that are directly side-by-side must be separated by a hair space (U+200A) character.</p>
<figure class="text">
<p class="corrected">“<span class="utf">hairsp</span>‘Green?’ Is that what you said?” asked Dave.</p>
</figure>
</li>
<li>
<p>Words with missing letters should use the right single quotation mark (’ or U+2019) character to indicate ommission.</p>
<figure class="text">
<p class="corrected">He had pork ’n’ beans for dinner</p>
</figure>
</li>
</ul>
</section>
<section id="ellipses">
<h3>Ellipses</h3>
<ul>
<li>
<p>Use the ellipses (U+2026) glyph instead of consecutive or spaced periods.</p>
</li>
<li>
<p>When used as suspension points (for example, to indicate dialog that pauses or trails off), don’t precede the ellipses with a comma. Commas followed by ellipses were sometimes used in older texts, but are now redundant to modern readers; remove them.</p>
<p>Note that ellipses used to indicate missing words in a quotation still require keeping surrounding punctuation, including commas, because that punctuation is in the original quotation.</p>
</li>
<li>
<p>Place a hair space (U+200A) glyph before all ellipses that are not directly preceded by punctuation, or that are directly preceded by an em-dash or a two- or three-em-dash. Place a regular space after all ellipses that are not followed by punctuation. If the ellipses is followed by punctuation, place a hair space between the ellipses and punctuation, <em>unless</em> the punctuation is a quotation mark, in which case don’t put a space at all.</p>
<figure class="text">
<p class="corrected">“I’m so hungry<span class="utf">hairsp</span>&hellip; What were you saying about eating<span class="utf">hairsp</span>&hellip;?”</p>
</figure>
</li>
</ul>
</section>
<section id="dashes">
<h3>Dashes</h3>
<p>There are many kinds of dashes, and your run-of-the-mill hyphen is often not what you should use. In particular, don’t use the hyphen for things like date ranges, phone numbers, or negative numbers.</p>
<ul>
<li>
<p>Do not put spaces around em-dashes. Remove spaces if in the original text.</p>
</li>
<li>
<p>Use em-dashes (— or U+2014) to offset parenthetical phrases. These are usually the most common kind of dash.</p>
</li>
<li>
<p>Use an em-dash for partially-obscured years.</p>
<figure class="text">
<p class="corrected">It was the year 19— in the town of Metrolopis.</p>
</figure>
<p>Use a regular hyphen if only the last digit of the year is obscured.</p>
<figure class="text">
<p class="corrected">It was the year 186- in the town of Metrolopis.</p>
</figure>
</li>
<li>
<p>Some older texts use two em-dashes to indicate an interruption in thought or speech. Our style is to replace two em-dashes used as an interruption marker with a single em-dash. However, <em>don’t</em> replace two em-dashes used to indicate the omission of a word (like an anonymous name or an expletive); see below.</p>
</li>
<li>
<p>Use a two-em-dash glyph (⸺ or U+2E3A) to signify a purposefully <em>partially</em> obscured word. The two-em-dash glyph isn’t available in some fonts, but include it anyway; our build process will convert it later.</p>
<figure class="text">
<p class="corrected">Sally J⸺ walked through town.</p>
</figure>
</li>
<li>
<p>Use a three-em-dash glyph (⸻ or U+2E3B) for <em>completely</em> obscured words.</p>
<figure class="text">
<p class="corrected">It was night in the town of ⸻.</p>
</figure>
</li>
<li>
<p>En-dashes (– or U+2013) are used to indicate a numerical or date range; when you can substitute the word “to,” for example between locations; or to indicate a connection in location between two places.</p>
<figure class="text">
<p class="corrected">We talked 2–3 days ago.</p>
<p class="corrected">We took the Berlin–Munich train yesterday.</p>
<p class="corrected">I saw the torpedo-boat in the Ems⁠–⁠Jade Canal.</p>
</figure>
</li>
<li>
<p>Figure dashes (‒ or U+2012) are used to indicate a dash in numbers that aren’t a range, like phone numbers.</p>
<figure class="text">
<p class="corrected">His number is 555‒1234.</p>
</figure>
</li>
<li>
<p>Minus dashes (− or U+2212) are used to indicate negative numbers and are used in mathematical equations instead of hyphens.</p>
<figure class="text">
<p class="corrected">It was −5° out yesterday!</p>
</figure>
</li>
<li>
<p>Many older texts use archaic spelling and hyphenate compound words that are no longer hyphenated today. Use the <code class="program">modernize-spelling</code> script to automatically find and correct candidates. Note that this script isn’t perfect, and proofreading is required after using it to make sure it didn’t wrongly remove a hyphen!</p>
<p><em>Do not</em> use the <code class="program">modernize-spelling</code> script on poetry.</p>
</li>
</ul>
</section>
</section>
<section id="latinisms">
<h2>Latinisms</h2>
<ul>
<li>
<p><em>Don’t</em> italicize Latinisms that can be found in a modern dictionary, like e.g., i.e., ad hoc, viz., ibid., etc. <em>except</em> sic, which should always be italicized. Some older works might italicize these kinds of Latinisms; remove the italics.</p>
</li>
<li>
<p><em>Do</em> italicize whole passages of Latin language (as you would italicize any passages of foreign text in a work) and Latinisms that <em>aren’t</em> found in a modern dictionary.</p>
</li>
<li>
<p>Latinisms that are abbreviations should be set in lowercase with periods between words and no spaces between them, <em>except</em>:</p>
<ul>
<li>
<p><abbr class="era">BC</abbr>, <abbr class="era">AD</abbr>, <abbr class="era">BCE</abbr>, and <abbr class="era">CE</abbr> should be set without periods and in small caps and wrapped with the <code class="html">&lt;abbr class="era"&gt;</code> tag.</p>
<table>
<thead>
<tr>
<td>Result</td>
<td>Code</td>
</tr>
</thead>
<tbody>
<tr>
<td>
<p>Julius Caesar was born around 100 <abbr class="era">BC</abbr>.</p>
</td>
<td><code class="css full">abbr.era{
font-variant: all-small-caps;
}</code> <code class="html full">Julius Caesar was born around 100 &lt;abbr class="era"&gt;BC&lt;/abbr&gt;.</code></td>
</tr>
</tbody>
</table>
</li>
</ul>
</li>
<li>
<p>Always use “etc.” instead of “&amp;c;”. Some older works use the latter; convert them to the former.</p>
</li>
<li>
<p>For “Ibid.,” see <a href="#endnotes">endnotes</a>.</p>
</li>
</ul>
</section>
<section id="initials">
<h2>Initials and Abbreviations</h2>
<ul>
<li>
<p><a href="#temperatures">See here for temperatures</a>.</p>
</li>
<li>
<p><a href="#times">See here for times</a>.</p>
</li>
<li>
<p><a href="#latinisms">See here for Latinisms</a> including <abbr class="era">BC</abbr> and <abbr class="era">AD</abbr>.</p>
</li>
<li>
<p>&ldquo;OK&rdquo; is set without periods or spaces. It is <em>not</em> an abbreviation.</p>
</li>
<li>
<p>An acronym is a term made up of initials and pronounced as one word: <abbr class="acronym long">NASA</abbr>, <abbr class="acronym long">SCUBA</abbr>, <abbr class="acronym long">TASER</abbr>.</p>
<p>An initialism is a term made up of initials in which each initial is pronounced separately: <abbr class="initialism">ABC</abbr>, <abbr class="initialism">HTML</abbr>, <abbr class="initialism">CSS</abbr>.</p>
<p>A contraction is an abbreviation of a longer word: Mr., Mrs., lbs.</p>
</li>
<li>
<p>In general, abbreviations ending in a lowercase letter should be set without spaces and followed by a period. Abbreviations without lowercase letters should be set without spaces and without a trailing period. Always use a no-break space after an abbreviation that describes the next word, like Mr., Mrs., Mt., St., etc. A few exceptions follow.</p>
</li>
<li>
<p>Initials of people’s names should be separated by periods and spaces. Wrap such initials in <code class="html">&lt;abbr class="name"&gt;</code>.</p>
<table>
<thead>
<tr>
<td>Result</td>
<td>Code</td>
</tr>
</thead>
<tbody>
<tr>
<td>
<p><abbr class="name">H. P.</abbr> Lovecraft</p>
</td>
<td><code class="html full">&lt;abbr class="name"&gt;H. P.&lt;/abbr&gt; Lovecraft</code></td>
</tr>
</tbody>
</table>
</li>
<li>
<p>Compass directions should be wrapped in <code class="html">&lt;abbr class="compass"&gt;</code>, with periods and spaces.</p>
<table>
<thead>
<tr>
<td>Result</td>
<td>Code</td>
</tr>
</thead>
<tbody>
<tr>
<td>
<p>He traveled <abbr class="compass">N. W.</abbr>, then <abbr class="compass eoc">E. S. E.</abbr></p>
</td>
<td><code class="html full">He traveled &lt;abbr class="compass"&gt;N. W.&lt;/abbr&gt;, then &lt;abbr class="compass eoc"&gt;E. S. E.&lt;/abbr&gt;</code></td>
</tr>
</tbody>
</table>
</li>
<li>
<p>For acronyms, initialisms, postal codes, temperatures, and abbreviated US states, remove periods and spaces. All of these are set in caps, except for temperatures and acronyms, which are set in small caps. The source code should represent the abbreviations in caps, but wrapped in an <code class="html">&lt;abbr&gt;</code> tag.</p>
<p>All acronyms are set in small caps. Because acroynms are capitalized in the source code, use the <abbr class="initialism">CSS</abbr> style <code class="css">font-variant: all-small-caps;</code> to properly set them in small caps.</p>
<table>
<thead>
<tr>
<td>Result</td>
<td>Code</td>
</tr>
</thead>
<tbody>
<tr>
<td>
<p><abbr>Dr.</abbr> <abbr class="name">J. D.</abbr> Ross, <abbr class="degree">MD</abbr>, served on the <abbr class="initialism">HMS</abbr> <i epub:type="se:name.vessel.ship">Bounty</i> as a <abbr class="acronym">NASA</abbr> liaison.</p>
</td>
<td><code class="css full">abbr.acronym{
font-variant: all-small-caps;
}</code> <code class="html full">&lt;abbr&gt;Dr.&lt;/abbr&gt; &lt;abbr class=&quot;name&quot;&gt;J. D.&lt;/abbr&gt; Ross, &lt;abbr class=&quot;degree&quot;&gt;MD&lt;/abbr&gt;, served on the &lt;abbr class=&quot;initialism&quot;&gt;HMS&lt;/abbr&gt; &lt;i epub:type=&quot;se:name.vessel.ship&quot;&gt;Bounty&lt;/i&gt; as a &lt;abbr class=&quot;acronym&quot;&gt;NASA&lt;/abbr&gt; laison.</code></td>
</tr>
</tbody>
</table>
</li>
<li>
<p>Unless mentioned above, <em>do not</em> set initialisms in small caps.</p>
</li>
</ul>
</section>
<section id="chemicals-and-compounds">
<h2>Chemicals and compounds</h2>
<ul>
<li>
<p>Set molecular compounds in regular type without spaces.</p>
</li>
<li>
<p>Elements should be capitalized according to their listing in the periodic table.</p>
</li>
<li>
<p>Amounts of an element should be set in subscript using the <code class="html">&lt;sub&gt;</code> tag.</p>
</li>
</ul>
<table>
<thead>
<tr>
<td>Result</td>
<td>Code</td>
</tr>
</thead>
<tbody>
<tr>
<td>
<p>H<sub>2</sub>O</p>
</td>
<td><code class="html full">H&lt;sub&gt;2&lt;/sub&gt;O</code></td>
</tr>
</tbody>
</table>
</section>
<section id="temperatures">
<h2>Temperatures</h2>
<ul>
<li>
<p>Use the minus glyph (− or U+2212), not the hyphen glyph, to indicate negative numbers.</p>
</li>
<li>
<p>Using either the degree glyph (° or U+00B0) or the word “degrees” is acceptable, but if a work uses both methods, normalize the work to use the dominant method.</p>
</li>
<li>
<p>If listing temperature as a digit followed by “F.”, “C.”, or another abbreviation, remove the trailing period and precede the letter by a hair space (U+200A). Wrap the letter in <code class="html">&lt;abbr class="temperature"&gt;</code> styled with <code class="css">abbr.temperature{ font-variant: all-small-caps; }</code></p>
</li>
</ul>
<table>
<thead>
<tr>
<td>Result</td>
<td>Code</td>
</tr>
</thead>
<tbody>
<tr>
<td>
<p>It was −23.33° Celsius (or −10°&#x200a;<abbr class="temperature">F</abbr>) last night.</p>
</td>
<td><code class="css full">abbr.temperature{
font-variant: all-small-caps;
}</code> <code class="html full">It was −23.33° Celsius (or −10°<span class="utf">hairsp</span>&lt;abbr class="temperature"&gt;F&lt;/abbr&gt;) last night.</code></td>
</tr>
</tbody>
</table>
</section>
<section id="epigraphs">
<h2>Epigraphs in chapter headers</h2>
<ul>
<li>
<p>The source of the epigraph is set in small caps, without a leading em-dash and without a trailing period.</p>
</li>
</ul>
</section>
<section id="bridgehead">
<h2>Bridgeheads in chapter headers</h2>
<ul>
<li>
<p>Bridgeheads are centered in the header.</p>
</li>
<li>
<p>Always include a trailing period at the end of the bridgehead.</p>
</li>
</ul>
</section>
<section id="times">
<h2>Times</h2>
<ul>
<li>
<p>Times in a.m. and p.m. format should have the letters a.m. and p.m. set in lowercase, with periods, and without spaces. “a.m.” and “p.m.” should be wrapped in an <code class="html">&lt;abbr class="time"&gt;</code> tag. If “a.m.” or “p.m.” are the last word in a sentence, omit a second period, but add the “eoc” (end-of-clause) class to the <code class="html">&lt;abbr&gt;</code> tag.</p>
</li>
<li>
<p>Seperate times written in digits followed by a.m. or p.m. with a no-break space. If the time is written out in words, use a regular space.</p>
</li>
<li>
<p>Separate the hour and minute with a colon, not a period or comma.</p>
</li>
<li>
<p>Do not hyphenate times when spelled out, unless they appear before a noun.</p>
<figure class="text">
<p class="corrected">He arrived at five thirty.</p>
<p class="corrected">They took the twelve-thirty train.</p>
</figure>
</li>
<li>
<p>Military time that is spelled out (for example, in dialog) is set with dashes. Leading zeros are spelled out as “oh”.</p>
<figure class="text">
<p class="corrected">He arrived at oh-nine-hundred.</p>
</figure>
</li>
</ul>
<table>
<thead>
<tr>
<td>Result</td>
<td>Code</td>
</tr>
</thead>
<tbody>
<tr>
<td>
<p>He called at 6:40&nbsp; <abbr class="time">a.m.</abbr>, but she wasn’t up till seven <abbr class="time eoc">a.m.</abbr></p>
</td>
<td>
<code class="html full">He called at 6:40<span class="utf">nbsp</span>&lt;abbr class="time"&gt;a.m.&lt;/abbr&gt;, but she wasn’t up till seven &lt;abbr class="time eoc"&gt;a.m.&lt;/abbr&gt;</code>
<p class="note">Note how the last &lt;abbr&gt; contains the period for the entire sentence, and consequently also has the “eoc” (end-of-clause) class.</p>
</td>
</tr>
</tbody>
</table>
</section>
<section id="ampersands-in-names">
<h2>Ampersands in names</h2>
<ul>
<li>
<p>Ampersands in names of things like firms should be separated by no-break spaces.</p>
<figure class="text">
<p class="corrected">The firm of Hawkins<span class="utf">nbsp</span>&amp;amp;<span class="utf">nbsp</span>Harker.</p>
</figure>
</li>
</ul>
</section>
<section id="ligatures">
<h2>Ligatures</h2>
<p>Ligatures are symbols which combine two or more characters into one.</p>
<ul>
<li>
<p>Some older texts use ligatures like æ and œ to represent dipthongs. The modernize-spelling tool will replace many of these for you, but keep an eye out for other instances, particularly in Latin phrases and in classical names such as Œdipus. These should be either be replaced with “ae” and “oe” or with alternative modern spellings of the word they are in (check Merriam-Webster for these).</p>
</li>
<li>
<p>It’s very unlikely that you will encounter stylistic ligatures such as fl or ffi in the source text, but if you do they should be replaced by the individual characters they represent.</p>
</li>
</ul>
</section>
<section id="numbers-measurements-and-math">
<h2>Numbers, measurements, and math</h2>
<ul>
<li>
<p>Roman numerals should not be followed by periods, unless the period is there for grammatical reasons. Some European texts include a trailing period after Roman numerals as a matter of course; remove them.</p>
</li>
<li>
<p>Fractions should be written using the Unicode glyphs (½, ¼, ¾, etc., or U+00BC–U+00BE and U+2150–U+2189), if a glyph exists for your fraction.</p>
<figure class="text">
<p class="corrected">I need ¼ cup of sugar.</p>
</figure>
<p>If a glyph for a fraction doesn&rsquo;t exist, compose it using the fraction slash Unicode glyph (⁄ or U+2044) and superscript/subscript Unicode numbers. See <a href="https://en.wikipedia.org/wiki/Unicode_subscripts_and_superscripts">this Wikipedia entry for more details</a>.</p>
<figure class="text">
<p class="corrected">Roughly ⁶⁄₁₀ of a mile.</p>
</figure>
</li>
<li>
<p>Dimensions and equations should use the Unicode multiplication glyph (× or U+00D7) instead of the letters x or X.</p>
<figure class="text">
<p class="corrected">The board was 4 × 3 × 7 feet.</p>
</figure>
</li>
<li>
<p>Feet and inches in shorthand are set with the prime (′ or U+2032) or double prime (″ or U+2033) glyphs, <em>not</em> single or double quotes, and with a no-break space separating feet and inches.</p>
<figure class="text">
<p class="corrected">He was 6′<span class="utf">nbsp</span>1″ in height.</p>
</figure>
</li>
<li id="coordinates">
<p>Coordinates should be noted with the prime (′ or U+2032) or double prime (″ or U+2033) glyphs, <em>not</em> single or double quotes.</p>
<figure class="text">
<p class="corrected">lat. 27° 0′ N., long. 20° 1′ W.</p>
</figure>
<p>(Note that in the above example your font might render the two glyphs in the same way, but they’re different Unicode glyphs.)</p>
</li>
<li>
<p>Operators and operands in mathematical equations should be separated by a space.</p>
<p>Remember to use minus dashes (− or U+2212) instead of regular hyphens, both for negative numbers and for mathematical operations.</p>
<figure class="text">
<p class="corrected">6 − 2 + 2 = 6</p>
</figure>
</li>
<li>
<p>When forming a compound of a number + unit of measurement, and the measurement is abbreviated, separate the two with a no-break space, <em>not</em> a dash.</p>
<figure class="text">
<p class="corrected">A 12<span class="utf">nbsp</span>mm pistol.</p>
</figure>
</li>
</ul>
</section>
<section id="endnotes">
<h2>Footnotes and endnotes</h2>
<ul>
<li>
<p>All footnotes should be converted to a single endnotes file. For more information on the structure of that file, see our <a href="/contribute/semantics#endnotes">structure and semantics manual</a>.</p>
</li>
<li>
<p>“Ibid.” is a Latinism commonly used in endnotes to indicate that the source for a quotation or reference is the same as the last-mentioned source.</p>
<p>In the case where the last-mentioned source is in the previous endnote, we must replace Ibid. by the full reference; since ebooks use popup endnotes, “Ibid.” becomes meaningless in that context.</p>
<p>In the case where the last-mentioned source is in the same endnote as Ibid., we can leave Ibid. untouched.</p>
</li>
<li>
<p>The endnote reference number goes after ending punctuation. If the endnote references an entire sentence in quotation marks, or the last word in a sentence in quotation marks, then the endnote reference number goes outside the quotation marks.</p>
</li>
<li>
<p>Within an endnote, a backlink to where the endnote occurred in the text must be the last item. It is preceded by exactly one space.</p>
</li>
</ul>
</section>
<section id="legal">
<h2>Legal cases and terms</h2>
<ul>
<li>
<p>Legal cases are set in italic. Either “versus” or “v.” are acceptable; if using “v.”, a period must follow the “v.”</p>
<figure class="text">
<p class="corrected">He prosecuted <i>Johnson v. Smith</i>.</p>
</figure>
</li>
</ul>
</section>
<aside class="alert">
<p>Standard Ebooks is a brand-new project&mdash;this manual is a pre-alpha, and much of it is incomplete. If you have a question, need clarification, or run in to an issue not yet covered here, please <a href="https://groups.google.com/forum/#!forum/standardebooks">contact us</a> so we can update this manual.</p>
</aside>
</article>
</main>
<?= Template::Footer() ?>

304
www/css/core.css
View file

@ -192,7 +192,7 @@ main p, main ul, main ol, main li, main blockquote{
margin-top: 1rem;
}
main p:first-child, main ul:first-child, main ol:first-child, main ul li:first-child, main ol li:first-child, main blockquote:first-child, main code:first-child{
main p:first-child, main ul:first-child, main ol:first-child, main ul li:first-child, main ol li:first-child, main blockquote:first-child{
margin-top: 0;
}
@ -204,7 +204,7 @@ ol ol, ol ul, ul ul, ul ol{
margin-left: 1.2rem;
}
h1,h2,h3,h4,h5,h6,code,.ebook h1 + p{
h1,h2,h3,h4,h5,h6,.ebook h1 + p{
-webkit-hyphens: none;
hyphens: none;
}
@ -1176,181 +1176,6 @@ ul.tags li + li{
margin-left: .5rem;
}
code.tag,
code.path,
code.program,
code.bash,
code.regex,
code.html,
code.ietf,
code.css,
code.marc{
border: 1px solid rgba(255,255,255,.25);
background: #333;
border-radius: .25rem;
white-space: pre-wrap;
padding: 0 .25rem;
color: #fff;
}
figure code.html,
figure code.css{
padding: 1rem;
background: #333;
border: none;
text-align: left;
color: #fff !important; /* in case code highlighting fails */
}
code.html.full,
code.css.full{
border: none;
display: block;
padding: 1rem;
background: #333;
text-align: left;
color: #fff !important; /* in case code highlighting fails */
}
code.full{
margin-top: 1rem;
color: #fff !important; /* in case code highlighting fails */
}
code.full::before{
display: block;
border-bottom: 1px dashed var(--sub-text);
padding-bottom: .5rem;
margin-bottom: .5rem;
font-weight: bold;
line-height: 1;
}
code.html.full::before{
content: 'HTML';
}
code.css.full::before{
content: 'CSS';
}
code{
font-family: 'Source Code Pro', monospace;
font-size: .8rem;
}
code.terminal{
color: #fff;
background-color: #444;
font-family: 'Source Code Pro', monospace;
text-align: left;
padding: 1rem 1rem 1rem 3rem;
border-radius: .25rem;
position: relative;
display: block;
margin-top: 1rem;
overflow: auto;
}
code.terminal::before{
content: url('/images/terminal.svg');
height: 1rem;
width: 1rem;
top: 1.15rem;
left: 1rem;
position: absolute;
}
code.raw{
white-space: pre;
}
code.terminal span{
display: block;
}
code.terminal span::before{
margin-right: .5rem;
color: #56DA55;
font-weight: bold;
display: inline;
}
code.terminal > span::before{
content:'user@localhost>';
}
blockquote,
figure.text{
background: rgba(255,255,255,.25);
border: 1px solid rgba(255,255,255,.25);
padding: 1rem;
border-radius: .25rem;
}
blockquote{
font-style: italic;
}
blockquote mark.error{
background: #CF4647;
padding: .2rem;
}
table{
width: 100%;
text-align: left;
margin-top: 1rem;
}
table code.full{
display: block;
white-space: normal !important;
}
table code.full{
white-space: pre-wrap !important;
}
table td{
vertical-align: top;
padding: 1rem;
}
table td:first-child{
width: 25%;
}
table td + td{
padding-left: 10px;
}
table p{
margin: 0;
}
table thead{
border-bottom: 3px double var(--sub-text);
font-weight: bold;
}
abbr{
white-space: nowrap;
}
abbr.acronym{
font-variant: all-small-caps;
}
abbr.temperature,
abbr.era{
font-variant: all-small-caps;
}
h3 abbr.initialism{
font-variant: normal;
}
figure img{
border-radius: .25rem;
border: 1px solid var(--border);
@ -1366,82 +1191,6 @@ figure p + p{
margin-top: 15px;
}
figure p.wrong{
text-decoration-line: underline;
text-decoration-style: wavy;
text-decoration-color: #CF4647;
}
figure p.wrong:before,
figure.wrong:before{
font-family: "FontAwesome";
content: "\f00d";
font-size: 1.5rem;
width: 1.5rem;
line-height: 1;
margin-right: .5rem;
color: #CF4647;
text-shadow: 1px 1px 0 rgba(0, 0, 0, .1);
display: inline-block;
}
figure p.corrected:before,
figure.corrected:before{
font-family: "FontAwesome";
content: "\f00c";
font-size: 1.5rem;
line-height: 1;
margin-right: .5rem;
width: 1.5rem;
color: #79BD9A;
text-shadow: 1px 1px 0 rgba(0, 0, 0, .1);
display: inline-block;
}
figure.wrong:before,
figure.corrected:before{
display: flex;
margin-right: 0;
align-self: stretch;
align-items: center;
justify-content: center;
padding: 0 .5rem;
border-top-left-radius: .25rem;
border-bottom-left-radius: .25rem;
}
figure.wrong:before{
background: #762729;
}
figure.corrected:before{
background: #406451;
}
figure.wrong code{
background: #550000 url('/images/stripes-dark.svg');
}
figure.wrong,
figure.corrected{
display: flex;
align-items: center;
}
figure.wrong code,
figure.corrected code{
flex-grow: 1;
border-top-left-radius: 0;
border-bottom-left-radius: 0;
}
.warning{
font-size: 2rem;
font-weight: bold;
text-align: center;
font-style: normal;
}
main.ebooks nav{
display: flex;
justify-content: center;
@ -1546,24 +1295,6 @@ label.search::before{
text-shadow: 1px 1px 0 rgba(255, 255, 255, .5);
}
.utf{
border: 1px solid var(--body-text);
padding: .1rem;
line-height: 1;
margin: 0 .1rem;
font-size: .5rem;
display: inline-block;
font-family: monospace;
vertical-align: middle;
margin-top: -3px; /* to match poor crimson alignment */
}
figure code.html .utf,
code.full .utf{
border-color: #fff;
margin-top: 0;
}
article nav ol li:not(:first-child):not(:last-child):not(.highlighted),
main.ebooks nav ol li:not(:first-child):not(:last-child):not(.highlighted){
display: none;
@ -1592,28 +1323,6 @@ main.ebooks nav ol li.highlighted:nth-last-child(2)::after{
display: none;
}
#producing-an-ebook > ol {
counter-reset: item;
margin-left: 0;
padding-left: 0;
list-style: none;
}
#producing-an-ebook > ol > li::before {
float: left;
content: counter(item) ".";
counter-increment: item;
width: 4rem;
text-align: right;
margin-left: -5.5rem;
font-size: 1.2rem;
font-family: 'League Spartan', sans-serif;
line-height: 1.2;
letter-spacing: 1px;
text-transform: uppercase;
}
@media(max-width: 1100px){
article.ebook header{
width: calc(100% + 4rem);
@ -1876,15 +1585,6 @@ main.ebooks nav ol li.highlighted:nth-last-child(2)::after{
color: rgba(255, 255, 255, .75);
}
blockquote,
figure.text{
background: rgba(0,0,0,.25);
}
code.terminal{
background-color: var(--light-body-text);
}
main.ebooks > ol img:hover{
box-shadow: 3px 3px 1px rgba(0, 0, 0, .5);
}

345
www/css/manual.css
View file

@ -1,5 +1,318 @@
@import url("monokai.css");
main code:first-child{
margin-top: 0;
}
code{
hyphens: none;
}
blockquote,
figure.text{
background: rgba(255,255,255,.25);
border: 1px solid rgba(255,255,255,.25);
padding: 1rem;
border-radius: .25rem;
}
blockquote{
font-style: italic;
}
blockquote mark.error{
background: #CF4647;
padding: .2rem;
}
table{
width: 100%;
text-align: left;
margin-top: 1rem;
}
table code.full{
display: block;
white-space: normal !important;
}
table code.full{
white-space: pre-wrap !important;
}
table td{
vertical-align: top;
padding: 1rem;
}
table td:first-child{
width: 25%;
}
table td + td{
padding-left: 10px;
}
table p{
margin: 0;
}
table thead{
border-bottom: 3px double var(--sub-text);
font-weight: bold;
}
abbr{
white-space: nowrap;
}
abbr.acronym{
font-variant: all-small-caps;
}
abbr.temperature,
abbr.era{
font-variant: all-small-caps;
}
h3 abbr.initialism{
font-variant: normal;
}
code.string,
code.tag,
code.path,
code.program,
code.bash,
code.regex,
code.html,
code.xml,
code.ietf,
code.css,
code.marc{
border: 1px solid rgba(255,255,255,.25);
background: #333;
border-radius: .25rem;
white-space: nowrap;
padding: 0 .25rem;
color: #fff;
margin: 0 .2rem;
}
figure code.xml,
figure code.html,
figure code.css{
padding: 1rem;
background: #333;
border: none;
text-align: left;
color: #fff !important; /* in case code highlighting fails */
}
code.xml.full,
code.html.full,
code.css.full{
border: none;
display: block;
padding: 1rem;
background: #333;
text-align: left;
color: #fff !important; /* in case code highlighting fails */
}
code.full{
margin-top: 1rem;
color: #fff !important; /* in case code highlighting fails */
}
code.full::before{
display: block;
border-bottom: 1px dashed var(--sub-text);
padding-bottom: .5rem;
margin-bottom: .5rem;
font-weight: bold;
line-height: 1;
}
code.xml.full::before{
content: 'XML';
}
code.html.full::before{
content: 'HTML';
}
code.css.full::before{
content: 'CSS';
}
code{
font-family: 'Source Code Pro', monospace;
font-size: .8rem;
}
code.terminal{
color: #fff;
background-color: #444;
font-family: 'Source Code Pro', monospace;
text-align: left;
padding: 1rem 1rem 1rem 3rem;
border-radius: .25rem;
position: relative;
display: block;
margin-top: 1rem;
overflow: auto;
}
code.terminal::before{
content: url('/images/terminal.svg');
height: 1rem;
width: 1rem;
top: 1.15rem;
left: 1rem;
position: absolute;
}
code.raw{
white-space: pre;
}
code.terminal span{
display: block;
}
code.terminal span::before{
margin-right: .5rem;
color: #56DA55;
font-weight: bold;
display: inline;
}
code.terminal > span::before{
content:'user@localhost>';
}
.utf{
border: 1px solid var(--body-text);
padding: .1rem;
line-height: 1;
margin: 0 .2rem;
display: inline-block;
font-family: monospace;
vertical-align: middle;
margin-top: -3px; /* to match poor crimson alignment */
}
figure code.html .utf,
code.full .utf{
border-color: #fff;
margin-top: 0;
}
#producing-an-ebook > ol li::marker{
font-weight: bold;
font-family: 'League Spartan', sans-serif;
}
#producing-an-ebook > ol {
counter-reset: item;
margin-left: 0;
padding-left: 0;
list-style: none;
}
#producing-an-ebook > ol > li::before {
float: left;
content: counter(item) ".";
counter-increment: item;
width: 4rem;
text-align: right;
margin-left: -5.5rem;
font-size: 1.2rem;
font-family: 'League Spartan', sans-serif;
line-height: 1.2;
letter-spacing: 1px;
text-transform: uppercase;
}
.warning{
font-size: 2rem;
font-weight: bold;
text-align: center;
font-style: normal;
}
figure p.wrong{
text-decoration-line: underline;
text-decoration-style: wavy;
text-decoration-color: #CF4647;
}
figure p.wrong:before,
figure.wrong:before{
font-family: "FontAwesome";
content: "\f00d";
font-size: 1.5rem;
width: 1.5rem;
line-height: 1;
margin-right: .5rem;
color: #CF4647;
text-shadow: 1px 1px 0 rgba(0, 0, 0, .1);
display: inline-block;
}
figure p.corrected:before,
figure.corrected:before{
font-family: "FontAwesome";
content: "\f00c";
font-size: 1.5rem;
line-height: 1;
margin-right: .5rem;
width: 1.5rem;
color: #79BD9A;
text-shadow: 1px 1px 0 rgba(0, 0, 0, .1);
display: inline-block;
}
figure.wrong:before,
figure.corrected:before{
display: flex;
margin-right: 0;
align-self: stretch;
align-items: center;
justify-content: center;
padding: 0 .5rem;
border-top-left-radius: .25rem;
border-bottom-left-radius: .25rem;
}
figure.wrong:before{
background: #762729;
}
figure.corrected:before{
background: #406451;
}
figure.wrong code{
background: #550000 url('/images/stripes-dark.svg');
}
figure.wrong,
figure.corrected{
display: flex;
align-items: center;
}
figure.wrong code,
figure.corrected code{
flex-grow: 1;
border-top-left-radius: 0;
border-bottom-left-radius: 0;
}
.manual p{
text-align: left;
}
@ -132,8 +445,22 @@
margin-top: -3px; /* to match poor crimson alignment */
}
code.bash > span{
color: var(--dark-button-highlight);
code.terminal b,
code.bash b{
font-weight: normal;
color: #4a9906;
}
code.terminal i,
code.bash i{
font-style: normal;
color: #c4a000;
}
code.terminal i.glob,
code.bash i.glob{
font-style: normal;
color: #719ece;
}
figure code.html .ws,
@ -189,6 +516,7 @@ main.manual > nav ol{
list-style: none;
}
figure code.xml,
figure code.html,
figure code.css{
white-space: pre;
@ -221,7 +549,7 @@ figure code.css{
}
main.manual > article > section,
main.manual nav + h1{
main.manual nav + article h1{
margin-top: 0;
}
@ -235,3 +563,14 @@ figure code.css{
margin-left: 2rem;
}
}
@media(prefers-color-scheme: dark){
blockquote,
figure.text{
background: rgba(0,0,0,.25);
}
code.terminal{
background-color: var(--light-body-text);
}
}

2
www/index.php
View file

@ -14,7 +14,7 @@ require_once('Core.php');
<div>
<div>
<p>Other free ebooks don’t put much effort into professional-quality typography: they use "straight" quotes instead of “curly” quotes, they ignore details like em- and en-dashes, and they look more like early-90&rsquo;s web pages instead of actual books.</p>
<p>The Standard Ebooks project applies a rigorous and modern <a href="/contribute/typography">typography manual</a> when developing each and every ebook to ensure they meet a professional-grade and consistent typographical standard. Our ebooks look <em>good</em>.</p>
<p>The Standard Ebooks project applies a rigorous and modern <a href="/manual">style manual</a> when developing each and every ebook to ensure they meet a professional-grade and consistent typographical standard. Our ebooks look <em>good</em>.</p>
</div>
<figure class="stacked">
<img alt="An example of bad typography." class="bottom" src="/images/typography-bad.png"> <img alt="An example of Standard Ebooks typography." class="top" src="/images/typography-good.png"> <img alt="An arrow pointing from bad typography to good typography." class="arrow" src="/images/arrow-down.png">

10
www/js/core.js
View file

@ -1,10 +0,0 @@
'use strict';
document.addEventListener('DOMContentLoaded', function(){
if(hljs){
let blocks = document.querySelectorAll('code.html.full, code.css.full, figure code.html');
for(let i = 0; i < blocks.length; i++){
hljs.highlightBlock(blocks[i]);
}
}
});

1646
www/js/highlight.js/CHANGES.md
View file

File diff suppressed because it is too large Load diff

24
www/js/highlight.js/LICENSE
View file

@ -1,24 +0,0 @@
Copyright (c) 2006, Ivan Sagalaev
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
* Neither the name of highlight.js nor the names of its contributors
may be used to endorse or promote products derived from this software
without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

150
www/js/highlight.js/README.md
View file

@ -1,150 +0,0 @@
# Highlight.js
[![Build Status](https://travis-ci.org/isagalaev/highlight.js.svg?branch=master)](https://travis-ci.org/isagalaev/highlight.js)
Highlight.js is a syntax highlighter written in JavaScript. It works in
the browser as well as on the server. It works with pretty much any
markup, doesn’t depend on any framework and has automatic language
detection.
## Getting Started
The bare minimum for using highlight.js on a web page is linking to the
library along with one of the styles and calling
[`initHighlightingOnLoad`][1]:
```html
<link rel="stylesheet" href="/path/to/styles/default.css">
<script src="/path/to/highlight.pack.js"></script>
<script>hljs.initHighlightingOnLoad();</script>
```
This will find and highlight code inside of `<pre><code>` tags; it tries
to detect the language automatically. If automatic detection doesn’t
work for you, you can specify the language in the `class` attribute:
```html
<pre><code class="html">...</code></pre>
```
The list of supported language classes is available in the [class
reference][2]. Classes can also be prefixed with either `language-` or
`lang-`.
To disable highlighting altogether use the `nohighlight` class:
```html
<pre><code class="nohighlight">...</code></pre>
```
## Custom Initialization
When you need a bit more control over the initialization of
highlight.js, you can use the [`highlightBlock`][3] and [`configure`][4]
functions. This allows you to control *what* to highlight and *when*.
Here’s an equivalent way to calling [`initHighlightingOnLoad`][1] using
jQuery:
```javascript
$(document).ready(function() {
$('pre code').each(function(i, block) {
hljs.highlightBlock(block);
});
});
```
You can use any tags instead of `<pre><code>` to mark up your code. If
you don't use a container that preserve line breaks you will need to
configure highlight.js to use the `<br>` tag:
```javascript
hljs.configure({useBR: true});
$('div.code').each(function(i, block) {
hljs.highlightBlock(block);
});
```
For other options refer to the documentation for [`configure`][4].
## Web Workers
You can run highlighting inside a web worker to avoid freezing the browser
window while dealing with very big chunks of code.
In your main script:
```javascript
addEventListener('load', function() {
var code = document.querySelector('#code');
var worker = new Worker('worker.js');
worker.onmessage = function(event) { code.innerHTML = event.data; }
worker.postMessage(code.textContent);
})
```
In worker.js:
```javascript
onmessage = function(event) {
importScripts('<path>/highlight.pack.js');
var result = self.hljs.highlightAuto(event.data);
postMessage(result.value);
}
```
## Getting the Library
You can get highlight.js as a hosted, or custom-build, browser script or
as a server module. Right out of the box the browser script supports
both AMD and CommonJS, so if you wish you can use RequireJS or
Browserify without having to build from source. The server module also
works perfectly fine with Browserify, but there is the option to use a
build specific to browsers rather than something meant for a server.
Head over to the [download page][5] for all the options.
**Don't link to GitHub directly.** The library is not supposed to work straight
from the source, it requires building. If none of the pre-packaged options
work for you refer to the [building documentation][6].
**The CDN-hosted package doesn't have all the languages.** Otherwise it'd be
too big. If you don't see the language you need in the ["Common" section][5],
it can be added manually:
```html
<script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.4.0/languages/go.min.js"></script>
```
**On Almond.** You need to use the optimizer to give the module a name. For
example:
```
r.js -o name=hljs paths.hljs=/path/to/highlight out=highlight.js
```
## License
Highlight.js is released under the BSD License. See [LICENSE][7] file
for details.
## Links
The official site for the library is at <https://highlightjs.org/>.
Further in-depth documentation for the API and other topics is at
<http://highlightjs.readthedocs.io/>.
Authors and contributors are listed in the [AUTHORS.en.txt][8] file.
[1]: http://highlightjs.readthedocs.io/en/latest/api.html#inithighlightingonload
[2]: http://highlightjs.readthedocs.io/en/latest/css-classes-reference.html
[3]: http://highlightjs.readthedocs.io/en/latest/api.html#highlightblock-block
[4]: http://highlightjs.readthedocs.io/en/latest/api.html#configure-options
[5]: https://highlightjs.org/download/
[6]: http://highlightjs.readthedocs.io/en/latest/building-testing.html
[7]: https://github.com/isagalaev/highlight.js/blob/master/LICENSE
[8]: https://github.com/isagalaev/highlight.js/blob/master/AUTHORS.en.txt

2
www/js/highlight.js/highlight.pack.js
View file

File diff suppressed because one or more lines are too long

72
www/js/highlight.js/styles/paraiso-dark.css
View file

@ -1,72 +0,0 @@
/*
Paraíso (dark)
Created by Jan T. Sott (http://github.com/idleberg)
Inspired by the art of Rubens LP (http://www.rubenslp.com.br)
*/
/* Paraíso Comment */
.hljs-comment,
.hljs-quote {
color: #8d8687;
}
/* Paraíso Red */
.hljs-variable,
.hljs-template-variable,
.hljs-tag,
.hljs-name,
.hljs-selector-id,
.hljs-selector-class,
.hljs-regexp,
.hljs-link,
.hljs-meta {
color: #ef6155;
}
/* Paraíso Orange */
.hljs-number,
.hljs-built_in,
.hljs-builtin-name,
.hljs-literal,
.hljs-type,
.hljs-params,
.hljs-deletion {
color: #f99b15;
}
/* Paraíso Yellow */
.hljs-title,
.hljs-section,
.hljs-attribute {
color: #fec418;
}
/* Paraíso Green */
.hljs-string,
.hljs-symbol,
.hljs-bullet,
.hljs-addition {
color: #48b685;
}
/* Paraíso Purple */
.hljs-keyword,
.hljs-selector-tag {
color: #815ba4;
}
.hljs {
display: block;
overflow-x: auto;
background: #2f1e2e;
color: #a39e9b;
padding: 0.5em;
}
.hljs-emphasis {
font-style: italic;
}
.hljs-strong {
font-weight: bold;
}

10
www/manual/1.0.0/1-code-style.php
View file

File diff suppressed because one or more lines are too long

43
www/manual/1.0.0/10-art-and-images.php
View file

File diff suppressed because one or more lines are too long

48
www/manual/1.0.0/2-filesystem.php
View file

File diff suppressed because one or more lines are too long

8
www/manual/1.0.0/3-the-structure-of-an-ebook.php
View file

File diff suppressed because one or more lines are too long

50
www/manual/1.0.0/4-semantics.php
View file

File diff suppressed because one or more lines are too long

38
www/manual/1.0.0/5-general-xhtml-patterns.php
View file

File diff suppressed because one or more lines are too long

928
www/manual/1.0.0/6-high-level-structural-patterns.php
View file

File diff suppressed because one or more lines are too long

46
www/manual/1.0.0/6-standard-ebooks-section-patterns.php
View file

File diff suppressed because one or more lines are too long

68
www/manual/1.0.0/7-high-level-structural-patterns.php
View file

File diff suppressed because one or more lines are too long

158
www/manual/1.0.0/7-table-of-contents-patterns.php
View file

File diff suppressed because one or more lines are too long

52
www/manual/1.0.0/8-typography.php
View file

File diff suppressed because one or more lines are too long

82
www/manual/1.0.0/9-metadata.php
View file

File diff suppressed because one or more lines are too long

3
www/manual/1.0.0/index.php
View file

@ -10,8 +10,9 @@ require_once('Core.php');
<p>If a rule is not covered in this manual, the directive is to follow the rules in the Chicago Manual of Style, 16th edition.</p>
<p>These rules align closely with the style rules used in modern publishing. However, books from the turn of the 20th century and older may appear to follow a different set of rules. Producers are expected to adjust those older conventions to match this manual.</p>
<p>Having said that, literature is a complex and multifaceted art, and in the process of converting older books some may call for a bending of a rule, or for an outright exception. Producers should not feel bound to slavishly follow these directives if a book seems to cry out for an exception. As Ralph Waldo Emerson once wrote, “a foolish consistency is the hobgoblin of little minds.” If unsure, producers are urged and welcomed to contact the <a href="https://groups.google.com/group/standardebooks/">Standard Ebooks Editor in Chief</a> for final-word guidance.</p>
<p>To contribute, please <a href="https://github.com/standardebooks/manual">visit the GitHub repository</a> or <a href="https://groups.google.com/group/standardebooks/">contact the mailing list</a>.</p>
<p>Editor-in-chief: Alex Cabal</p>
<p>Contributors (in alpha order): David Grigg, B. Timothy Keith, Vince Rice, Emma Sweeney, Robin Whittleton, Kenny Williams.</p>
<p>Contributors (in alpha order): David Grigg, B. Timothy Keith, Vince Rice, Emma Sweeney, Robin Whittleton.</p>
<section>
<h2>Table of Contents</h2>
<ol type="1">

11
www/manual/index.php
View file

@ -8,5 +8,14 @@ sort($dirs);
$currentManual = str_replace(WEB_ROOT, '', $dirs[sizeof($dirs) - 1]);
$url = HttpInput::GetString('url', true, '');
$url = preg_replace('|^/|ius', '', $url);
$url = preg_replace('|\.php$|ius', '', $url);
$url = preg_replace('|/$|ius', '', $url);
if($url != ''){
$url = '/' . $url;
}
http_response_code(302);
header('Location: ' . $currentManual);
header('Location: ' . $currentManual . $url);