From d78d2ee4022b54e62ad4927d8b0438380031c344 Mon Sep 17 00:00:00 2001 From: Alex Cabal Date: Thu, 12 Mar 2020 22:10:14 -0500 Subject: [PATCH] Add the first draft of the unified manual --- config/apache/standardebooks.org.conf | 2 +- config/apache/standardebooks.test.conf | 2 +- templates/Header.php | 7 + www/css/core.css | 63 -- www/css/manual.css | 163 +++ www/css/monokai.css | 65 ++ www/manual/1.0/art.php | 233 +++++ www/manual/1.0/code-style.php | 182 ++++ www/manual/1.0/filesystem.php | 231 +++++ www/manual/1.0/general-xhtml-patterns.php | 240 +++++ .../1.0/high-level-structural-patterns.php | 927 ++++++++++++++++++ www/manual/1.0/index.php | 25 + www/manual/1.0/metadata.php | 350 +++++++ www/manual/1.0/semantics.php | 116 +++ www/manual/1.0/table-of-contents-patterns.php | 158 +++ www/manual/1.0/the-structure-of-an-ebook.php | 109 ++ www/manual/1.0/typography.php | 697 +++++++++++++ .../1.0/uncategorized-art-resources.php | 121 +++ 18 files changed, 3626 insertions(+), 65 deletions(-) create mode 100644 www/css/manual.css create mode 100644 www/css/monokai.css create mode 100644 www/manual/1.0/art.php create mode 100644 www/manual/1.0/code-style.php create mode 100644 www/manual/1.0/filesystem.php create mode 100644 www/manual/1.0/general-xhtml-patterns.php create mode 100644 www/manual/1.0/high-level-structural-patterns.php create mode 100644 www/manual/1.0/index.php create mode 100644 www/manual/1.0/metadata.php create mode 100644 www/manual/1.0/semantics.php create mode 100644 www/manual/1.0/table-of-contents-patterns.php create mode 100644 www/manual/1.0/the-structure-of-an-ebook.php create mode 100644 www/manual/1.0/typography.php create mode 100644 www/manual/1.0/uncategorized-art-resources.php diff --git a/config/apache/standardebooks.org.conf b/config/apache/standardebooks.org.conf index 52e1a91d..2c110b35 100644 --- a/config/apache/standardebooks.org.conf +++ b/config/apache/standardebooks.org.conf @@ -155,7 +155,7 @@ Define domain standardebooks.org RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_URI} !-f RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_URI} !-d RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_URI}.php -f - RewriteRule ^([^\.]+)$ $1.php [QSA] + RewriteRule ^(.+)$ $1.php [QSA] # End PHP-FPM configuration # Received: /filename and /filename.xml exists in filesystem; Result: rewrite to /filename.xml and end request diff --git a/config/apache/standardebooks.test.conf b/config/apache/standardebooks.test.conf index 7875009b..63d64c7e 100644 --- a/config/apache/standardebooks.test.conf +++ b/config/apache/standardebooks.test.conf @@ -154,7 +154,7 @@ Define domain standardebooks.test RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_URI} !-f RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_URI} !-d RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_URI}.php -f - RewriteRule ^([^\.]+)$ $1.php [QSA] + RewriteRule ^(.+)$ $1.php [QSA] # End PHP-FPM configuration # Received: /filename and /filename.xml exists in filesystem; Result: rewrite to /filename.xml and end request diff --git a/templates/Header.php b/templates/Header.php index 1fbd5cd4..2f88c28d 100644 --- a/templates/Header.php +++ b/templates/Header.php @@ -12,6 +12,10 @@ if(!isset($description)){ $description = ''; } +if(!isset($manual)){ + $manual = false; +} + if(!isset($js)){ $js = false; } @@ -24,6 +28,9 @@ if(!isset($js)){ + + + diff --git a/www/css/core.css b/www/css/core.css index 2d3874ce..76e1562e 100644 --- a/www/css/core.css +++ b/www/css/core.css @@ -1609,69 +1609,6 @@ main.ebooks nav ol li.highlighted:nth-last-child(2)::after{ text-transform: uppercase; } -.manual section, -.manual ol{ - counter-reset: item; -} - -.manual section{ - margin-top: 2rem; -} - -.manual section section{ - margin-left: 2rem; -} - -.manual section ol{ - margin-top: 1rem; - margin-left: 2rem; -} - -.manual section + section, -.manual ol + section{ - counter-reset: none; -} - -.manual ol li{ - list-style: none; -} - -.manual section::before, -.manual ol li::before{ - counter-increment: item; - content: counters(item, "."); - font-style: italic; - position: absolute; - margin-left: -3rem; -} - -.manual section::before{ - font-family: 'League Spartan', sans-serif; - line-height: 1.2; -} - -.manual > section::before{ - font-size: 1.2rem; -} - -.manual h2, -.manual h3, -.manual h4{ - margin-top: 0; -} - -.manual figure p{ - hyphens: none; -} - -.manual table td:first-child{ - width: auto; -} - -.manual table td code.path{ - white-space: nowrap; -} - @media(max-width: 1100px){ article.ebook header{ width: calc(100% + 4rem); diff --git a/www/css/manual.css b/www/css/manual.css new file mode 100644 index 00000000..909217d9 --- /dev/null +++ b/www/css/manual.css @@ -0,0 +1,163 @@ +@import url("monokai.css"); + +.manual > section[data-start-at='1']{ + counter-reset: root 1; +} + +.manual > section[data-start-at='2']{ + counter-reset: root 2; +} + +.manual > section[data-start-at='3']{ + counter-reset: root 3; +} + +.manual > section[data-start-at='4']{ + counter-reset: root 4; +} + +.manual > section[data-start-at='5']{ + counter-reset: root 5; +} + +.manual > section[data-start-at='6']{ + counter-reset: root 6; +} + +.manual > section[data-start-at='7']{ + counter-reset: root 7; +} + +.manual > section[data-start-at='8']{ + counter-reset: root 8; +} + +.manual > section[data-start-at='9']{ + counter-reset: root 9; +} + +.manual > section[data-start-at='10']{ + counter-reset: root 10; +} + +.manual > section[data-start-at='11']{ + counter-reset: root 11; +} + +.manual > section[data-start-at='12']{ + counter-reset: root 12; +} + +.manual > section[data-start-at='13']{ + counter-reset: root 13; +} + +.manual > section[data-start-at='14']{ + counter-reset: root 14; +} + +.manual > section[data-start-at='15']{ + counter-reset: root 15; +} + +.manual > section section, +.manual ol{ + counter-reset: item; +} + +.manual section{ + margin-top: 2rem; +} + +.manual section section{ + margin-left: 2rem; +} + +.manual section ol{ + margin-top: 1rem; + margin-left: 2rem; +} + +.manual section + section, +.manual ol + section{ + counter-reset: none; +} + +.manual section[data-start-at] ol > li{ + list-style: none; +} + +.manual > section[data-start-at]::before{ + content: counters(root, '.'); + position: absolute; + width: 10rem; + text-align: right; + margin-left: -11rem; + margin-top: 2rem; + font-size: 2rem; +} + +.manual h1 + section > h2:first-child{ + margin-top: 0; +} + +.manual > section[data-start-at] section::before, +.manual section[data-start-at] ol > li::before{ + counter-increment: item; + content: counters(root, '.') '.' counters(item, "."); + position: absolute; + width: 10rem; + margin-left: -10.5rem; + text-align: right; + font-family: 'League Spartan', sans-serif; + font-weight: normal; +} + +.manual .no-numbering::before{ + content: none !important; + display: none !important; +} + +.manual section[data-start-at] ol > li::before{ + font-size: .75rem; + margin-top: .15rem; +} + +.manual > section[data-start-at] > section::before{ + font-style: normal; + margin-left: -11.5rem; +} + +.manual section::before{ + font-family: 'League Spartan', sans-serif; + line-height: 1.2; +} + +.manual > section::before{ + font-size: 1.2rem; +} + +.manual h2, +.manual h3, +.manual h4, +.manual h5, +.manual h6{ + margin-top: 0; +} + +.manual figure p{ + hyphens: none; +} + +.manual table td:first-child{ + width: auto; +} + +.manual table td code.path{ + white-space: nowrap; +} + +.manual aside.tip{ + font-style: italic; + margin: 1rem; +} diff --git a/www/css/monokai.css b/www/css/monokai.css new file mode 100644 index 00000000..ff0b5d77 --- /dev/null +++ b/www/css/monokai.css @@ -0,0 +1,65 @@ +.hll { background-color: #49483e } +.c { color: #75715e } /* Comment */ +.err { color: #960050; background-color: #1e0010 } /* Error */ +.k { color: #66d9ef } /* Keyword */ +.l { color: #ae81ff } /* Literal */ +.n { color: #f8f8f2 } /* Name */ +.o { color: #f92672 } /* Operator */ +.p { color: #f8f8f2 } /* Punctuation */ +.ch { color: #75715e } /* Comment.Hashbang */ +.cm { color: #75715e } /* Comment.Multiline */ +.cp { color: #75715e } /* Comment.Preproc */ +.cpf { color: #75715e } /* Comment.PreprocFile */ +.c1 { color: #75715e } /* Comment.Single */ +.cs { color: #75715e } /* Comment.Special */ +.gd { color: #f92672 } /* Generic.Deleted */ +.ge { font-style: italic } /* Generic.Emph */ +.gi { color: #a6e22e } /* Generic.Inserted */ +.gs { font-weight: bold } /* Generic.Strong */ +.gu { color: #75715e } /* Generic.Subheading */ +.kc { color: #66d9ef } /* Keyword.Constant */ +.kd { color: #66d9ef } /* Keyword.Declaration */ +.kn { color: #f92672 } /* Keyword.Namespace */ +.kp { color: #66d9ef } /* Keyword.Pseudo */ +.kr { color: #66d9ef } /* Keyword.Reserved */ +.kt { color: #66d9ef } /* Keyword.Type */ +.ld { color: #e6db74 } /* Literal.Date */ +.m { color: #ae81ff } /* Literal.Number */ +.s { color: #e6db74 } /* Literal.String */ +.na { color: #a6e22e } /* Name.Attribute */ +.nb { color: #f8f8f2 } /* Name.Builtin */ +.nc { color: #a6e22e } /* Name.Class */ +.no { color: #66d9ef } /* Name.Constant */ +.nd { color: #a6e22e } /* Name.Decorator */ +.ni { color: #f8f8f2 } /* Name.Entity */ +.ne { color: #a6e22e } /* Name.Exception */ +.nf { color: #a6e22e } /* Name.Function */ +.nl { color: #f8f8f2 } /* Name.Label */ +.nn { color: #f8f8f2 } /* Name.Namespace */ +.nx { color: #a6e22e } /* Name.Other */ +.py { color: #f8f8f2 } /* Name.Property */ +.nt { color: #f92672 } /* Name.Tag */ +.nv { color: #f8f8f2 } /* Name.Variable */ +.ow { color: #f92672 } /* Operator.Word */ +.w { color: #f8f8f2 } /* Text.Whitespace */ +.mb { color: #ae81ff } /* Literal.Number.Bin */ +.mf { color: #ae81ff } /* Literal.Number.Float */ +.mh { color: #ae81ff } /* Literal.Number.Hex */ +.mi { color: #ae81ff } /* Literal.Number.Integer */ +.mo { color: #ae81ff } /* Literal.Number.Oct */ +.sb { color: #e6db74 } /* Literal.String.Backtick */ +.sc { color: #e6db74 } /* Literal.String.Char */ +.sd { color: #e6db74 } /* Literal.String.Doc */ +.s2 { color: #e6db74 } /* Literal.String.Double */ +.se { color: #ae81ff } /* Literal.String.Escape */ +.sh { color: #e6db74 } /* Literal.String.Heredoc */ +.si { color: #e6db74 } /* Literal.String.Interpol */ +.sx { color: #e6db74 } /* Literal.String.Other */ +.sr { color: #e6db74 } /* Literal.String.Regex */ +.s1 { color: #e6db74 } /* Literal.String.Single */ +.ss { color: #e6db74 } /* Literal.String.Symbol */ +.bp { color: #f8f8f2 } /* Name.Builtin.Pseudo */ +.vc { color: #f8f8f2 } /* Name.Variable.Class */ +.vg { color: #f8f8f2 } /* Name.Variable.Global */ +.vi { color: #f8f8f2 } /* Name.Variable.Instance */ +.il { color: #ae81ff } /* Literal.Number.Integer.Long */ diff --git a/www/manual/1.0/art.php b/www/manual/1.0/art.php new file mode 100644 index 00000000..2b82e657 --- /dev/null +++ b/www/manual/1.0/art.php @@ -0,0 +1,233 @@ + '10. Art - The Standard Ebooks Manual', 'highlight' => 'contribute', 'manual' => true]) ?> +
+
+ +
+

Art

+

When you create a new Standard Ebooks draft using the se create-draft tool, you’ll already have templates for the cover and titlepage images present in ./images/.

+

Text in these SVG files is represented as text, not paths, so you can edit them using a text editor and not an SVG editor. Then, the se build-images tool 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.

+

To develop cover and titlepage images, you must have the free League Spartan and Sorts Mill Goudy fonts installed on your system.

+
+

Complete list of files

+

A complete set of image source files consists of:

+
    +
  • ./images/cover.source.jpg: 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 JPGs.
    • +
  • ./images/cover.jpg: 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.
    • +
  • ./images/cover.svg: The SVG source file for the cover, with any text represented as actual, editable text. Must be exactly 1400w × 2100h pixels. Since the final cover image SVG has the text converted to paths, we keep this file around to make it easier to make changes to the cover in the future.
    • +
  • ./src/epub/images/cover.svg: The final SVG cover image. This image should be exactly like ./images/cover.svg, but with the text converted to paths. +

    This image is generated by the se build-images tool.

    +
    • +
  • ./images/titlepage.svg: The SVG 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).
    • +
  • ./src/epub/images/titlepage.svg: The final SVG titlepage image, with text converted to paths just like the cover page. +

    This image is generated by the se build-images tool.

    +
    • +
+
+
+

SVG patterns

+
    +
  1. SVGs are only sized with viewBox, not height or width. +
      +
    1. The viewBox attribute consists of whole numbers, without fractions.
      2. +
    +
    2. +
  2. The only attributes on the <svg> root element are: xmlns, version, and viewBox.
    3. +
  3. The contents of the SVG’s <title> element matches the alt attribut of its <img> element in the text.
    4. +
  4. Grouping with <g> is avoided, unless it makes semantic sense. Groups whose sole purpose is to apply transforms should have those transforms applied to the children, and the group removed.
    5. +
  5. The use of fill color is avoided unless strictly necessary. Not defining a fill color allows for night mode compatibility.
    6. +
  6. The transform attribute is illegal; transforms are applied to their elements directly.
    7. +
+
+
+

The cover image

+ +

The cover image is auto-generated by the se create-draft tool. The arrangement of the text is a suggestion, and may be changed by the producer in case a more visually-pleasing arrangment is desired.

+

After completing ./images/cover.svg, use the se build-images tool to build the rasterized distribution SVG in ./src/epub/images/cover.svg.

+
+

Cover image layout

+

se create-draft generates ./images/cover.svg for you with correct dimensions and layout. It’s rarely necessary to edit the cover.

+
    +
  1. Both the title and author are in League Spartan font with 5px letter spacing in ALL CAPS.
    2. +
  2. The left and right sides of the black title box have at least 40px padding. More padding is preferrable over cramming the title in.
    3. +
  3. Translators, illustrators, and other contributors besides the author do not appear on the cover.
    4. +
  4. The group of both the title and author lines is horizontally centered in the black title box.
    5. +
+
+

Title line dimensions

+
    +
  1. One-line titles: the line is 80px tall. Example: The Prince, by Niccolò Machiavelli.
    2. +
  2. Two-line titles: each line is 80px tall, and the second title line is 20px below the first line. Example: Crime and Punishment, by Fyodor Dostoevsky.
    3. +
  3. Two-line, very long titles: each line is 60px tall, and the second line is 20px below the first line. Example: The Wonderful Adventures of Nils, by Selma Lagerlöf.
    4. +
  4. Two-line, extremely long titles: each line is 50px tall, and the second line is 20px below the first line. Example: The Surprising Adventures of Baron Munchausen, by Rudolph Erich Raspe.
    5. +
+
+
+

Author line dimensions

+
    +
  1. The first author line begins 60px below the last title line.
    2. +
  2. One-line authors: the line is 40px tall.
    3. +
  3. Two-line authors: each line is 40px tall, and the second author line is 20px below the first line.
    4. +
+
+
+
+

Cover art

+
    +
  1. ./images/cover.svg links to ./images/cover.jpg as the canvas background.
    2. +
  2. ./images/cover.jpg is 1400w × 2100h in pixels, and is compressed as much as possible while maintaining an acceptable image quality. An acceptable level of image quality is more important than file size.
    3. +
  3. Because ./images/cover.jpg is an image with large dimensions, it must be sourced from a high-resolution scan. It may not always be possible to locate a high-resolution scan, so a smaller source image may be upscaled a small amount to meet the target dimensions.
    4. +
  4. Cover art is in the “fine art oil painting” style. Art not in this style, like modern CG art, is not acceptable.
    5. +
  5. ./images/cover.source.svg is the unmodified source image used to create ./images/cover.jpg. This image is kept in case changes to the source images are to be made in the future.
    6. +
+
+

US-PD clearance

+

The paintings we use are all in the U.S. public domain (US-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.

+

U.S. copyright law is complicated. Because of this, we require that you provide a link to a page scan of a 1924-or-older book that reproduces the painting you selected. This is a hard requirement 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 is PD in the U.S.

+
+
Clearance procedure
+

To actually demonstrate that a painting is PD, you must locate a reproduction of that painting in a 1924-or-older book.

+

This can be quite difficult. Many people find this to be the most time-consuming part of the ebook production process.

+

Because of the difficulty, finding suitable cover at is all about compromise. 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.

+

Note that in ./images/cover.svg, 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.

+
    +
  • 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. Wikiart.org is a great resource to search for paintings by keyword. Museum online collections are another good place to look for inspiration. +

    Once you find a potential candidate you can start researching its PD status.

    +
    • +
  • 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.
    • +
  • Visit Google Books, HathiTrust, and the Internet Archive to begin searching for books where your art is reproduced. +

    (Note that if your IP address is not in the U.S., many book archives like Google Books and HathiTrust may disable book previews.)

    +

    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.

    +
    • +
  • 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.
    • +
+
+
Gotchas
+
    +
  • In older books it was common to have etchings of paintings. Etchings are not strict reproductions, and so we cannot count them for PD clearance. +

    Additionally, it was common for painters to produce several different versions of the same artwork. These different versions are also not enough for PD clearance. The version you find in print must exactly match the scan you located online.

    +

    Before completing PD clearance, carefully compare the reproduction in the page scan with the high-resolution scan 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.

    +
    • +
  • 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.
    • +
+
+
+
+
Resources for locating high resolution scans
+ +
+
+
Resources for locating print reproductions
+ +
+
+
Museums with CC0 collections
+

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.

+ +
+
+
Clearance FAQ
+
    +
  • 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? +

    No. You must find a reproduction of your selected painting in a book published in 1924 or earlier.

    +
    • +
  • 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? +

    No. You must find a reproduction of your selected painting in a book published in 1924 or earlier.

    +
    • +
  • I’ve found a reproduction in a book, but the book is from 1925. Is that OK? +

    No. You must find a reproduction of your selected painting in a book published in 1924 or earlier.

    +
    • +
  • I’ve found scan on a random museum site. Is that OK? +

    No. You must find a reproduction of your selected painting in a book published in 1924 or earlier.

    +
    • +
  • But... +

    No. You must find a reproduction of your selected painting in a book published in 1924 or earlier.

    +
    • +
+
+
+
+
+
+

The titlepage image

+

The titlepage image is auto-generated by the se create-draft tool. The arrangement of the text is a suggestion, and may be changed by the producer in case a more visually-pleasing arrangment is desired.

+

After completing ./images/titlepage.svg, use the se build-images tool to build the rasterized distribution SVG in ./src/epub/images/titlepage.svg.

+
+

Titlepage image layout

+
    +
  1. The title, author, other contributors are in League Spartan font with 5px letter spacing in ALL CAPS.
    2. +
  2. The titlepage does not include subtitles. +

    For example, the titlepage would contain THE MAN WHO WAS THURSDAY, but not THE MAN WHO WAS THURSDAY: A NIGHTMARE.

    +
    3. +
  3. Names of contributors besides the author are preceded by translated by or illustrated by. translated by and illustrated by are set in lowercase Sorts Mill Goudy Italic font.
    4. +
  4. Only the author, translator, and illustrator are on the titlepage. Other contributors like writers of introductions or annotators are not included.
    5. +
  5. The canvas has a padding area of 50px vertically and 100px horizontally in which text must not enter.
    6. +
  6. The viewbox width is exactly 1400px wide.
    7. +
  7. The viewbox height must precisely fit the titlepage contents, plus 50px padding.
    8. +
+
+

Title line dimensions

+
    +
  1. Each title line is 80px tall.
    2. +
  2. The title is split into as many lines as necessary to fit.
    3. +
  3. Title lines are separated by a 20px margin between each line.
    4. +
+
+
+

Author line dimensions

+
    +
  1. The first author line begins 100px below the last title line.
    2. +
  2. Each author line is 60px tall.
    3. +
  3. If an author line must be split, the next line begins 20px below the previous one.
    4. +
  4. For works with multiple authors, subsequent author lines begin 20px below the last author line.
    5. +
+
+
+

Contributor lines dimensions

+
    +
  1. “Contributors” are a “contributor descriptor,” like translated by, followed by the contributor name on a new line.
    2. +
  2. The first contributor descriptor line begins 150px below the last author line.
    3. +
  3. Contributor descriptor lines are 40px tall, all lowercase, in the Sorts Mill Goudy Italic font.
    4. +
  4. The contributor name begins 20px below the contributor descriptor line.
    5. +
  5. The contributor name is 40px tall, ALL CAPS, in the League Spartan font.
    6. +
  6. 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. Example: Siddhartha, by Hermann Hesse.
    7. +
  7. 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.
    8. +
+
+
+
+
+
+
+ diff --git a/www/manual/1.0/code-style.php b/www/manual/1.0/code-style.php new file mode 100644 index 00000000..9c486e32 --- /dev/null +++ b/www/manual/1.0/code-style.php @@ -0,0 +1,182 @@ + '1. XHTML, CSS, and SVG Code Style - The Standard Ebooks Manual', 'highlight' => 'contribute', 'manual' => true]) ?> +
+
+
+

XHTML, CSS, and SVG Code Style

+

The se clean 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.

+
+

XHTML formatting

+
    +
  1. The first line of all XHTML files is: +
    <?xml version="1.0" encoding="utf-8"?>
    +
    2. +
  2. The second line of all XHTML files is (replace xml:lang="en-US" with the appropriate language tag for the file): +
    <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">
    +
    3. +
  3. Tabs are used for indentation.
    4. +
  4. Tag names are lowercase.
    5. +
  5. Tags whose content is phrasing content are on a single line, with no whitespace between the opening and closing tags and the content. +
    <p> + It was a dark and stormy night... +</p>
    +
    <p>It was a dark and stormy night...</p>
    +
    6. +
+
+

<br/> elements

+
    +
  1. <br/> elements within phrasing content are on the same line as the precediong phrasing content, and are followed by a newline. +
    <p>“Pray for the soul of the +<br/> +Demoiselle Jeanne D’Ys.</p>
    +
    <p>“Pray for the soul of the +<br/>Demoiselle Jeanne D’Ys.</p>
    +
    <p>“Pray for the soul of the<br/> +Demoiselle Jeanne D’Ys.</p>
    +
    2. +
  2. The next indentation level after a <br/> element is the same as the previous indentation level. +
    <p>“Pray for the soul of the<br/> + Demoiselle Jeanne D’Ys,<br/> + who died<br/> + in her youth for love of<br/> + Philip, a Stranger.</p>
    +
    <p>“Pray for the soul of the<br/> +Demoiselle Jeanne D’Ys,<br/> +who died<br/> +in her youth for love of<br/> +Philip, a Stranger.</p>
    +
    3. +
  3. The closing tag of the phrasing content broken by a <br/> element is on the same line as the last line of the phrasing content. +
    <p>“Pray for the soul of the<br/> +Demoiselle Jeanne D’Ys. +</p>
    +
    <p>“Pray for the soul of the<br/> +Demoiselle Jeanne D’Ys.</p>
    +
    4. +
  4. <br/> elements have phrasing content both before and after; they don’t appear with phrasing content only before, or only after. +
    <p>“Pray for the soul of the<br/> +Demoiselle Jeanne D’Ys<br/></p>
    +
    <p>“Pray for the soul of the<br/> +Demoiselle Jeanne D’Ys</p>
    +
    5. +
+
+
+

Attributes

+
    +
  1. Attributes are in alphabetical order.
    2. +
  2. Attributes, their namespaces, and their values are lowercase, except for values which are IETF language tags. In IETF language tags, the language subtag is capitalized. +
    <section EPUB:TYPE="CHAPTER" XML:LANG="EN-US">...</section>
    +
    <section epub:type="chapter" xml:lang="en-US">...</section>
    +
    3. +
  3. The string utf-8 is lowercase.
    4. +
+
+

Classes

+
    +
  1. Classes are not used as one-time style hooks. There is almost always a clever selector that can be constructed instead of taking the shortcut of adding a class to an element.
    2. +
  2. Classes are named semantically, describing what they are styling instead of the resulting visual style. +
    <p>There was one great tomb more lordly than all the rest; huge it was, and nobly proportioned. On it was but one word</p> +<blockquote class="small-caps"> + <p>Dracula.</p> +</blockquote>
    +
    <p>There was one great tomb more lordly than all the rest; huge it was, and nobly proportioned. On it was but one word</p> +<blockquote class="tomb"> + <p>Dracula.</p> +</blockquote>
    +
    3. +
+
+
+
+
+

CSS formatting

+
    +
  1. The first two lines of all CSS files are: +
    @charset "utf-8"; +@namespace epub "http://www.idpf.org/2007/ops";
    +
    2. +
  2. Tabs are used for indentation.
    3. +
  3. Selectors, properties, and values are lowercase.
    4. +
+
+

Selectors

+
    +
  1. Selectors are each on their own line, directly followed by a comma or a brace with no whitespace inbetween. +
    abbr.era, .signature{ + font-variant: all-small-caps; +}
    +
    abbr.era, +.signature{ + font-variant: all-small-caps; +}
    +
    2. +
  2. Complete selectors are separated by exactly one blank line. +
    abbr.era{ + font-variant: all-small-caps; +} + + +strong{ + font-weight: normal; + font-variant: small-caps; +}
    +
    abbr.era{ + font-variant: all-small-caps; +} + +strong{ + font-weight: normal; + font-variant: small-caps; +}
    +
    3. +
  3. Closing braces are on their own line.
    4. +
+
+
+

Properties

+
    +
  1. Properties are each on their own line (even if the selector only has one property) and indented with a single tab. +
    abbr.era{ font-variant: all-small-caps; }
    +
    abbr.era{ + font-variant: all-small-caps; +}
    +
    2. +
  2. Where possible, properties are in alphabetical order. +

    This isn’t always possible if a property is attempting to override a previous property in the same selector, and in some other cases.

    +
    3. +
  3. Properties are directly followed by a colon, then a single space, then the property value. +
    blockquote{ + margin-left: 1em; + margin-right: 1em; + border:none; +}
    +
    blockquote{ + margin-left: 1em; + margin-right: 1em; + border: none; +}
    +
    4. +
  4. Property values are directly followed by a semicolon, even if it’s the last value in a selector. +
    abbr.era{ + font-variant: all-small-caps +}
    +
    abbr.era{ + font-variant: all-small-caps; +}
    +
    5. +
+
+
+
+

SVG Formatting

+
    +
  1. SVG formatting follows the same directives as XHTML formatting.
    2. +
+
+
+
+
+ diff --git a/www/manual/1.0/filesystem.php b/www/manual/1.0/filesystem.php new file mode 100644 index 00000000..1122bbbe --- /dev/null +++ b/www/manual/1.0/filesystem.php @@ -0,0 +1,231 @@ + '2. Filesystem Layout and File Naming Conventions - The Standard Ebooks Manual', 'highlight' => 'contribute', 'manual' => true]) ?> +
+
+ +
+

Filesystem Layout and File Naming Conventions

+ +

Filenames aim to be clear, common-sense descriptions of their contents.

+
+

File locations

+
    +
  1. XHTML files containing the actual text of the ebook are located in ./src/epub/text/. All files in this directory end in .xhtml.
    2. +
  2. CSS files used in the ebook are located in ./src/epub/css/. All files in this directory end in .css. This directory contains only two CSS files: +
      +
    1. ./src/epub/css/core.css is distributed with all ebooks and is not meant to be edited.
      2. +
    2. ./src/epub/css/local.css is used for custom CSS local to the particular ebook.
      3. +
    +
    3. +
  3. Raw source images used in the ebook, but not distributed with the ebook, are located in ./src/images/. These images may be, for example, very high resolution that are later converted to lower resolution for distribution, or raw bitmaps that are later converted to SVG for distribution. Every ebook contains the following images in this directory: +
      +
    1. ./src/images/titlepage.svg is the editable titlepage file that is later compiled for distribution.
      2. +
    2. ./src/images/cover.svg is the editable cover file that is later compiled for distribution.
      3. +
    3. ./src/images/cover.source.(jpg|png|bmp|tiff) is the raw cover art file that may be cropped, resized, or otherwise edited to create ./src/images/cover.jpg.
      4. +
    4. ./src/images/cover.jpg is the final edited cover art that will be compiled in to ./src/epub/images/cover.svg for distribution.
      5. +
    +
    4. +
  4. Images compiled or derived from raw source images, that are then distributed with the ebook, are located in ./src/epub/images/.
    5. +
  5. The table of contents is located in ./src/epub/toc.xhtml.
    6. +
  6. The epub metadata file is located in ./src/epub/content.opf.
    7. +
  7. The ONIX metadata file is located in ./src/epub/onix.xml. This file is identical for all ebooks.
    8. +
  8. The ONIX metadata file is located in ./src/epub/onix.xml. This file is identical for all ebooks.
    9. +
  9. The ./src/META-INF/ and ./src/mimetype directory and files are epub structural files that are identical for all ebooks.
    10. +
  10. The ./LICENSE.md contains th ebook license and is identical for all ebooks.
    11. +
+
+
+

XHTML file naming conventions

+
    +
  1. Numbers in filenames don’t include leading 0s.
    2. +
  2. 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. + + + + + + + + + + + + + + + + + +
    WorkFilename
    A short story named “The Variable Man”the-variable-man.xhtml
    A short story named “The Sayings of Limpang-Tung (The God of Mirth and of Melodious Minstrels)”the-sayings-of-limpang-tung.xhtml
    +
    3. +
  3. 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 1. +
    +

    book-1.xhtml

    +

    book-2.xhtml

    +

    part-1.xhtml

    +

    part-2.xhtml

    +
    +
    4. +
  4. 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. +
      +
    1. Chapters not contained in separate volumes are named chapter-N.xhtml, where N is the chapter number starting at 1. + + + + + + + + + + + + + + + + + +
      SectionFilename
      Chapter 1chapter-1.xhtml
      Chapter 2chapter-2.xhtml
      +
      2. +
    2. Chapters contained in separate volumes, where the chapter number re-starts at 1 in each volume, are named chapter-X-N.xhtml, where X is the part number starting at 1, and N is the chapter number within the part, starting at 1. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      SectionFilename
      Part 1part-1.xhtml
      Part 1 Chapter 1chapter-1-1.xhtml
      Part 1 Chapter 2chapter-1-2.xhtml
      Part 1 Chapter 3chapter-1-3.xhtml
      Part 2part-2.xhtml
      Part 2 Chapter 1chapter-2-1.xhtml
      Part 2 Chapter 2chapter-2-2.xhtml
      +
      3. +
    3. Chapters contained in separate volumes, where the chapter number does not re-start at 1 in each volume, are named chapter-N.xhtml, where N is the chapter number, starting at 1. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      SectionFilename
      Part 1part-1.xhtml
      Chapter 1chapter-1.xhtml
      Chapter 2chapter-2.xhtml
      Chapter 3chapter-3.xhtml
      Part 2part-2.xhtml
      Chapter 4chapter-4.xhtml
      Chapter 5chapter-5.xhtml
      +
      4. +
    4. 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. + + + + + + + + + + + + + +
      SectionFilename
      A book of short poems called “North of Boston”north-of-boston.xhtml
      +
      5. +
    5. Frontmatter and backmatter sections have filenames that are named after the type of section, regardless of what the actual title of the section is. + + + + + + + + + + + + + +
      SectionFilename
      A preface titled “Note from the author”preface.xhtml
      +
      6. +
    6. If a work contains more than one section of the same type (for example multiple prefaces), the filename is followed by -N, where N is a number representing the order of the section, starting at 1. + + + + + + + + + + + + + + + + + +
      SectionFilename
      The work’s first preface, titled “Preface to the 1850 Edition”preface-1.xhtml
      The work’s second preface, titled “Preface to the Charles Dickens Edition”preface-2.xhtml
      +
      7. +
    +
    5. +
+
+
+
+
+ diff --git a/www/manual/1.0/general-xhtml-patterns.php b/www/manual/1.0/general-xhtml-patterns.php new file mode 100644 index 00000000..219f0517 --- /dev/null +++ b/www/manual/1.0/general-xhtml-patterns.php @@ -0,0 +1,240 @@ + '5. General XHTML Patterns - The Standard Ebooks Manual', 'highlight' => 'contribute', 'manual' => true]) ?> +
+
+ +
+

General XHTML Patterns

+

Intro.

+
+

The id attribute

+
+

id attributes of <section> elements

+
    +
  1. Each <section> has an id attribute identical to the filename containing that <section>, without the trailing extension.
    2. +
  2. In files containing multiple <section> elements, each <section> has an id attribute identical to what the filename would be if the section was in an individual file, without the trailing extension. +
    <body epub:type="bodymatter z3998:fiction"> + <article id="the-fox-and-the-grapes" epub:type="se:short-story"> + <h2 epub:type="title">The Fox and the Grapes</h2> + <p>...</p> + </article> + <article id="the-goose-that-laid-the-golden-eggs" epub:type="se:short-story"> + <h2 epub:type="title">The Goose That Laid the Golden Eggs</h2> + <p>...</p> + </article> +</body>
    +
    3. +
+
+
+

id attributes of other elements

+
    +
  1. Elements that are not <section> elements do not have an id attribute, unless a part of the ebook, like an endnote, refers to a specific point in the book, and a direct link is desirable.
    2. +
  2. id attributes are generally used to identify parts of the document that a reader may wish to navigate to using a hash in the URL. That generally means major structural divisions.
    3. +
  3. id attributes are not used as hooks for CSS styling.
    4. +
  4. If an element that is not a <section> requires an id attribute, the attribute’s value is the name of the tag followed by -N, where N is the sequence number of the tag start at 1. +
    <p>See <a href="#p-4">this paragraph</a> for more details.</p> +<p>...</p> +<p>...</p> +<p id="p-4">...</p> +<p>...</p>
    +
    5. +
+
+
+
+

The class attribute

+

Classes denote a group of elements sharing a similar style.

+
    +
  1. Classes are not used as single-use style hooks. There is almost always a way to compose a CSS selector to select a single element without the use of a one-off class. +
    .business-card{ + border: 1px solid; + padding: 1em; +}
    +
    <body epub:type="bodymatter z3998:fiction"> + <section epub:type="chapter"> + <p>...</p> + <p>...</p> + <p>...</p> + <p>...</p> + <blockquote class="business-card"> + <p>John Doe, <abbr class="eoc">Esq.</abbr></p> + </blockquote> + </section> +</body>
    +
    #chapter-3 blockquote{ + border: 1px solid; + padding: 1em; +}
    +
    <body epub:type="bodymatter z3998:fiction"> + <section id="chapter-3" epub:type="chapter"> + <p>...</p> + <p>...</p> + <p>...</p> + <p>...</p> + <blockquote> + <p>John Doe, <abbr class="eoc">Esq.</abbr></p> + </blockquote> + </section> +</body>
    +
    2. +
  2. Classes are used to style a recurring class of elements, i.e. a class of element that appears more than once in an ebook. +
    .business-card{ + border: 1px solid; + padding: 1em; +}
    +
    <body epub:type="bodymatter z3998:fiction"> + <section id="chapter-3" epub:type="chapter"> + <p>...</p> + <p>...</p> + <blockquote class="business-card"> + <p>Jane Doe, <abbr class="eoc">Esq.</abbr></p> + </blockquote> + <p>...</p> + <p>...</p> + <blockquote class="business-card"> + <p>John Doe, <abbr class="eoc">Esq.</abbr></p> + </blockquote> + </section> +</body>
    +
    3. +
  3. Class names describe what they are styling semantically, not the actual style the class is applying. +
    .black-border{ + border: 1px solid; + padding: 1em; +}
    +
    .business-card{ + border: 1px solid; + padding: 1em; +}
    +
    4. +
+
+
+

The <title> element

+
    +
  1. The <title> element contains an appropriate description of the local file only. It does not contain the book title.
    2. +
+
+

Titles of files that are an individual chapter or part division

+
    +
  1. 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. +
    <title>Chapter 10</title>
    +
    2. +
  2. If a chapter or part is only an ordinal and has no title or subtitle, the <title> element is Chapter followed by the chapter number. +
    <title>Chapter 4</title> +... +<h2 epub:type="title z3998:roman">IV</h2> +... +<p>The chapter body...</p>
    +
    3. +
  3. If a chapter or part has a title or subtitle, the <title> element is Chapter, followed by the chapter number in decimal, followed by a colon and a single space, followed by the title or subtitle. +
    <title>Chapter 6: The Reign of Louis XVI</title> +... +<h2 epub:type="title z3998:roman"> + <span>VI</span>> + <span epub:type="subtitle">The Reign of Louis <span epub:type="z3998:roman">XVI</span></h2> +... +<p>The chapter body...</p>
    +
    4. +
+
+
+

Titles of files that are not chapter or part divisions

+
    +
  1. Files that are not a chapter or a part division, like a preface, introduction, or epigraph, have a <title> element that contains the complete title of the section. +
    <title>Preface</title>
    +
    2. +
  2. If a file contains a section with a title or subtitle, the <title> element contains the title, followed by a colon and a single space, followed by the title or subtitle. +
    <title>Quevedo and His Works: With an Essay on the Picaresque Novel</title>
    +
    3. +
+
+
+
+

Ordered/numbered and unordered lists

+
    +
  1. All <li> children of <ol> and <ul> elements have at least one direct child block-level tag. This is usually a <p> element, but not necessarily; for example, a <blockquote> element might also be appropriate. +
    <ul> + <li>Don’t forget to feed the pigs.</li> +</ul>
    +
    <ul> + <li> + <p>Don’t forget to feed the pigs.</p> + </li> +</ul>
    +
    2. +
+
+
+

Tables

+
    +
  1. <table> elements have a direct child <tbody> element. +
    <table> + <tr> + <td>1</td> + <td>2</td> + </tr> +</table>
    +
    <table> + <tbody> + <tr> + <td>1</td> + <td>2</td> + </tr> + </tbody> +</table>
    +
    2. +
  2. <table> elements may have an optional direct child <thead> element, if a table heading is desired.
    3. +
  3. <table> elements that are used to display tabular numerical data, for example columns of sums, have CSS styling for tabular numbers: { font-variant-numeric: tabular-nums; }. +
    table td:last-child{ + text-align: right; + font-variant-numeric: tabular-nums; +}
    +
    <table> + <tbody> + <tr> + <td>Amount 1</td> + <td>100</td> + </tr> + <tr> + <td>Amount 2</td> + <td>300</td> + </tr> + <tr> + <td>Total</td> + <td>400</td> + </tr> + </tbody> +</table>
    +
    4. +
+
+
+

xml:lang attributes

+
    +
  1. When words are required to be pronounced in a language other than English, the xml:lang attribute is used to indicate the IETF language tag in use. +
      +
    1. The xml:lang attribute is used even if a word is not required to be italicized. This allows screen readers to understand that a particular word or phrase should be pronounced in a certain way.
      2. +
    2. The xml:lang attribute is included in any word that requires special pronunciation, including names of places and titles of books.
      3. +
    +
    She opened the book titled <i epub:type="se:name.publication.book" xml:lang="la">Mortis Imago</i>.
    +
      +
    1. The xml:lang attribute is applied to the highest-level tag possible. If italics are required and moving the xml:lang attribute would also remove an <i> element, the parent element can be styled with body [xml|lang]{ font-style: italic; }.
      2. +
    +
    <blockquote> + <p><i xml:lang="es">“Como estas?” el preguntó.</i></p> + <p><i xml:lang="es">“Bien, gracias,” dijo ella.</i></p> +</blockquote>
    +
    <blockquote xml:lang="es"> + <p>“Como estas?” el preguntó.</p> + <p>“Bien, gracias,” dijo ella.</p> +</blockquote>
    +
    2. +
+
+
+
+
+ diff --git a/www/manual/1.0/high-level-structural-patterns.php b/www/manual/1.0/high-level-structural-patterns.php new file mode 100644 index 00000000..ed0114c8 --- /dev/null +++ b/www/manual/1.0/high-level-structural-patterns.php @@ -0,0 +1,927 @@ + '6. High Level Structural Patterns - The Standard Ebooks Manual', 'highlight' => 'contribute', 'manual' => true]) ?> +
+
+ +
+

High Level Structural Patterns

+

Section should contain high-level structural patterns for common formatting situations.

+
+

Sectioning

+
    +
  1. Major structural divisions of a larger work, like parts, volumes, books, chapters, or subchapters, are contained in a <section> element.
    2. +
  2. Individual items in a larger collection (like a poem in a poetry collection) are contained in a <article> element.
    3. +
  3. In <section> or <articles> elements that have titles, the first child element is an <h1>–<h6> element, or a <header> element containing the section's title.
    4. +
+
+

Recomposability

+

“Recomposability” is the concept of generating a single structurally-correct HTML5 file out of an epub file. All SE ebooks are recomposable.

+
    +
  1. XHTML files that contain <section> or <articles> elements that are semantic children of <section> or <articles> elements in other files, are wrapped in stubs of all parent <section> or <articles> elements, up to the root.
    2. +
  2. Each such included parent element has the identical id and epub:type attributes of its real counterpart.
    3. +
+
+

Examples

+

Consider a book that contains several top-level subdivisions: Books 1–4, with each book having 3 parts, and each part having 10 chapters. Below is an example of three files demonstrating the structure necessary to achieve recomposability:

+

Book 1 (book-1.xhtml):

+
<section id="book-1" epub:type="division"> + <h2 epub:type="title">Book <span epub:type="z3998:roman">I</span></h2> +</section>
+

Book 1, Part 2 (part-1-2.xhtml):

+
<section id="book-1" epub:type="division"> + <section id="part-1-2" epub:type="part"> + <h2 epub:type="title">Part <span epub:type="z3998:roman">II</span></h2> + </section> +</section>
+

Book 1, Part 2, Chapter 3 (chapter-1-2-3.xhtml):

+
<section id="book-1" epub:type="division"> + <section id="part-1-2" epub:type="part"> + <section id="chapter-3" epub:type="chapter"> + <h2 epub:type="title">Chapter <span epub:type="z3998:roman">III</span></h2> + <p>...</p> + <p>...</p> + </section> + </section> +</section>
+
+
+
+
+

Headers

+
    +
  1. <h1>–<h6> elements are used for headers of sections that are structural divisions of a document, i.e., divisions that appear in the table of contents. <h1>–<h6> elements are not used for headers of components that are not in the table of contents. For example, they are not used to mark up the the title of a short poem in a chapter, where the poem itself is not a structural component of the larger ebook.
    2. +
  2. A section containing an <h1>–<h6> appears in the table of contents.
    3. +
  3. The book's title is implicitly at the <h1> level, even if <h1> is not present in the ebook. Because of the implicit <h1>, all other sections begin at <h2>.
    4. +
  4. Each <h1>–<h6> element uses the correct number for the section's heading level in the overall book, not the section's heading level in the individual file. For example, given an ebook with a file named part-2.xhtml containing: +
    <section id="part-2" epub:type="part"> + <h2 epub:type="title">Part <span epub:type="z3998:roman">II</span></h2> +</section>
    +

    Consider this example for the file chapter-2-3.xhtml:

    +
    <section id="part-2" epub:type="part"> + <section id="chapter-2-3" epub:type="chapter"> + <h2 epub:type="title z3998:roman">III</h2> + ... + </section> +</section>
    +
    <section id="part-2" epub:type="part"> + <section id="chapter-2-3" epub:type="chapter"> + <h3 epub:type="title z3998:roman">III</h3> + ... + </section> +</section>
    +
    5. +
  5. Each <h1>–<h6> element has a direct parent <section> or <article> element.
    6. +
+
+

Header patterns

+
    +
  1. Sections without titles: +
    <h2 epub:type="title z3998:roman">XI</h2>
    +
    2. +
  2. Sections with titles but no ordinal (i.e. chapter) numbers: +
    <h2 epub:type="title">A Daughter of Albion</h2>
    +
    3. +
  3. Sections with titles and ordinal (i.e. chapter) numbers: +
    span[epub|type~="subtitle"]{ + display: block; + font-weight: normal; +}
    +
    <h2 epub:type="title"> + <span epub:type="z3998:roman">XI</span> + <span epub:type="subtitle">Who Stole the Tarts?</span> +</h2>
    +
    4. +
  4. Sections titles and subtitles but no ordinal (i.e. chapter) numbers: +
    span[epub|type~="subtitle"]{ + display: block; + font-weight: normal; +}
    +
    <h2 epub:type="title"> + <span>An Adventure</span> + <span epub:type="subtitle">(A Driver’s Story)</span> +</h2>
    +
    5. +
  5. Sections that require titles, but that are not in the table of contents: +
    header{ + font-variant: small-caps; + margin: 1em; + text-align: center; +}
    +
    <header> + <p>The Title of a Short Poem</p> +</header>
    +
    6. +
+
+
+

Bridgeheads

+

Bridgeheads are sections in a chapter header that give an abstract or summary of the following chapter. They may be in prose or in a short list with clauses separated by em dashes.

+
    +
  1. The last clause in a bridgehead ends in appropriate punctuation, like a period.
    2. +
  2. Bridgeheads have the following CSS and HTML structure: +
    [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; +}
    +
    <header> + <h2 epub:type="title z3998:roman">I</h2> + <p epub:type="bridgehead">Which treats of the character and pursuits of the famous gentleman Don Quixote of La Mancha.</p> +</header>
    +
    <header> + <h2 epub:type="title z3998:roman">X</h2> + <p epub:type="bridgehead">Our first night⁠—Under canvas⁠—An appeal for help⁠—Contrariness of teakettles, how to overcome⁠—Supper⁠—How to feel virtuous⁠—Wanted! a comfortably-appointed, well-drained desert island, neighbourhood of South Pacific Ocean preferred⁠—Funny thing that happened to George’s father⁠—a restless night.</p> +</header>
    +
    3. +
+
+
+
+

Epigraphs

+
    +
  1. All epigraphs include this CSS: +
    /* 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 */
    +
    2. +
+
+

Epigraphs in section headers

+
    +
  1. Epigraphs in section headers have the quote source in a <cite> element set in small caps, without a leading em-dash and without a trailing period. +
    <header> + <h2 epub:type="title z3998:roman">II</h2> + <blockquote epub:type="epigraph"> + <p>“Desire no more than to thy lot may fall. …”</p> + <cite>—Chaucer.</cite> + </blockquote> +</header>
    +
    header [epub|type~="epigraph"] cite{ + font-variant: small-caps; +}
    +
    <header> + <h2 epub:type="title z3998:roman">II</h2> + <blockquote epub:type="epigraph"> + <p>“Desire no more than to thy lot may fall. …”</p> + <cite>Chaucer</cite> + </blockquote> +</header>
    +
    2. +
  2. In addition to the CSS used for all epigraphs, this additional CSS is included for epigraphs in section headers: +
    /* Epigraphs in section headers */ +section > header [epub|type~="epigraph"]{ + display: inline-block; + margin: auto; + max-width: 80%; + text-align: left; +} + +section > header [epub|type~="epigraph"] + *{ + margin-top: 3em; +} + +@supports(display: table){ + section > header [epub|type~="epigraph"]{ + display: table; + } +} +/* End epigraphs in section headers */
    +
    3. +
+
+
+

Full-page epigraphs

+
    +
  1. In full-page epigraphs, the epigraph is centered on the page for ereaders that support advanced CSS. For all other ereaders, the epigraph is horizontally centered with a small margin above it.
    2. +
  2. Full-page epigraphs that contain multiple quotations are represented by multiple <blockquote> elements.
    3. +
  3. In addition to the CSS used for all epigraphs, this additional CSS is included for full-page epigraphs: +
    /* Full-page epigraphs */ +section[epub|type~="epigraph"]{ + text-align: center; +} + +section[epub|type~="epigraph"] > *{ + 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"] > *{ + margin: 0; + } + + section[epub|type~="epigraph"] > * + *{ + margin-top: 3em; + } +} +/* End full-page epigraphs */
    +
    4. +
  4. Example HTML: +
    <body epub:type="frontmatter"> + <section id="epigraph" epub:type="epigraph"> + <blockquote> + <p>Reorganisation, irrespectively of God or king, by the worship of Humanity, systematically adopted.</p> + <p>Man’s only right is to do his duty.</p> + <p>The Intellect should always be the servant of the Heart, and should never be its slave.</p> + </blockquote> + <blockquote> + <p>“We tire of thinking and even of acting; we never tire of loving.”</p> + </blockquote> + </section> +</body>
    +
    5. +
+
+
+
+

Poetry, verse, and songs

+

Unfortunately there’s no great way to semantically format poetry in HTML. As such, unrelated elements are conscripted for use in poetry.

+
    +
  1. A stanza is represented by a <p> element. +
    [epub|type~="z3998:poem"] p{ + text-align: left; + text-indent: 0; +} + +[epub|type~="z3998:poem"] p + p{ + margin-top: 1em; +} + +[epub|type~="z3998:poem"] + p{ + text-indent: 0; +}
    +
    2. +
  2. Each stanza contains <span> elements, each one representing a line in the stanza. +
    [epub|type~="z3998:poem"] p > span{ + display: block; + text-indent: -1em; + padding-left: 1em; +}
    +
    3. +
  3. Each <span> line is followed by a <br/> element, except for the last line in a stanza. +
    [epub|type~="z3998:poem"] p > span + br{ + display: none; +}
    +
    4. +
  4. Indented <span> lines have the i1 class. Do not use nbsp for indentation. Indenting to different levels is done by incrementing the class to i2, i3, and so on, and including the appropriate CSS. +
    p span.i1{ + text-indent: -1em; + padding-left: 2em; +} + +p span.i2{ + text-indent: -1em; + padding-left: 3em; +}
    +
    5. +
  5. Poems, songs, and verse that are shorter part of a longer work, like a novel, are wrapped in a <blockquote> element. +
    <blockquote epub:type="z3998:poem"> + <p> + <span>...</span></br> + <span>...</span> + </p> +</blockquote>
    +
    6. +
  6. The parent element of poetry, verse, or song, has the semantic inflection of z3998:poem, z3998:verse, z3998:song, or z3998:hymn.
    7. +
  7. If a poem is quoted and has one or more lines removed, the removed lines are represented with a vertical ellipses (⋮ or u+22EE) in a <span class="elision"> element: +
    span.elision{ + margin: .5em; + margin-left: 3em; +} + +/* If eliding within an epigraph, include this additional style: */ +[epub|type~="epigraph"] span.elision{ + font-style: normal; +}
    +
    <blockquote epub:type="z3998:verse"> + <p> + <span>O Lady! we receive but what we give,</span> + <br/> + <span>And in our life alone does nature live:</span> + <br/> + <span>Ours is her wedding garments, ours her shroud!</span> + <br/> + <span class="elision">⋮</span> + <br/> + <span class="i1">Ah! from the soul itself must issue forth</span> + <br/> + <span>A light, a glory, a fair luminous cloud,</span> + </p> +</blockquote>
    +
    8. +
+
+

Examples

+

Note that below we include CSS for the i2 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.

+
[epub|type~="z3998:poem"] p{ + text-align: left; + text-indent: 0; +} + +[epub|type~="z3998:poem"] p > span{ + display: block; + text-indent: -1em; + padding-left: 1em; +} + +[epub|type~="z3998:poem"] p > 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; +}
+
<blockquote epub:type="z3998:poem"> + <p> + <span>“How doth the little crocodile</span> + <br/> + <span class="i1">Improve his shining tail,</span> + <br/> + <span>And pour the waters of the Nile</span> + <br/> + <span class="i1">On every golden scale!</span> + </p> + <p> + <span>“How cheerfully he seems to grin,</span> + <br/> + <span class="i1">How neatly spread his claws,</span> + <br/> + <span>And welcome little fishes in</span> + <br/> + <span class="i1"><em>With gently smiling jaws!</em>”</span> + </p> +</blockquote>
+
+
+
+

Plays & Drama

+
    +
  1. Dialog in plays is structured using <table> elements.
    2. +
  2. Each <tr> is either a block of dialog or a standalone stage direction.
    3. +
  3. Works that are plays or that contain sections of dramatic dialog have this core 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; +}
    +
    4. +
+
+

Dialog rows

+
    +
  1. The first child of a row of dialog is a <td> element with the semantic inflection of z3998:persona.
    2. +
  2. The second child of a row of dialog is a <td> element containing the actual dialog. Elements that contain only one line of dialog do not have a block-level child (like <p>). +
    <tr> + <td epub:type="z3998:persona">Algernon</td> + <td>Did you hear what I was playing, Lane?</td> +</tr> +<tr> + <td epub:type="z3998:persona">Lane</td> + <td>I didn’t think it polite to listen, sir.</td> +</tr>
    +
    3. +
  3. When several personas speak at once, or a group of personas ("The Actors") speaks at once, the containing <tr> element has the together class, and the the first <td> child has a rowspan attribute corresponding to the number of lines spoken together. +
    tr.together td{ + padding: 0 .5em 0 0; + vertical-align: middle; +} + +tr.together td:only-child, +tr.together td + td{ + border-left: 1px solid; +} + +.together + .together td[rowspan], +.together + .together td[rowspan] + td{ + padding-top: .5em; +} + +[epub|type~="z3998:drama"] .together td:last-child{ + padding-left: .5em; +}
    +
    <tr class="together"> + <td rowspan="3" epub:type="z3998:persona">The Actors</td> + <td>Oh, what d’you think of that?</td> +</tr> +<tr class="together"> + <td>Only the mantle?</td> +</tr> +<tr class="together"> + <td>He must be mad.</td> +</tr> +<tr class="together"> + <td rowspan="2" epub:type="z3998:persona">Some Actresses</td> + <td>But why?</td> +</tr> +<tr class="together"> + <td>Mantles as well?</td> +</tr>
    +
    4. +
+
+
+

Stage direction rows

+
    +
  1. The first child of a row of stage direction is an empty <td> element.
    2. +
  2. The second child of a row of dialog is a <td> element containing the stage direction
    3. +
  3. Stage direction is wrapped in an <i epub:type="z3998:stage-direction"> element.
    4. +
  4. Personas mentioned in stage direction are wrapped in a <b epub:type="z3998:persona"> element.
    5. +
+
+

Examples

+
<tr> + <td/> + <td> + <i epub:type="z3998:stage-direction"><b epub:type="z3998:persona">Lane</b> is arranging afternoon tea on the table, and after the music has ceased, <b epub:type="z3998:persona">Algernon</b> enters.</i> + </td> +</tr>
+
+
+
+

Works that are complete plays

+
    +
  1. The top-level element (usually <body>) has the z3998:drama semantic inflection.
    2. +
  2. Acts are <section> elements containing at least one <table> for dialog, and optionally containing an act title and other top-level stage direction.
    3. +
  3. Introductory or high-level stage direction is presented using <p> elements outside of the dialog table. +
    <body epub:type="bodymatter z3998:fiction z3998:drama"> + <section id="act-1" epub:type="chapter z3998:scene"> + <h2 epub:type="title">Act <span epub:type="z3998:roman">I</span></h2> + <p>Scene: Morning-room in Algernon’s flat in Half-Moon Street. The room is luxuriously and artistically furnished. The sound of a piano is heard in the adjoining room.</p> + <table> + ... + </table> + <p epub:type="z3998:stage-direction">Act Drop</p> + </section> +</body>
    +
    4. +
  4. Dramatis personae are presented as a <ul> element listing the characters. +
    [epub|type~="z3998:dramatis-personae"]{ + text-align: center; +} + +[epub|type~="z3998:dramatis-personae"] ul{ + list-style: none; + margin: 0; + padding: 0; +} + +[epub|type~="z3998:dramatis-personae"] ul li{ + margin: 1em; + font-style: italic; +}
    +
    <section id="dramatis-personae" epub:type="z3998:dramatis-personae"> + <h2 epub:type="title">Dramatis Personae</h2> + <ul> + <li> + <p>King Henry <span epub:type="z3998:roman">V</span></p> + </li> + <li> + <p>Duke of Clarence, brother to the King</p> + </li> + ... + </ul> +</section>
    +
    5. +
+
+
+
+

Letters

+

Letters require particular attention to styling and semantic tagging. Letters may not exactly match the formatting in the source scans, but they are in visual sympathy with the source.

+
    +
  1. Letters are wrapped in a <blockquote> element with the appropriate semantic inflection, usually z3998:letter.
    2. +
+
+

Letter headers

+
    +
  1. Parts of a letter prior to the body of the letter, for example the location where it is written, the date, and the salutation, are wrapped in a <header> element.
    2. +
  2. If there is only a salutation and no other header content, the <header> element is ommitted.
    3. +
  3. The location and date of a letter have the semantic inflection of se:letter.dateline. Dates are in a <time> element with a computer-readable date. +
    <header> + <p epub:type="se:letter.dateline">Blarney Castle, <time datetime="1863-10-11">11th of October, 1863</time></p> +</header>
    +
    4. +
  4. The salutation (for example, “Dear Sir” or “My dearest Jane”) has the semantic inflection of z3998:salutation.
    5. +
  5. The first line of a letter after the salutation is not indented.
    6. +
  6. Salutations that are within the first line of the letter are wrapped in a <span epub:type="z3998:salutation> element (or a <b epub:type="z3998:salutation> element if small-caps are desired). +
    <p><b epub:type="z3998:salutation">Dear Mother</b>, I was so happy to hear from you.</p>
    +
    7. +
  7. The name of the recipient of the letter, when set out other than within a saluation (for example a letter headed “To: John Smith Esquire”), is given the semantic inflection of z3998:recipient. Sometimes this may occur at the end of a letter, particularly for more formal communications, in which case it is placed within a <footer> element.
    8. +
+
+
+

Letter footers

+
    +
  1. Parts of a letter after the body of the letter, for example the signature or postscript, are wrapped in a <footer> element.
    2. +
  2. The footer element has the following CSS: +
    footer{ + margin-top: 1em; + text-align: right; +}
    +
    3. +
  3. The valediction (for example, “Yours Truly” or “With best regards”) has the semantic inflection of z3998:valediction.
    4. +
  4. The sender’s name has semantic inflection of z3998:sender. If the name appears to be a signature to the letter, it has the signature class and the corresponding .signature CSS. +
    .signature{ + font-variant: small-caps; +}
    +
    <footer> + <p class="signature z3998:sender"><abbr class="name">R. A.</abbr> Johnson</p> +</footer>
    +
    <footer> + <p class="z3998:sender"><span class="signature">John Doe</span>, President</p> +</footer>
    +
    5. +
  5. Postscripts have the semantic inflection of z3998:postscript and the following CSS: +
    [epub|type=~"z3998:postscript"]{ + margin-top: 1em; + text-align: left; +}
    +
    6. +
+
+
+

Examples

+
[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; +}
+
<blockquote epub:type="z3998:letter"> + <p epub:type="z3998:salutation">Dearest Auntie,</p> + <p>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.</p> + <footer> + <p epub:type="z3998:valediction">Your loving niece,</p> + <p class="signature" epub:type="z3998:sender">Mabel</p> + <p epub:type="z3998:postscript">P.S.⁠—Lots, please, because some of us are very hungry.</p> + </footer> +</blockquote>
+
<blockquote epub:type="z3998:letter"> + <header> + <p epub:type="se:letter.dateline">Gracechurch-street, <time datetime="08-02">August 2</time>.</p> + </header> + <p><span epub:type="z3998:salutation">My dear Brother</span>, 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⁠—</p> + <p>I shall write again as soon as anything more is determined on.</p> + <footer> + <p epub:type="z3998:valediction">Yours, etc.</p> + <p class="signature" epub:type="z3998:sender">Edward Gardner</p> + </footer> +</blockquote>
+
+
+
+

Images

+
    +
  1. <img> elements have an alt attribute that uses prose to describe the image in detail; this is what screen reading software will read aloud. +
      +
    1. The alt attribute describes the visual image itself in words, which is not the same as writing a caption or describing its place in the book. +
      <img alt="The illustration for chapter 10" src="..." />
      +
      <img alt="Pierre's fruit-filled dinner" src="..." />
      +
      <img alt="An apple and a pear inside a bowl, resting on a table." src="..." />
      +
      2. +
    2. The alt attribute is one or more complete sentences ended with periods or other appropriate punctuation. It is not composed of sentence fragments or complete sentences without ending punctuation.
      3. +
    3. The alt attribute is not necessarily the same as text in the image’s sibling <figcaption> element, if one is present.
      4. +
    +
    2. +
  2. <img> elements have semantic inflection denoting the type of image. Common values are z3998:illustration or z3998:photograph.
    3. +
  3. <img> element whose image is black-on-white line art (i.e. exactly two colors, not grayscale!) are PNG files with a transparent background. They have the se:image.color-depth.black-on-transparent semantic inflection.
    4. +
  4. <img> elements that are meant to be aligned on the block level or displayed as full-page images are contained in a parent <figure> element, with an optional <figcaption> sibling. +
      +
    1. when contained in a <figure> element, the <img> element does not have an id attribute; instead the <figure> element has the id attribute.
      2. +
    2. An optional <figcaption> element containing a concise context-dependent caption may follow the <img> element within a <figure> element. This caption depends on the surrounding context, and is not necessarily (or even ideally) identical to the <img> element's alt attribute.
      3. +
    3. All figure elements, regardless of positioning, have this CSS: +
      figure img{ + display: block; + margin: auto; + max-width: 100%; +} + +figure + p{ + text-indent: 0; +} + +figcaption{ + font-size: .75em; + font-style: italic; + margin: 1em; +}
      +
      4. +
    4. <figure> elements that are meant to be displayed as full-page images have the full-page class and this additional CSS: +
      figure.full-page{ + margin: 0; + max-height: 100%; + page-break-before: always; + page-break-after: always; + page-break-inside: avoid; + text-align: center; +}
      +
      5. +
    5. <figure> elements that meant to be aligned block-level with the text have this additional CSS: +
      figure{ + margin: 1em auto; + text-align: center; +}
      +
      6. +
    +
    5. +
+
+

Examples

+
/* 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; +}
+
<p>...</p> +<figure id="illustration-10"> + <img alt="An apple and a pear inside a bowl, resting on a table." src="../images/illustration-10.jpg" epub:type="z3998:photograph"/> + <figcaption>The Monk’s Repast</figcaption> +</figure>
+
<p>...</p> +<figure class="full-page" id="image-11"> + <img alt="A massive whale breaching the water, with a sailor floating in the water directly within the whale’s mouth." src="../images/illustration-11.jpg" epub:type="z3998:illustration"/> + <figcaption>The Whale eats Sailor Jim.</figcaption> +</figure>
+
<p>He saw strange alien text that looked like this: <img alt="A line of alien heiroglyphs." src="../images/alien-text.svg" epub:type="z3998:illustration se:color-depth.black-on-transparent" />. There was nothing else amongst the ruins.</p>
+
+
+
+

List of Illustrations (the LoI)

+

If an ebook has any illustrations that are major structural components of the work (even just one!), then the ebook includes an loi.xhtml file at the end of the ebook. This file lists the illustrations in the ebook, along with a short caption or description. #. The LoI is an XHTML file located in ./src/epub/text/loi.xhtml.

+
    +
  1. The LoI file has the backmatter semantic inflection.
    2. +
  2. The LoI only contains links to images that are major structural components of the work. +
      +
    1. 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.
      2. +
    2. An illustration is not a major structural components if, for example: it is a drawing used to represent a person's signature, like an X mark; it is an inline drawing representing text in alien languages; it is a drawing used as a layout element to illustrate forms, tables, or diagrams.
      3. +
    +
    3. +
  3. The LoI file contains a single <section id="loi" epub:type="loi"> element, which in turn contains an <h2 epub:type="title">List of Illustrations</h2> element, followed by a <nav epub:type="loi"> element containing an <ol> element, which in turn contains list items representing the images.
    4. +
  4. If an image listed in the LoI has a <figcaption> element, then that caption is used in the anchor text for that LoI entry. If not, the image’s alt attribute is used. If the <figcaption> element is too long for a concise LoI entry, the alt attribute is used instead.
    5. +
  5. Links to the images go directly to the image's corresponding id hashes, not just the top of the containing file.
    6. +
+
+

Examples

+
<?xml version="1.0" encoding="UTF-8"?> +<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" epub:prefix="z3998: http://www.daisy.org/z3998/2012/vocab/structure/, se: http://standardebooks.org/vocab/1.0" xml:lang="en-GB"> + <head> + <title>List of Illustrations</title> + <link href="../css/core.css" rel="stylesheet" type="text/css"/> + <link href="../css/local.css" rel="stylesheet" type="text/css"/> + </head> + <body epub:type="backmatter"> + <section id="loi" epub:type="loi"> + <nav epub:type="loi"> + <h2 epub:type="title">List of Illustrations</h2> + <ol> + <li> + <a href="../text/preface.xhtml#the-edge-of-the-world">The Edge of the World</a> + </li> + ... + </ol> + </nav> + </section> + </body> +</html>
+
+
+
+

Endnotes

+
    +
  1. Ebooks do not have footnotes, only endnotes. Footnotes are instead converted to endnotes.
    2. +
  2. “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. +

    When the last-mentioned source is in the previous endnote, Ibid. is replaced by the full reference; otherwise Ibid. is left as-is. Since ebooks use popup endnotes, “Ibid.” becomes meaningless without context.

    +
    3. +
+
+

Noterefs

+

The noteref is the superscripted number in the body text that links to the endnote at the end of the book.

+
    +
  1. Endnotes are referenced in the text by an <a> tag with the semantic inflection noteref. +
      +
    1. Noterefs point directly to the corresponding endnote <li> element in the endnotes file.
      2. +
    2. Noterefs have an id attribute like noteref-n, where n is identical to the endnote number.
      3. +
    3. The text of the noteref is the endnote number.
      4. +
    +
    2. +
  2. If located at the end of a sentence, noterefs are placed after ending punctuation.
    3. +
  3. If the endnote references an entire sentence in quotation marks, or the last word in a sentence in quotation marks, then the noteref is placed outside the quotation marks.
    4. +
+
+
+

The endnotes file

+
    +
  1. Endnotes are in an XHTML file located in ./src/epub/text/endnotes.xhtml.
    2. +
  2. The endnotes file has the backmatter semantic inflection.
    3. +
  3. The endnotes file contains a single <section id="endnotes" epub:type="endnotes"> element, which in turn contains an <h2 epub:type="title">Endnotes</h2> element, followed by an <ol> element containing list items representing the endnotes.
    4. +
  4. Each endnote’s id attribute is in sequential ascending order.
    5. +
+
+
+

Individual endnotes

+
    +
  1. An endnote is an <li id="note-n" epub:type="endnote"> element containing one or more block-level text elements and one backlink element.
    2. +
  2. Each endnote’s contains a backlink, which has the semantic inflection backlink, contains the text ↩, and has the href attribute pointing to the corresponding noteref hash. +
      +
    1. In endnotes where the last block-level element is a <p> element, the backlink goes at the end of the <p> element, preceded by exactly one space.
      2. +
    2. In endnotes where the last block-level element is verse, quotation, or otherwise not plain prose text, the backlink goes in its own <p> element following the last block-level element in the endnote.
      3. +
    +
    3. +
  3. Endnotes with ending citations have those citations are wrapped in a <cite> element, including any em-dashes. A space follows the <cite> element, before the backlink.
    4. +
+
+
+

Examples

+
<p>... a continent that was not rent asunder by volcanic forces as was that legendary one of Atlantis in the Eastern Ocean.<a href="endnotes.xhtml#note-1" id="noteref-1" epub:type="noteref">1</a> My work in Java, in Papua, ...</p>
+
<?xml version="1.0" encoding="UTF-8"?> +<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" epub:prefix="z3998: http://www.daisy.org/z3998/2012/vocab/structure/, se: http://standardebooks.org/vocab/1.0" xml:lang="en-GB"> + <head> + <title>Endnotes</title> + <link href="../css/core.css" rel="stylesheet" type="text/css"/> + <link href="../css/local.css" rel="stylesheet" type="text/css"/> + </head> + <body epub:type="backmatter"> + <section id="endnotes" epub:type="endnotes"> + <h2 epub:type="title">Endnotes</h2> + <ol> + <li id="note-1" epub:type="endnote"> + <p>For more detailed observations on these points refer to <abbr class="name">G.</abbr> Volkens, “Uber die Karolinen Insel Yap.” <cite>—<abbr class="name eoc">W. T. G.</abbr></cite> <a href="chapter-2.xhtml#noteref-1" epub:type="backlink">↩</a></p> + </li> + </ol> + <ol> + <li id="note-2" epub:type="endnote"> + <blockquote epub:type="z3998:verse"> + <p> + <span>“Who never ceases still to strive,</span> + <br/> + <span>’Tis him we can deliver.”</span> + </p> + </blockquote> + <p> + <a href="chapter-4.xhtml#noteref-2" epub:type="backlink">↩</a> + </p> + </li> + </ol> + </section> + </body> +</html>
+
+
+
+
+
+ diff --git a/www/manual/1.0/index.php b/www/manual/1.0/index.php new file mode 100644 index 00000000..e11be766 --- /dev/null +++ b/www/manual/1.0/index.php @@ -0,0 +1,25 @@ + 'The Standard Ebooks Manual', 'highlight' => 'contribute']) ?> +
+ +
+ diff --git a/www/manual/1.0/metadata.php b/www/manual/1.0/metadata.php new file mode 100644 index 00000000..b5de55c4 --- /dev/null +++ b/www/manual/1.0/metadata.php @@ -0,0 +1,350 @@ + '9. Metadata - The Standard Ebooks Manual', 'highlight' => 'contribute', 'manual' => true]) ?> +
+
+ +
+

Metadata

+

Metadata in a Standard Ebooks epub is stored in the ./src/epub/content.opf file. The file contains some boilerplate that an ebook producer won’t have to touch, and a lot of information that they will have to touch as an ebook is produced.

+

Follow the general structure of the content.opf file present in the tools ./templates/ directory. Don’t rearrange the order of anything in there.

+
+

General URL rules

+
    +
  1. URLs used in metadata are https where possible.
    2. +
  2. URLs used in metadata do not contain query strings, or if a query string is required, only contain the minimum necessary query string to render the base resource.
    3. +
  3. URLs used for Project Gutenberg page scans look like: https://www.gutenberg.org/ebooks/<BOOK-ID>.
    4. +
  4. URLs used for HathiTrust page scans look like: https://catalog.hathitrust.org/Record/<RECORD-ID>.
    5. +
  5. URLs used for Google Books page scans look like: https://books.google.com/books?id=<BOOK-ID>.
    6. +
  6. URLs used for Internet Archive page scans look like: https://archive.org/details/<BOOK-ID>.
    7. +
+
+
+

The ebook identifier

+
    +
  1. The <dc:identifier> element contains the unique identifier for the ebook. The identifier is the Standard Ebooks URL for the ebook, prefaced by url:. +
    <dc:identifier id="uid">url:https://standardebooks.org/ebooks/anton-chekhov/short-fiction/constance-garnett</dc:identifier>
    +
    2. +
+
+

Forming the SE URL

+

The SE URL is formed by the following algorithm.

+

(Note: A string can be made URL-safe using the se make-url-safe tool.)

+
    +
  • 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.
    • +
  • Append a forward slash, then the URL-safe title of the work. Do not alpha-sort the title.
    • +
  • 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.
    • +
  • If the work is illustrated, append a foreward 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.
    • +
  • Finally, do not append a trailing forward slash.
    • +
+
+
+
+

Publication date and release identifiers

+

There are several elements in the metadata describing the publication date, updated date, and revision number of the ebook. Generally these are not updated by hand; instead, the se prepare-release tool updates them automatically.

+
    +
  1. <dc:date> 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.
    2. +
  2. <meta property="dcterms:modified"> is a timestamp representing the last time this ebook file was modified. This changes often.
    3. +
  3. <meta property="se:revision-number"> 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 <meta property="dcterms:modified"> changes, the revision number is incremented.
    4. +
+
+
+

Book titles

+
+

Books without subtitles

+
    +
  1. The <dc:title id="title"> element contains the title.
    2. +
  2. The <meta property="file-as" refines="#title"> element contains alpha-sorted title, even if the alpha-sorted title is identical to the unsorted title.
    3. +
+
<dc:title id="title">The Moon Pool</dc:title> +<meta property="file-as" refines="#title">Moon Pool, The</meta>
+
<dc:title id="title">Short Fiction</dc:title> +<meta property="file-as" refines="#title">Short Fiction</meta>`
+
+
+

Books with subtitles

+
    +
  1. The <meta property="title-type" refines="#title">main</meta> element identifies the main part of the title.
    2. +
  2. A second <dc:title id="subtitle"> element contain the subtitle, and is refined with <meta property="title-type" refines="#subtitle">subtitle</meta>.
    3. +
  3. A third <dc:title id="fulltitle"> element contains the complete title on one line, with the main title and subtitle separated by a colon and space, and is refined with <meta property="title-type" refines="#fulltitle">extended</meta>.
    4. +
  4. All three <dc:title> elements have an accompanying <meta property="file-as"> element, even if the file-as value is the same as the title.
    5. +
+
<dc:title id="title">The Moon Pool</dc:title> +<meta property="file-as" refines="#title">Moon Pool, The</meta>
+
<dc:title id="title">The Man Who Was Thursday</dc:title> +<meta property="file-as" refines="#title">Man Who Was Thursday, The</meta> +<meta property="title-type" refines="#title">main</meta> +<dc:title id="subtitle">A Nightmare</dc:title> +<meta property="file-as" refines="#subtitle">Nightmare, A</meta> +<meta property="title-type" refines="#subtitle">subtitle</meta> +<dc:title id="fulltitle">The Man Who Was Thursday: A Nightmare</dc:title> +<meta property="file-as" refines="#fulltitle">Man Who Was Thursday, The</meta> +<meta property="title-type" refines="#fulltitle">extended</meta>
+
+ +
+

Books with numbers or abbreviations in the title

+

Books that contain numbers in their title may be difficult to find with a search query, if the query contains the Arabic number instead of the spelled-out number. For example, trying to find like Around the World in Eighty Days by searching for 80 instead of eighty. To facilitate such queries, a special <meta> element is included.

+
    +
  1. If a book title contains numbers or abbreviations, a <meta id="alternative-title" id="se:alternative-title" refines="#title"> element is placed after the main title block, containing the title with expanded or alternate spelling to facilitate possible search queries. +
    <dc:title id="title">Around the World in Eighty Days</dc:title> +<meta property="file-as" refines="#title">Around the World in Eighty Days</meta> +<meta id="alternative-title" id="se:alternative-title" refines="#title">Around the World in 80 Days</meta>
    +
    <dc:title id="title">File No. 113</dc:title> +<meta property="file-as" refines="#title">File No. 113</meta> +<meta id="alternative-title" id="se:alternative-title" refines="#title">File Number One Hundred and Thirteen</meta>
    +
    2. +
+
+
+
+

Book subjects

+
+

Library of Congress subjects

+

The <dc:subject> elements allow us to categorize the ebook. We use the Library of Congress categories assigned to the book for this purpose.

+
    +
  1. Each <dc:subject> has the id attribute set to subject-#, where # is a number starting at 1, without leading zeros, that increments with each subject.
    2. +
  2. The <dc:subject> elements are arranged sequentially in a single block.
    3. +
  3. If the transcription for the ebook comes from Project Gutenberg, the value of <dc:subject> element comes from the Project Gutenberg page for the ebook. Otherwise, the value comes from the Library of Congress catalog.
    4. +
  4. After the block of <dc:subject> elements there is a block of <meta property="meta-auth"> elements. The values of these elements represent the URLs at which each subject was found. Typically the value is the same for each element.
    5. +
  5. A <meta property="meta-auth"> element is required for each individual <dc:subject> element, even if the meta-auth URL is the same for all of the subjects.
    6. +
+

This example shows how to mark up the subjects for A Voyage to Arcturus, by David Lindsay:

+
<dc:subject id="subject-1">Science fiction</dc:subject> +<dc:subject id="subject-2">Psychological fiction</dc:subject> +<dc:subject id="subject-3">Quests (Expeditions) -- Fiction</dc:subject> +<dc:subject id="subject-4">Life on other planets -- Fiction</dc:subject> +<meta property="meta-auth" refines="#subject-1">https://www.gutenberg.org/ebooks/1329</meta> +<meta property="meta-auth" refines="#subject-2">https://www.gutenberg.org/ebooks/1329</meta> +<meta property="meta-auth" refines="#subject-3">https://www.gutenberg.org/ebooks/1329</meta> +<meta property="meta-auth" refines="#subject-4">https://www.gutenberg.org/ebooks/1329</meta>
+
+
+

SE subjects

+

Along with 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 the subject categories in a medium-sized bookstore, as opposed to the precise, detailed, heirarchal Library of Congress categories.

+

It’s the producer’s task to select appropriate SE subjects for the ebook. Usually just one or two of these categories will suffice.

+
+

All SE subjects

+
    +
  • Adventure
    • +
  • Autobiography
    • +
  • Biography
    • +
  • Childrens
    • +
  • Comedy
    • +
  • Drama
    • +
  • Fantasy
    • +
  • Fiction
    • +
  • Horror
    • +
  • Memoir
    • +
  • Mystery
    • +
  • Nonfiction
    • +
  • Philosophy
    • +
  • Poetry
    • +
  • Satire
    • +
  • Science Fiction
    • +
  • Shorts
    • +
  • Spirituality
    • +
  • Travel
    • +
+
+
+

Required subjects for certain kinds of books

+
    +
  1. Ebooks that are collections of short stories must have the SE subject Shorts.
    2. +
  2. Ebooks that are young adult or children’s books must have the SE subject Childrens.
    3. +
+
+
+
+
+

Book descriptions

+

An ebook has two kinds of descriptions: a short <dc:description> element, and a much longer <meta property="se:long-description"> element.

+
+

The short description

+

The <dc:description> element contains a short, single-sentence summary of the ebook.

+
    +
  1. The description is a single complete sentence ending in a period, not a sentence fragment or restatment of the title.
    2. +
  2. The description is typogrified, i.e. it contains Unicode curly quotes, em-dashes, and the like.
    3. +
+
+
+

The long description

+

The <meta property="se:long-description"> element contains a much longer description of the ebook.

+
    +
  1. The long description is a non-biased, encyclopedia-like description of the book, including any relevant publication history, backstory, or historical notes. It is as detailed as possible without giving away plot spoilers. It does not impart the producer’s opinions of the book, or include content warnings. Think along the lines of a Wikipedia-like summary of the book and its history, but under no circumstances can a producer copy and paste from Wikipedia!
    2. +
  2. The long descriptions is typogrified, i.e. it contains Unicode curly quotes, em-dashes, and the like.
    3. +
  3. The long description is in escaped HTML, with the HTML beginning on its own line after the <meta property="se:long-description"> element. + +
    4. +
  4. Long description HTML follows the code style conventions of this manual.
    5. +
  5. The long description element is directly followed by: <meta property="meta-auth" refines="#long-description">https://standardebooks.org</meta>
    6. +
+
+
+
+

Book language

+
    +
  1. The <dc:language> element follows the long description block. It contains the IETF language tag for the language that the work is in. Usually this is either en-US or en-GB.
    2. +
+
+
+

Book transcription and page scan source

+
    +
  1. The <dc:source> elements represent URLs to sources for the transcription the ebook is based on, and page scans of the print sources used to correct the transcriptions.
    2. +
  2. <dc:source> URLs are in https where possible.
    3. +
  3. A book can contain more than one such element if multiple sources for page scans were used.
    4. +
+
+
+

Book production notes

+
    +
  1. The <meta property="se:production-notes"> element contains any of the ebook producer’s production notes. For example, the 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; or that certain archaic spellings were retained as a matter of prose style specific to this ebook.
    2. +
  2. The <meta property="se:production-notes"> element is not present if there are no production notes.
    3. +
+
+
+

Readability metadata

+

These two elements are automatically computed by the se prepare-release tool.

+
    +
  1. The <meta property="se:word-count"> element contains an integer representing the ebooks total word count, excluding some SE files like the colophon and Uncopyright.
    2. +
  2. The <meta property="se:reading-ease.flesch"> element contains a decimal representing the computed Flesch reading ease for the book.
    3. +
+
+
+

Additional book metadata

+
    +
  1. <meta property="se:url.encyclopedia.wikipedia"> contains the Wikipedia URL for the book. This element is not present if there is no Wikipedia entry for the book.
    2. +
  2. <meta property="se:url.vcs.github"> contains the SE GitHub URL for this ebook. This is calculated by taking the string https://github.com/standardebooks/ and appending the SE identifier, without https://standardebooks.org/ebooks/, and with forward slashes replaced by underscores.
    3. +
+
+
+

General contributor rules

+

The following apply to all contributors, including the author(s), translator(s), and illustrator(s).

+
    +
  1. If there is exactly one contributor in a set (for example, only one author, or only one translator) then the <meta property="display-seq"> element is ommitted for that contributor.
    2. +
  2. If there is more than one contributor in a set (for example, multiple authors, or translators) then the <meta property="display-seq"> element is specified for each contributor, with a value equal to their position in the SE identifier.
    3. +
  3. The epub standard specifies that in a set of contributors, if at least one has the display-seq attribute, then other contributors in the set without the display-seq attribute are ignored. For SE purposes, this also means they will be excluded from the SE identifier.
    4. +
  4. By SE convention, contributors with <meta property="display-seq">0</meta> are excluded from the SE identifier.
    5. +
+
+
+

The author metadata block

+
    +
  1. <dc:creator id="author"> contains the author’s name as it appears on the cover.
    2. +
  2. If there is more than one author, the first author’s id is author-1, the second author-2, and so on.
    3. +
  3. <meta property="file-as" refines="#author"> contains the author’s name as filed alphabetically. This element is included even if it’s identical to <dc:creator>.
    4. +
  4. <meta property="se:name.person.full-name" refines="#author"> contains the author’s full name, with any initials or middle names expanded, and including any titles. This element is not included if the value is identical to <dc:creator>.
    5. +
  5. <meta property="alternate-script" refines="#author"> contains 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. This element is not included if not applicable.
    6. +
  6. <meta property="se:url.encyclopedia.wikipedia" refines="#author"> contains the URL of the author’s Wikipedia page. This element is not included if there is no Wikipedia page.
    7. +
  7. <meta property="se:url.authority.nacoaf" refines="#author"> contains the URL of the author’s Library of Congress Names Database page. It does not include the .html file extension. This element is not included if there is no LoC Names database entry. + +
    8. +
  8. <meta property="role" refines="#author" scheme="marc:relators"> contains the MARC relator tag for the roles the author played in creating this book. +

    There is always one element with the value of aut. There may be additional elements for additional values, if applicable. For example, if the author also illustrated the book, there would be an additional <meta property="role" refines="#author" scheme="marc:relators">ill</meta> element.

    +
    9. +
+

This example shows a complete author metadata block for Short Fiction, by Anton Chekhov:

+
<dc:creator id="author">Anton Chekhov</dc:creator> +<meta property="file-as" refines="#author">Chekhov, Anton</meta> +<meta property="se:name.person.full-name" refines="#author">Anton Pavlovich Chekhov</meta> +<meta property="alternate-script" refines="#author">Анто́н Па́влович Че́хов</meta> +<meta property="se:url.encyclopedia.wikipedia" refines="#author">https://en.wikipedia.org/wiki/Anton_Chekhov</meta> +<meta property="se:url.authority.nacoaf" refines="#author">http://id.loc.gov/authorities/names/n79130807</meta> +<meta property="role" refines="#author" scheme="marc:relators">aut</meta>
+
+
+

The translator metadata block

+
    +
  1. If the work is translated, the <dc:contributor id="translator"> metadata block follows the author metadata block.
    2. +
  2. If there is more than one translator, then the first translator's id is translator-1, the second translator-2, and so on.
    3. +
  3. Each block is identical to the author metadata block, but with <dc:contributor id="translator"> instead of <dc:creator id="author">.
    4. +
  4. The MARC relator tag is trl: <meta property="role" refines="#translator" scheme="marc:relators">trl</meta>.
    5. +
  5. Translators often annotate the work; if this is the case, the additional MARC relator tag ann is included in a separate <meta property="role" refines="#translator" scheme="marc:relators"> element.
    6. +
+
+
+

The illustrator metadata block

+
    +
  1. If the work is illustrated by a person who is not the author, the illustrator metadata block follows.
    2. +
  2. If there is more than one illustrator, the first illustrator's id is illustrator-1, the second illustrator-2, and so on.
    3. +
  3. Each block is identical to the author metadata block, but with <dc:contributor id="illustrator"> instead of <dc:creator id="author">.
    4. +
  4. The MARC relator tag is ill: <meta property="role" refines="#illustrator" scheme="marc:relators">ill</meta>.
    5. +
+
+
+

The cover artist metadata block

+

The “cover artist” is the artist who painted the art the producer selected for the SE ebook cover.

+
    +
  1. The cover artist metadata block is identical to the author metadata block, but with <dc:contributor id="artist"> instead of <dc:creator id="author">.
    2. +
  2. The MARC relator tag is art: <meta property="role" refines="#artist" scheme="marc:relators">art</meta>.
    3. +
+
+
+

Metadata for additional contributors

+

Occasionally a book may have other contributors besides the author, translator, and illustrator; for example, a person who wrote a preface, an introduction, or who edited the work or added endnotes.

+
    +
  1. Additional contributor blocks are identical to the author metadata block, but with <dc:contributor> instead of <dc:creator>.
    2. +
  2. The id attribute of the <dc:contributor> is the lowercase, URL-safe, fully-spelled out version of the MARC relator tag. For example, if the MARC relator tag is wpr, the id attribute would be writer-of-preface.
    3. +
  3. The MARC relator tag is one that is appropriate for the role of the additional contributor. Common roles for ebooks are: wpr, ann, and aui.
    4. +
+
+
+

Transcriber metadata

+
    +
  1. If the ebook is based on a transcription by someone else, like Project Gutenberg, then transcriber blocks follow.
    2. +
  2. If there is more than one transcriber, the first transcriber is transcriber-1, the second transcriber-2, and so on.
    3. +
  3. The <meta property="file-as" refines="#transcriber-1"> element contains an alpha-sorted representation of the transcriber’s name.
    4. +
  4. The MARC relator tag is trc: <meta property="role" refines="#transcriber-1" scheme="marc:relators">trc</meta>.
    5. +
  5. If the transcriber’s personal homepage is known, the element <meta property="se:url.homepage" refines="#transcriber-1"> is included, whose value is the URL of the transcriber’s homepage. The URL must link to a personal homepage only; no products, services, or other endorsements, commercial or otherwise.
    6. +
+
+
+

Producer metadata

+

These elements describe the SE producer who produced the ebook for the Standard Ebooks project.

+
    +
  1. If there is more than one producer, the first producer is producer-1, the second producere-2, and so on.
    2. +
  2. The producer metadata block is identical to the author metadata block, but with <dc:contributor id="producer-1"> instead of <dc:creator id="author">.
    3. +
  3. If the producer’s personal homepage is known, the element <meta property="se:url.homepage" refines="#producer-1"> is included, whose value is the URL of the transcriber’s homepage. The URL must link to a personal homepage only; no products, services, or other endorsements, commercial or otherwise.
    4. +
  4. The MARC relator tags for the SE producer usually include all of the following: +
      +
    • bkp: The producer produced the ebook.
      • +
    • blw: The producer wrote the blurb (the long description).
      • +
    • cov: The producer selected the cover art.
      • +
    • mrk: The producer wrote the HTML markup for the ebook.
      • +
    • pfr: The producer proofread the ebook.
      • +
    • tyg: The producer reviewed the typography of the ebook.
      • +
    +
    5. +
+
+
+

The ebook manifest

+

The <manifest> element is a required part of the epub spec that defines a list of files within the ebook.

+ +
    +
  1. The manifest is in alphabetical order.
    2. +
  2. The id attribute is the basename of the href attribute.
    3. +
  3. Files which contain SVG images have the additional properties="svg" property in their manifest item.
    4. +
  4. The manifest item for the table of contents file has the additional properties="nav" property.
    5. +
  5. The manifest item for the cover image has the additional properties="cover-image" property.
    6. +
+
+
+

The ebook spine

+

The <spine> element is a required part of the epub spec that defines the reading order of the files in the ebook.

+ +
+
+
+
+ diff --git a/www/manual/1.0/semantics.php b/www/manual/1.0/semantics.php new file mode 100644 index 00000000..cf2135b5 --- /dev/null +++ b/www/manual/1.0/semantics.php @@ -0,0 +1,116 @@ + '4. Semantics - The Standard Ebooks Manual', 'highlight' => 'contribute', 'manual' => true]) ?> +
+
+ +
+

Semantics

+

Semantics convey what an element or section mean or are, instead of merely conveying how they are visually presented.

+

For example, the following snippet visually presents a paragraph, followed by a quotation from a poem:

+
<div>“All done in the tying of a cravat,” Sir Percy had declared to his clique of admirers.</div> +<div style="margin: 1em;"> + <div>“We seek him here, we seek him there,<br/> + Those Frenchies seek him everywhere.<br/> + Is he in heaven?⁠—Is he in hell,<br/> + That demmed, elusive Pimpernel?”</div> +</div>
+

While that snipped might visually present the text as a paragraph followed by a quotation of verse, the actual HTML tells us nothing about what these lines of text actually are.

+

Compare the above snippet to this next snippet, which renders almost identically but uses semantically-correct tags and epub's semantic inflection to tell us what the text is:

+
<p>“All done in the tying of a cravat,” Sir Percy had declared to his clique of admirers.</p> +<blockquote epub:type="z3998:poem"> + <p> + <span>“We seek him here, we seek him there,</span> + <br/> + <span>Those Frenchies seek him everywhere.</span> + <br/> + <span>Is he in heaven?⁠—Is he in hell,</span> + <br/> + <span>That demmed, elusive Pimpernel?”</span> + </p> +</blockquote>
+

By inspecting the tags above, we can see that the first line is a semantic paragraph (<p> stands for paragraph, of course); the paragraph is followed by a semantic block quotation, which browsers automatically render with a margin; the quotation is a poem; the poem has one stanza; and there are four lines in the poem. (By SE convention, <p> elements in verse are stanzas and <span> elements are lines.)

+
+

Semantic Tags

+

Epub allows for the use of the full range of tags in the HTML5 spec. Each tag has a semantic meaning, and each tag in an SE ebook is carefully considered before use.

+

Below is an incomplete list of HTML5 elements and their semantic meanings. These are some of the most common elements encountered in an ebook.

+
+

Block-level tags

+

Block-level tags are by default rendered with { display: block; }. See the complete list of block-level tags.

+
    +
  1. Sectioning block-level tags denote major structural divisions in a work. +
      +
    1. <body>: The top-level tag in any XHTML file. Must contain a direct child that is either a <section> or <article>.
      2. +
    2. <section>: A major structural division in a work. Typically a part, volume, chapter, or subchapter. Semantically a <section> cannot stand alone, but is part of a larger work.
      3. +
    3. <article>: An item in a larger work that could be pulled out of the work and serialized or syndicated separately. For example, a single poem in a poetry collection, or a single short story in a short story collection; but not a single poem in a larger novel.
      4. +
    +
    2. +
  2. Other block-level tags have well-defined semantic meanings. +
      +
    1. <p>: A paragraph of text.
      2. +
    2. <blockquote>: A quotation displayed on the block level. This may include non-speech “quotations” like business cards, headstones, telegrams, letters, and so on.
      3. +
    3. <figure>: Encloses a photograph, chart, or illustration, represented with an <img> element. Optionally includes a <figcaption> element for a context-appropriate caption.
      4. +
    4. <figcaption>: Only appears as a child of <figure>. Represents a context-appropriate caption for the sibling <img>. A caption is not the same as an <img> element’s alt text. alt text is strictly a textual description of the image used for screen readers, whereas <figcaption> has more freedom in its contents, depending on its context.
      5. +
    5. <header>: Denotes a header section applying to its direct parent. <header> is typically used for chapter headers, but can also be used in <blockquote>s or other block-level tags that require header styling.
      6. +
    6. <footer>: Denotes a footer section applying to its direct parent. Typically used to denote signatures in sections like prefaces, forewords, letters, telegrams, and so on.
      7. +
    7. <hr>: Denotes a thematic break. <hr> is not used any place a black border is desired; it strictly denotes a thematic break.
      8. +
    8. <ol>: Denotes an ordered list. Ordered lists are automatically numbered by the renderer.
      9. +
    9. <ul>: Denotes an unordered list. Ordered lists are bulleted by the renderer.
      10. +
    10. <li>: Denotes an list item in a parent <ol> or <ul>.
      11. +
    11. <table>: Denotes a tabular section, for example when displaying tabular data, or reports or charts where a tabular appearance is desired.
      12. +
    +
    3. +
  3. <div> elements are almost never appropriate, as they have no semantic meaning. However, they may in rare occasions be used to group related elements in a situation where no other semantic tag is appropriate.
    4. +
+
+
+

Inline tags

+

Inline tags are by default rendered with { display: inline; }. See the complete list of inline tags.

+
    +
  1. <em>: Text rendered in italics, with the semantic meaning of emphasize speech, or speech spoken in a different tone of voice; for example, a person shouting, or putting stress on a particular word.
    2. +
  2. <i>: Text rendered in italics, without any explicit semantic meaning. Because <i> lacks semantic meaning, the epub:type attribute is added with appropriate semantic inflection to describe the contents of the tag. +
    <p>The <abbr class="initialism">HMS</abbr> <i epub:type="se:name.vessel.ship">Bounty</i>.</p>
    +
    3. +
  3. <b>: Text rendered in small caps, without any explicit semantic meaning. Because <i> lacks semantic meaning, the epub:type attribute is added with appropriate semantic inflection to describe the contents of the tag.
    4. +
  4. <span>: Plain inline text that requires specific styling or semantic meaning that cannot be achieved with any other semantically meaningful inline tag. Typically used in conjunction with a class or epub:type attribute.
    5. +
+
+
+
+

Semantic Inflection

+

The epub spec allows for semantic inflection, which is a way of adding semantic metadata to elements in the ebook document.

+

For example, an ebook producer may want to convey that the contents of a certain <section> are part of a chapter. They would do that by using the epub:type attribute:

+
<section epub:type="chapter">...</section>
+
    +
  1. The epub spec includes a vocabulary that can be used in the epub:type attribute. This vocabulary has priority when selecting a semantic keyword, even if other vocabularies contain the same one.
    2. +
  2. The epub spec might not contain a keyword necessary to describe the semantics of a particular element. In that case, the z3998 vocabulary is consulted next. +

    Keywords using this vocabulary are preceded by the z3998 namespace.

    +
    <blockquote epub:type="z3998:letter">...</blockquote>
    +
    3. +
  3. If the z3998 vocabulary doesn’t have an appropriate keyword, the Standard Ebooks vocabulary is consulted next. +

    Keywords using this vocabulary are preceded by the se namespace.

    +

    Unlike other vocabularies, the Standard Ebooks vocabulary is organized hierarchically. A complete vocabulary entry begins with the root vocabulary entry, with subsequent children separated by ..

    +
    The <i epub:type="se:name.vessel.ship"><abbr class="initialism">HMS</abbr> Bounty</i>.
    +
    4. +
  4. The epub:type attribute can have multiple keywords separated by spaces, even if the vocabularies are different. +
    <section epub:type="chapter z3998:letter">...</section>
    +
    5. +
  5. Child elements inherit the semantics of their parent element. +

    In this example, both chapters are considered to be “non-fiction,” because they inherit it from the <body> element:

    +
    <body epub:type="z3998:non-fiction"> + <section id="chapter-1" epub:type="chapter"> + <h2 epub:type="title z3998:roman">I</h2> + ... + </section> + <section id="chapter-2" epub:type="chapter"> + <h2 epub:type="title z3998:roman">II</h2> + ... + </section> +</body>
    +
    6. +
+
+
+
+
+ diff --git a/www/manual/1.0/table-of-contents-patterns.php b/www/manual/1.0/table-of-contents-patterns.php new file mode 100644 index 00000000..3c342888 --- /dev/null +++ b/www/manual/1.0/table-of-contents-patterns.php @@ -0,0 +1,158 @@ + '7. Table of Contents Patterns - The Standard Ebooks Manual', 'highlight' => 'contribute', 'manual' => true]) ?> +
+
+ +
+

Table of Contents Patterns

+

The table of contents (the ToC) is not viewable as a page in the ebook's reading order. Instead, the reader's ereading system displays the ToC as part of its reading interface.

+

These rules outline how to structure the ToC. Typically, the output of se print-toc constructs ToCs according to these rules, without further changes being necessary.

+
+

The ToC <nav> element

+
    +
  1. The first child of the Toc's <body> tag is a <nav> element with the semantic inflection toc.
    2. +
  2. The first child of the <nav> element is a <h2 epub:type="title">Table of Contents</h2> element.
    3. +
  3. The second child of the <nav> element is an <ol> element representing the items in the Table of Contents.
    4. +
+
+

The top-level <ol> element

+

The <nav> element's top-level <ol> element contains a list of items in the Table of Contents.

+
    +
  1. The first child is a link to the titlepage. +
    <li> + <a href="text/titlepage.xhtml">Titlepage</a> +</li>
    +
    2. +
  2. The second child is a link to the imprint. +
    <li> + <a href="text/imprint.xhtml">Imprint</a> +</li>
    +
    3. +
  3. The second-to-last child is a link to the colophon. +
    <li> + <a href="text/colophon.xhtml">Colophon</a> +</li>
    +
    4. +
  4. The second-to-last child is a link to the Uncopyright. +
    <li> + <a href="text/uncopyright.xhtml">Uncopyright</a> +</li>
    +
    5. +
  5. In books with half title pages, the half title page is listed in the ToC and the next sibling is an <ol> element containing the book's contents. +
    <li> + <a href="text/halftitle.xhtml">The Moon Pool</a> + <ol> + <li> + <a href="text/chapter-1.xhtml"><span epub:type="z3998:roman">I</span>: The Thing on the Moon Path</a> + </li> + <li> + <a href="text/chapter-2.xhtml"><span epub:type="z3998:roman">II</span>: “Dead! All Dead!”</a> + </li>
    +
    6. +
+
+
+

<li> descendents

+
    +
  1. Each <li> contains an <a> tag pointing to a file or hash, and optionally also contains an <ol> element representing a nested series of ToC items.
    2. +
  2. If an <li> element contains a nested <ol> element, that <li>'s first child is an <a> element that points to the beginning of that section. +
    <li> + <a href="text/halftitle.xhtml">Sybil</a> + <ol> + <li> + <a href="text/book-1.xhtml">Book <span epub:type="z3998:roman">I</span></a> + <ol> + <li> + <a href="text/chapter-1-1.xhtml" epub:type="z3998:roman">I</a> + </li>
    +
    3. +
  3. Roman numerals in the ToC have the semantic inflection of z3998:roman. A <span> element is included if the entire contents of the <a> element are not a Roman numeral. +
    <li> + <a href="text/chapter-1.xhtml">I</a> +</li>
    +
    <li> + <a href="text/chapter-1.xhtml"><span epub:type="z3998:roman">I</span></a> +</li>
    +
    <li> + <a href="text/chapter-1.xhtml" epub:type="z3998:roman">I</a> +</li>
    +
    <li> + <a href="text/book-1.xhtml">Book <span epub:type="z3998:roman">I</span></a> + <ol> + ... + </ol> +</li>
    +
    4. +
+
+
+

<a> descendents

+
    +
  1. Chapters without titles are represented by their Roman ordinal, without the word Chapter: +
    <a epub:type="title z3998:roman">XI</a>
    +
    2. +
  2. Chapters with titles are represented by their Roman ordinal, followed by a colon and a space, followed by the chapter title: +
    <a href="text/chapter-3.xhtml"><span epub:type="z3998:roman">III</span>: The Moon Rock</a>
    +
    3. +
  3. Chapters with unique identifiers (i.e. not Chapter, but something unique to the style of the book, like Book or Stave), include that unique identifier in the <a> element: +
    <a href="text/chapter-1.xhtml">Stave <span epub:type="z3998:roman">I</span>: Marley’s Ghost</a>
    +
    4. +
  4. High-level sections (like parts or divisions) without titles are represented by their identifier (like Book or Part), followed by their Roman ordinal: +
    <a href="text/book-1.xhtml">Book <span epub:type="z3998:roman">I</span></a>
    +
    5. +
  5. High-level sections (like parts or divisions) with titles include the title: +
    <a href="text/book-10.xhtml">Book <span epub:type="z3998:roman">X</span>: The Boys</a>
    +
    6. +
  6. Sections that are not chapters do not include their subtitles in the ToC: +
    <a href="text/epilogue.xhtml">Epilogue: A Morning Call</a>
    +
    <a href="text/epilogue.xhtml">Epilogue</a>
    +
    7. +
  7. High-level sections (like parts or divisions) with titles include the title: +
    <a href="text/book-10.xhtml">Book <span epub:type="z3998:roman">X</span>: The Boys</a>
    +
    8. +
  8. Entries for half title pages do not include the subtitle: +
    <li> + <a href="text/halftitle.xhtml">His Last Bow</a> + <ol> + ... + </ol> +</li>
    +
    9. +
+
+
+
+

The landmarks <nav> element

+

After the first <nav> element, there is a second <nav> element with the semantic inflection of landmarks.

+
    +
  1. The first child is an <h2 epub:type="title">Landmarks</h2> element.
    2. +
  2. The second child is an <ol> element listing the major structural divisions of the book.
    3. +
+
+

<li> descendents

+

Each <li> element contains a link to one of the major structural divisions of the book. In general, a structural division is any section of the book that is not part of the body text.

+
    +
  1. Each <li> element has the computed semantic inflection of top-level <section> element in the file. The computed semantic inflection includes inherited semantic inflection from the <body> tag. +
    <li> + <a href="text/preface.xhtml" epub:type="frontmatter preface">Preface</a> +</li>
    +
    2. +
  2. The body text is represented by a link to the first file of the body text. In a prose novel, this is usually Chapter 1 or Part 1. In a collection this is usually the first item, like the first short story in a short story collection. The text is the title of the work as represented in the metadata <dc:title> element. +
    <li> + <a href="text/book-1.xhtml" epub:type="bodymatter z3998:fiction">Sybil</a> +</li>
    +
    <li> + <a href="text/chapter-1.xhtml" epub:type="bodymatter z3998:fiction">The Moon Pool</a> +</li>
    +
    <li> + <a href="text/the-adventure-of-wisteria-lodge.xhtml" epub:type="bodymatter z3998:fiction">His Last Bow</a> +</li>
    +
    3. +
+
+
+
+
+
+ diff --git a/www/manual/1.0/the-structure-of-an-ebook.php b/www/manual/1.0/the-structure-of-an-ebook.php new file mode 100644 index 00000000..f5d1a337 --- /dev/null +++ b/www/manual/1.0/the-structure-of-an-ebook.php @@ -0,0 +1,109 @@ + '3. The Structure of an Ebook - The Standard Ebooks Manual', 'highlight' => 'contribute', 'manual' => true]) ?> +
+
+ +
+

The Structure of an Ebook

+ +

Books consist of three major partitions: Front Matter, Body Matter, and Back Matter.

+

These terms become important when building the Table of Contents (ToC). The Landmarks section of the ToC requires items to be labeled with the appropriate partition identifier. See ToC Patterns for more information about the ToC.

+
+

Front matter

+

Front matter is material that appears before to the main content of the work. It includes such items as a dedication, an epigraph, an introduction, and so on.

+
+

Cover

+

The cover presents the outer appearance of the book, usually consisting of an image, the title of the book and the author’s name. For Standard Ebooks productions, the cover is an SVG image generated from template that combines the book title and author, and a background image. The se build-images tool generates the cover image used for distribution.

+
+
+

Title page

+

The title page lists the title of the book and the author’s name. For Standard Ebooks productions, the title page contains an SVG image generated by the se create-draft tool, which is then compiled for distribution using the se build-images tool.

+
+
+

Imprint

+

The imprint contains information about the publisher of the book. For Standard Ebooks productions, a template file is provided and the producer modifies it to suit the particular ebook.

+
+
+

Dedication

+

An inscription at the start of a work and is usually a tribute to some person or persons whom the author wishes to honor.

+
+
+

Epigraph

+

A quotation or poem at the start of a book which may set the mood or inspire thoughts about the work to come.

+

If the epigraph is a poem or quotation from poetry, it must follow the standards for verse described in High-Level Structural Patterns

+
+
+

Acknowledgements

+

A list of persons or organizations whom the author wishes to thank, generally for helping with the creation of the book. The acknowledgements can also be part of the back matter of the book, depending on where the author placed them.

+
+
+

Foreword

+

A preliminary section containing information about the book, generally written by someone other than the author.

+
+
+

Preface

+

A preliminary section which states the subject of the book and its aims, generally written by the author of the work.

+
+
+

Introduction

+

An introduction is typically found in non-fiction works. It is written by the book’s author and sets out the book’s main argument.

+
+
+

Half title

+

In books which include front matter, the half title page marks the start of the body matter.

+
    +
  1. The half title lists the title of the book, but not the author.
    2. +
  2. A half title is required if there is any front matter in the book.
    3. +
+
+
+

Table of Contents

+

Also known as the ”ToC.” The Table of Contents lists the main headings in the book. In traditionally printed books, the table of contents is part of the front matter of the book.

+
    +
  1. In Standard Ebooks productions, the table of contents is ommitted from the ebook's spine and is instead presented to the reader via their ereader’s ToC feature.
    2. +
+
+
+
+

Body matter

+

The body matter is the main content of the book. It is typically divided into chapters, or in the case of a collection, individual stories, poems, or articles. It may be structured at the highest level into larger divisions such as volumes or parts. Besides the contents of the book itself, it may also include:

+
+

Prologue

+

A prologue is generally found only in works of fiction. It may introduce characters, set up background information, or bring forward a critical part of the action to which the story leads.

+

A prologue is generally part of the body matter, unless the prologue is a fictional element of a frame narrative. In that case, it may be appropriate to place it in front of the half title and give it a different title, while keeping the prologue semantic inflection.

+
+
+

Epilogue

+

An epilogue is generally found only in works of fiction. It typically winds up the action or briefly tells the subsequent history of major characters. An epilogue should therefore have similar structure to the chapters of a book.

+
+
+
+

Back matter

+

Back matter is material which follows the main content, but could be separated from the main content. It might include endnotes, an appendix, an afterword, a colophon, and so on.

+
+

Afterword

+

A concluding section of a book, typically but not necessarily written by the author, which stands outside the main story of a work of fiction, or the main argument of a work of non-fiction. It may add additional information or comment on the book and its production.

+
+
+

List of Illustrations

+

Also known as the “LoI,” the list of illustrations is an index to the illustrations in a book. The items are included as part of a list and linked to the points in the text where the illustration appears.

+
+
+

Endnotes

+

A list of notes to the text. Each item is given a unique sequential number and linked to the point in the text to which the note refers. If the text originally has footnotes, they are converted to endntoes.

+
+
+

Colophon

+

The colophon contains information about the publisher of the book, the author, the original publication date, the edition, its publication date, the cover artist and other information relevant to the particular release of a book. A Standard Ebooks colophon is standardized and follows a common pattern.

+
+
+

Copyright Page

+

The copyright page includes information about the copyright status of the work. All Standard Ebooks are in the US Public domain, and use a standardized “copyright” page to explain this.

+

Copyright pages are usually part of the front matter of a book, but in the case of Standard Ebooks productions they are back matter, and the last item in the book.

+
+
+
+
+
+ diff --git a/www/manual/1.0/typography.php b/www/manual/1.0/typography.php new file mode 100644 index 00000000..abee50ed --- /dev/null +++ b/www/manual/1.0/typography.php @@ -0,0 +1,697 @@ + '8. Typography - The Standard Ebooks Manual', 'highlight' => 'contribute', 'manual' => true]) ?> +
+
+ +
+

Typography

+
+

Section titles and ordinals

+
    +
  1. Section ordinals in the body text are set in Roman numerals.
    2. +
  2. Section ordinals in a file's <title> element are set in Arabic numerals. +
    <title>Chapter VII</title>
    +
    <title>Chapter 7</title>
    +
    3. +
  3. Section titles are titlecased according to the output of se titlecase. Section titles are not all-caps or small-caps.
    4. +
  4. Section titles do not have trailing periods.
    5. +
  5. Chapter titles omit the word Chapter, unless the word used is a stylistic choice for prose style purposes. Chapters with unique identifiers (i.e. not Chapter, but something unique to the style of the book, like Book or Stave) do include that unique identifier in the title. +
    <h2 epub:type="title">Chapter <span epub:type="z3998:roman">II</span></h2>
    +
    <h2 epub:type="title z3998:roman">II</h2>
    +
    <h2 epub:type="title">Stave <span epub:type="z3998:roman">III</span></h2>
    +

    In special cases it may be desirable to retain Chapter for clarity. For example, Frankenstein has “Chapter” in titles to differentiate between the “Letter” sections.

    +
    6. +
+
+
+

Italics

+
    +
  1. Using both italics and quotes (outside of the context of quoted dialog) is usually not necessary. Either one or the other is used based on the rules above.
    2. +
  2. Words and phrases that require emphasis are italicized with the <em> element. +
    <p>“Perhaps <em>he</em> was there,” Raoul said, at last.</p>
    +
    3. +
  3. Strong emphasis, like shouting, may be set in small caps with the <strong> element. +
    <p>“<strong>Can’t</strong> I?” screamed the unhappy creature to himself.</p>
    +
    4. +
  4. When a short phrase within a longer clause is italicized, trailing punctuation that may belong to the containing clause is not italicized. +
    <p>“Look at <em>that!</em>” she shouted.</p>
    +
    <p>“Look at <em>that</em>!” she shouted.</p>
    +
    5. +
  5. When an entire clause is italicized, trailing punctuation is italicized, unless that trailing punctuation is a comma at the end of dialog. +

    <p>“<em>Charge!</em>” she shouted.</p>

    +

    <p>“<em>But I want to</em>,” she said.</p>

    +
    6. +
  6. Words written to be read as sounds are italicized with <i>. +
    <p>He could hear the dog barking: <i>Ruff, ruff, ruff!</i></p>
    +
    7. +
+
+

Italicizing individual letters

+
    +
  1. Individual letters that are read as referring to letters in the alphabet are italicized with the <i> element.
    2. +
+
+
<p>He often rolled his <i>r</i>’s.</p>
+
+
    +
  1. Individual letters that are read as referring names or the shape of the letterform are not italicized. +
    <p>...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>She was learning her A B Cs.</p>
    +
    <p>His trident had the shape of an E.</p>
    +
    2. +
  2. The ordinal nth is set with an italicized n, and without a hyphen. +
    <p>The <i>n</i>th degree.</p>
    +
    3. +
+
+
+

Italicizing non-English words and phrases

+
    +
  1. Non-English words and phrases that are not in Merriam-Webster are italicized. +
    <p>The <i xml:lang="fr">corps de ballet</i> was flung into consternation.</p>
    +
    2. +
  2. Foreign words that are proper names, or are in proper names, are not italicized, unless the name itself would be italicized according to the rules for italicizing or quoting names and titles. Such words are wrapped in a <span xml:lang="LANGUAGE"> element, to assist screen readers with pronunciation. +
    <p>She got off the metro at the <i xml:lang="fr">Place de Clichy</i> stop, next to the <i xml:lang="fr">PLe Bon Petit Déjeuner restaurant</i>.</p>
    +
    <p>“<i xml:lang="fr">Où est le métro?</i>” he asked, and she pointed to <span xml:lang="fr">Place de Clichy</span>, next to the <span xml:lang="fr">Le Bon Petit Déjeuner</span> restaurant.
    +
    3. +
  3. If certain foreign words are used so frequently in the text that italicizing them at each instance would be distracting to the reader, then only the first instance is italicized. Subsequent instances are wrapped in a <span xml:lang="LANGUAGE"> element.
    4. +
  4. Words and phrases that are originally non-English in origin, but that can now be found in Merriam-Webster, are not italicized. +
    <p>Sir Percy’s bon mot had gone the round of the brilliant reception-rooms.</p>
    +
    5. +
  5. Inline-level italics are set using the <i> element with an xml:lang attribute corresponding to the correct IETF language tag.
    6. +
  6. Block-level italics are set using an xml:lang attribute on the top-level block element, with the style of font-style: italic. +

    In this example, note the additional namespace declaration, and that we target descendants of the <body> element; otherwise, the entire <body> element would receive italics!

    +
    @namespace xml "http://www.w3.org/XML/1998/namespace"; + +body [xml|lang]{ + font-style: italic; +}
    +
    <blockquote epub:type="z3998:verse" xml:lang="la"> + <p> + <span>—gelidas leto scrutata medullas,</span> + <br/> + <span>Pulmonis rigidi stantes sine vulnere fibras</span> + <br/> + <span>Invenit, et vocem defuncto in corpore quaerit.</span> + </p> +</blockquote>
    +
    7. +
+
+
+

Italicizing or quoting newly-used English words

+
    +
  1. When introducing new terms, foreign or technical terms are italicized, but terms composed of common English are set in quotation marks. +
    <p>English whalers have given this the name “ice blink.”</p> + +<p>The soil consisted of that igneous gravel called <i>tuff</i>.</p>
    +
    2. +
  2. English neologisms in works where a special vocabulary is a regular part of the narrative are not italicized. For example science fiction works may necessarily contain made-up English technology words, and those are not italicized. However, “alien” language in such works is italicized.
    3. +
+
+
+

Italics in names and titles

+
    +
  1. Place names, like pubs, bars, or buildings, are not quoted.
    2. +
  2. The names of publications, music, and art that can stand alone are italicized; additionally, the names of transport vessels are italicized. These include, but are not limited to: +
      +
    • Periodicals like magazines, newspapers, and journals.
      • +
    • Publications like books, novels, plays, and pamphlets, except “holy texts,” like the Bible or books within the Bible.
      • +
    • Long poems and ballads, like the Iliad, that are book-length.
      • +
    • Long musical compositions or audio, like operas, music albums, or radio shows.
      • +
    • Long visual art, like films or a TV show series.
      • +
    • Visual art, like paintings or sculptures.
      • +
    • Transport vessels, like ships.
      • +
    +
    3. +
  3. The names of short publications, music, or art, that cannot stand alone and are typically part of a larger collection or work, are quoted. These include, but are not limited to: +
      +
    • Short musical compositions or audio, like pop songs, arias, or an episode in a radio series.
      • +
    • Short prose like novellas, shot stories, or short (i.e. not epic) poems.
      • +
    • Chapter titles in a prose work.
      • +
    • Essays or individual articles in a newspaper or journal.
      • +
    • Short visual art, like short films or episodes in a TV series.
      • +
    +
    4. +
+
+

Examples

+
<p>He read “Candide” while having a pint at the “King’s Head.”</p>
+
<p>He read <i epub:type="se:name.publication.book">Candide</i> while having a pint at the King’s Head.</p>
+
+
+
+

Taxonomy

+
    +
  1. Binomial names (generic, specific, and subspecific) are italicized with a <i> element having the z3998:taxonomy semantic inflection. +
    <p>A bonobo monkey is <i epub:type="z3998:taxonomy">Pan paniscus</i>.</p>
    +
    2. +
  2. Family, order, class, phylum or division, and kingdom names are capitalized but not italicized. +
    <p>A bonobo monkey is in the phylum Chordata, class Mammalia, order Primates.</p>
    +
    3. +
  3. If a taxonomic name is the same as the common name, it is not italicized.
    4. +
  4. The second part of the binomial name follows the capitalization style of the source text. Modern usage requires lowercase, but older texts may set it in uppercase.
    5. +
+
+
+
+

Capitalization

+
    +
  1. In general, capitalization follows modern English style. Some very old works frequently capitalize nouns that today are no longer capitalized. These archaic capitalizations are removed, unless doing so would change the meaning of the work.
    2. +
  2. Text in all caps is almost never correct typography. Instead, such text is changed to the correct case and surround with a semantically-meaningful element like <em> (for emphasis), <strong> (for strong emphasis, like shouting) or <b> (for unsemantic formatting required by the text). <strong> and <b> are styled in small-caps by default in SE ebooks. +
    <p>The sign read BOB’S RESTAURANT.</p>
    +
    <p>“CHARGE!” he cried.</p>
    +
    <p>The sign read <b>Bob’s Restaurant</b>.</p>
    +
    <p>“<strong>Charge!</strong>” he cried.</p>
    +
    3. +
  3. When something is addressed as an apostrophe <https://www.merriam-webster.com/dictionary/apostrophe#dictionary-entry-2>.., O is capitalized. +
    <p>I carried the bodies into the sea, O walker in the sea!</p>
    +
    4. +
  4. Titlecasing follows the formula used in the se build-images tool.
    5. +
+
+
+

Indentation

+
    +
  1. Body text in a new paragraph that directly follows earlier body text is indented by 1em.
    2. +
  2. 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. +

    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.

    +
    3. +
+
+
+

Chapter headers

+
    +
  1. Epigraphs in chapter have the quote source set in small caps, without a leading em-dash and without a trailing period. +
    <header> + <h2 epub:type="title z3998:roman">II</h2> + <blockquote epub:type="epigraph"> + <p>“Desire no more than to thy lot may fall. …”</p> + <cite>—Chaucer.</cite> + </blockquote> +</header>
    +
    header [epub|type~="epigraph"] cite{ + font-variant: small-caps; +}
    +
    <header> + <h2 epub:type="title z3998:roman">II</h2> + <blockquote epub:type="epigraph"> + <p>“Desire no more than to thy lot may fall. …”</p> + <cite>Chaucer</cite> + </blockquote> +</header>
    +
    2. +
+
+
+

Ligatures

+

Ligatures are two or more letters that are combined into a single letter, usually for stylistic purposes. In general they are not used, and are replaced with their respective characters.

+
+
<p>Œdipus Rex</p> +<p>Archæology</p>
+
<p>Oedipus Rex</p> +<p>Archaeology</p>
+
+
+
+

Punctuation and spacing

+
    +
  1. Sentences are single-spaced.
    2. +
  2. Ampersands in names of things, like firms, are surrounded by no-break spaces. +
    <p>The firm of Hawkinsnbsp&amp;nbspHarker.</p>
    +
    3. +
  3. Some older works include spaces in common contrations; these spaces are removed. + +
    <p>Would n’t it be nice to go out? It ’s such a nice day.</p>
    +
    <p>Wouldn’t it be nice to go out? It’s such a nice day.</p>
    +
    4. +
+
+

Quotation marks

+
    +
  1. “Curly” or typographer’s quotes, both single and double, are always be used instead of straight quotes. +
    <p>“Don’t do it!” she shouted.</p>
    +
    2. +
  2. Quotation marks that are directly side-by-side are separated by a hair space (u+200A) character. +
    <p>“hairsp‘Green?’ Is that what you said?” asked Dave.</p>
    +
    3. +
  3. Words with missing letters represent the missing letters with a right single quotation mark (’ or u+2019) character to indicate elision. +
    <p>He had pork ’n’ beans for dinner</p>
    +
    4. +
+
+
+

Ellipses

+
    +
  1. The ellipses glyph (… or u+2026) is used for ellipses, instead of consecutive or spaced periods.
    2. +
  2. When ellipses are used as suspension points (for example, to indicate dialog that pauses or trails off), the ellipses is not preceded by a comma. +

    Ellipses used to indicate missing words in a quotation require keeping surrounding punctuation, including commas, as that punctuation is in the original quotation.

    +
    3. +
  3. A hair space (u+200A) glyph is located 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.
    4. +
  4. A regular space is located after all ellipses that are not followed by punctuation.
    5. +
  5. A hair space (u+200A) glyph is located between an ellipses and any punctuation that follows directly after the ellipses, unless that punctuation is a quotation mark, in which case there space at all between the ellipses and the quotation mark. +
    <p>“I’m so hungryhairsp… What were you saying about eatinghairsp…?”
    +
    6. +
+
+
+

Dashes

+

There are many kinds of dashes, and the run-of-the-mill hyphen is often not the correct dash to use. In particular, hyphens are not used for things like date ranges, phone numbers, or negative numbers.

+
    +
  1. Dashes of all types do not have white space around them.
    2. +
  2. Figure dashes (‒ or u+2012) are used to indicate a dash in numbers that aren’t a range, like phone numbers. +
    <p>His number is 555‒1234.</p>
    +
    3. +
  3. Hyphens (- or u+002D) are used to join words, including double-barrel names, or to separate syllables in a word. +
    <p>Pre- and post-natal.</p>
    +
    <p>The Smoot-Hawley act.</p>
    +
    4. +
  4. Minus sign glyphs (− or u+2212) are used to indicate negative numbers, and are used in mathematical equations instead of hyphens to represent the “subtraction” operator. +
    <p>It was −5° out yesterday!</p>
    +
    <p>5 − 2 = 3</p>
    +
    5. +
  5. En-dashes (– or u+2013) are used to indicate a numerical or date range; to indicate a relationships where two concepts are connected by the word “to,” for example a distance between locations or a range between numbers; or to indicate a connection in location between two places. +
    <p>We talked 2–3 days ago.</p>
    +
    <p>We took the Berlin–Munich train yesterday.</p>
    +
    <p>I saw the torpedo-boat in the Ems⁠–⁠Jade Canal.</p>
    +
    6. +
+
+

Em-dashes

+

Em-dashes (— or u+2014) are typically used to offset parenthetical phrases.

+

# Em-dashes are preceded by the invisible word joiner glyph (u+2060).

+
    +
  1. Interruption in dialog is set by a single em-dash, not two em-dashes or a two-em-dash. +
    <p>“I wouldn’t go as far as that, not myself, butwj——”</p>
    +
    <p>“I wouldn’t go as far as that, not myself, butwj—”</p>
    +
    2. +
+
+
+

Partially-obscured words

+
    +
  1. Em-dashes are used for partially-obscured years. +
    <p>It was the year 19wj— in the town of Metropolis.</p>
    +
    2. +
  2. A regular hyphen is used in partially obscured years where only the last number is obscured. +
    <p>It was the year 192- in the town of Metropolis.</p>
    +
    3. +
  3. A two-em-dash (⸺ or u+2E3A) preceded by a word joiner (u+2060) is used in partially obscured word. +
    <p>Sally Jwj⸺ walked through town.</p>
    +
    4. +
  4. A three-em-dash (⸻ or u+2E3B) is used for completely obscured words. +
    <p>It was night in the town of ⸻.</p>
    +
    5. +
+
+
+
+
+

Numbers, measurements, and math

+
    +
  1. Coordinates are set with the prime (′ or u+2032) or double prime (″ or u+2033) glyphs, not single or double quotes. +
    <p><abbr>Lat.</abbr> 27° 0' <abbr class="compass">N.</abbr>, <abbr>long.</abbr> 20° 1' <abbr class="compass eoc">W.</abbr></p> + +<p><abbr>Lat.</abbr> 27° 0’ <abbr class="compass">N.</abbr>, <abbr>long.</abbr> 20° 1’ <abbr class="compass eoc">W.</abbr></p>
    +
    <p><abbr>Lat.</abbr> 27° 0′ <abbr class="compass">N.</abbr>, <abbr>long.</abbr> 20° 1′ <abbr class="compass eoc">W.</abbr></p>
    +
    2. +
  2. Ordinals for Arabic numbers are as follows: st, nd, rd, th. +
    <p>The 1st, 2d, 3d, 4th.</p>
    +
    <p>The 1st, 2nd, 3rd, 4th.</p>
    +
    3. +
+
+

Roman numerals

+
    +
  1. Roman numerals are not followed by trailing periods, unless for grammatical reasons.
    2. +
  2. Roman numerals are set using ASCII, not the Unicode Roman numeral glyphs.
    3. +
  3. Roman numerals are not followed by ordinal indicators. +
    <p>Henry the <span epub:type="z3998:roman">VIII</span>th had six wives.</p>
    +
    <p>Henry the <span epub:type="z3998:roman">VIII</span> had six wives.</p>
    +
    4. +
+
+
+

Fractions

+
    +
  1. Fractions are set in their appropriate Unicode glyph, if a glyph available; for example, ½, ¼, ¾ and u+00BC–u+00BE and u+2150–u+2189.</p> +
    <p>I need 1/4 cup of sugar.</p>
    +
    <p>I need ¼ cup of sugar.</p>
    +
    2. +
  2. If a fraction doesn't have a corresponding Unicode glyph, it is composed using the fraction slash Unicode glyph (⁄ or u+2044) and superscript/subscript Unicode numbers. See this Wikipedia entry for more details. +
    <p>Roughly 6/10 of a mile.</p>
    +
    <p>Roughly ⁶⁄₁₀ of a mile.</p>
    +
    3. +
+
+
+

Measurements

+
    +
  1. Dimension measurements are set using the Unicode multiplication glyph (× or u+00D7), not the ASCII letter x or X. +
    <p>The board was 4 x 3 x 7 feet.</p>
    +
    <p>The board was 4 × 3 × 7 feet.</p>
    +
    2. +
  2. Feet and inches in shorthand are set using the prime (′ or u+2032) or double prime (″ or u+2033) glyphs (not single or double quotes), with a no-break space (u+00A0) separating consecutive feet and inch measurements. +
    <p>He was 6'nbsp1" in height.</p> + +<p>He was 6’nbsp1” in height.</p>
    +
    <p>He was 6′nbsp1″ in height.</p>
    +
    3. +
  3. When forming a compound of a number and unit of measurement in which the measurement is abbreviated, the number and unit of measurement are separated with a no-break space (u+0A00), not a dash. +
    <p>A 12-mm pistol.</p>
    +
    <p>A 12nbspmm pistol.</p>
    +
    4. +
+
+
+

Math

+
    +
  1. In works that are not math-oriented or that dont't have a significant amount of mathematical equations, equations are set using regular HTML and Unicode. +
      +
    1. Operators and operands in mathematical equations are separated by a space. +
      <p>6−2+2=6</p>
      +
      <p>6 − 2 + 2 = 6</p>
      +
      2. +
    2. Operators like subtraction (− or u+2212), multiplication (× or u+00D7), and equivalence (≡ or u+2261) are set using their corresponding Unicode glyphs, not a hyphen or x. Almost all mathematical operators have a corresponding special Unicode glyph. +
      <p>6 - 2 x 2 == 2</p>
      +
      <p>6 − 2 × 2 ≡ 2</p>
      +
      3. +
    +
    2. +
  2. In works that are math-oriented or that have a significant amount of math, all variables, equations, and other mathematical objects are set using MathML. +
      +
    1. When MathML is used in a file, the m namespace is declared at the top of the file and used for all subsequent MathML code, as follows: +
      xmlns:m="http://www.w3.org/1998/Math/MathML"
      +

      This namespace is declared and used even if there is just a single MathML equation in a file.

      +
      <html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" ub:prefix="z3998: http://www.daisy.org/z3998/2012/vocab/structure/, se: https://standardebooks.org/vocab/1.0" xml:lang="en-GB"> +... +<p> + <math xmlns="http://www.w3.org/1998/Math/MathML" alttext="x"> + <ci>x</ci> + </math> +</p>
      +
      <html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" xmlns:m="http://www.w3.org/1998/Math/MathML" epub:prefix="z3998: http://www.daisy.org/z3998/2012/vocab/structure/, se: https://standardebooks.org/vocab/1.0" xml:lang="en-GB"> +... +<p> + <m:math alttext="x"> + <m:ci>x</m:ci> + </m:math> +</p>
      +
      2. +
    2. When possible, Content MathML is used over Presentational MathML. (This may not always be possible depending on the complexity of the work.) +
      <p> + <m:math alttext="x + 1 = y"> + <m:apply> + <m:equals/> + <m:apply> + <m:plus/> + <m:ci>x</m:ci> + <m:cn>1</m:cn> + </m:apply> + <m:ci>y</m:ci> + </m:apply> + </m:math> +</p>
      +
      3. +
    3. Each <m:math> element has an alttext attribute. +
        +
      1. The alttext attribute describes the contents in the element in plain-text Unicode according to the rules in this specification.
        2. +
      2. Operators in the alttext attribute are surrounded by a single space. +
        <p> + <m:math alttext="x+1=y"> + <m:apply> + <m:equals/> + <m:apply> + <m:plus/> + <m:ci>x</m:ci> + <m:cn>1</m:cn> + </m:apply> + <m:ci>y</m:ci> + </m:apply> + </m:math> +</p>
        +
        <p> + <m:math alttext="x + 1 = y"> + <m:apply> + <m:equals/> + <m:apply> + <m:plus/> + <m:ci>x</m:ci> + <m:cn>1</m:cn> + </m:apply> + <m:ci>y</m:ci> + </m:apply> + </m:math> +</p>
        +
        3. +
      +
      4. +
    4. When using Presentational MathML, <m:mrow> is used to group subexpressions, but only when necessary. Many elements in MathML, like <m:math> and <m:mtd>, imply <m:mrow> and redundant elements are not desirable. See this section of the MathML spec for more details. +
      <p> + <m:math alttext="x"> + <m:mrow> + <m:mi>x</m:mi> + </m:mrow> + </m:math> +</p>
      +
      <p> + <m:math alttext="x"> + <m:mi>x</m:mi> + </m:math> +</p>
      +
      5. +
    5. If a Presentational MathML expression contains a function, the invisible Unicode function application glyph (u+2061) is used as an operator between the function name and its operand. This element looks exactly like the following, including the comment for readability: <m:mo>⁡<!--hidden u+2061 function application--></m:mo>. (Note that the preceding element contains an invisible Unicode character! It can be revealed with the se unicode-names tool.) +
      <p> + <m:math alttext="f(x)"> + <m:mi>f</m:mi> + <m:row> + <m:mo fence="true">(</m:mo> + <m:mi>x</m:mi> + <m:mo fence="true">)</m:mo> + </m:row> + </m:math> +</p>
      +
      <p> + <m:math alttext="f(x)"> + <m:mi>f</m:mi> + <m:mo>⁡u+2061</span><!--hidden u+2061 function application--></m:mo> + <m:row> + <m:mo fence="true">(</m:mo> + <m:mi>x</m:mi> + <m:mo fence="true">)</m:mo> + </m:row> + </m:math> +</p>
      +
      6. +
    6. Expressions grouped by parenthesis or brackets are wrapped in an <m:row> element, and fence characters are set using the <m:mo fence="true"> element. Separators are set using the <m:mo separator="true"> element. <m:mfenced>, which used to imply both fences and separators, is deprecated and thus is not used. +
      <p> + <m:math alttext="f(x,y)"> + <m:mi>f</m:mi> + <m:mo>⁡u+2061</span><!--hidden u+2061 function application--></m:mo> + <m:fenced> + <m:mi>x</m:mi> + <m:mi>y</m:mi> + </m:fenced> + </m:math> +</p>
      +
      <p> + <m:math alttext="f(x,y)"> + <m:mi>f</m:mi> + <m:mo>⁡u+2061</span><!--hidden u+2061 function application--></m:mo> + <m:row> + <m:mo fence="true">(</m:mo> + <m:mi>x</m:mi> + <m:mo separator="true">,</m:mo> + <m:mi>x</m:mi> + <m:mo fence="true">)</m:mo> + </m:row> + </m:math> +</p>
      +
      7. +
    7. If a MathML variable includes an overline, it is set by combining the variable's normal Unicode glyph and the Unicode overline glyph (‾ or u+203E) in a <m:mover> element. However in the alttext attribute, the Unicode overline combining mark (u+0305) is used to represent the overline in Unicode. +
      <p> + <m:math alttext="x̅"> + <m:mover> + <m:mi>x</m:mi> + <m:mo>‾</m:mo> + </m:mover> + </m:math> +</p>
      +
      8. +
    +
    3. +
+
+
+
+

Latinisms

+ +
    +
  1. Latinisms (except sic) that can be found in a modern dictionary are not italicized. Examples include e.g., i.e., ad hoc, viz., ibid., etc.. The exception is sic, which is always italicized.
    2. +
  2. Whole passages of Latin language and Latinisms that aren’t found in a modern dictionary are italicized.
    3. +
  3. “&c;” is not used, and is replaced with “etc.”
    4. +
  4. For “Ibid.,” see Endnotes.
    5. +
  5. Latinisms that are abbreviations are set in lowercase with periods between words and no spaces between them, except BC, AD, BCE, and CE, which are set without periods, in small caps, and wrapped with <abbr class="era">: +
    abbr.era{ + font-variant: all-small-caps; +}
    +
    <p>Julius Caesar was born around 100 <abbr class="era">BC</abbr>.</p>
    +
    6. +
+
+
+

Initials and abbreviations

+ +
    +
  1. “OK” is set without periods or spaces. It is not an abbreviation.
    2. +
  2. When an abbreviation contains a terminal period, its <abbr> tag has the additional eoc class (End of Clause) if the terminal period is also the last period in clause. Such sentences do not have two consecutive periods. +
    <p>She loved Italian food like pizza, pasta, <abbr class="eoc">etc.</abbr></p>
    +
    <p>He lists his name alphabetically as Johnson, <abbr class="name eoc">R. A.</abbr></p>
    +
    <p>His favorite hobby was <abbr class="acronym">SCUBA</abbr>.</p>
    +
    3. +
  3. Initialisms, postal codes, and abbreviated US states are set in all caps, without periods or spaces.
    4. +
  4. Acronyms (terms made up of initials and pronounced as one word, like NASA, SCUBA, or NATO) are set in small caps, without periods, and are wrapped in an <abbr class="acronym"> element. +
    abbr.acronym{ + font-variant: all-small-caps; +}
    +
    <p>He was hired by <abbr class="acronym">NASA</abbr> last week.</p>
    +
    5. +
  5. Initialisms (terms made up of initials in which each initial is pronounced separately, like ABC, HTML, or CSS) are set with without periods and are wrapped in an <abbr class="initialism"> element. +
    <p>He was hired by the <abbr class="initialism">FBI</abbr> last week.</p>
    +
    6. +
  6. Initials of people’s names are each separated by periods and spaces. The group of initials is wrapped in an <abbr class="name"> element. +
    <p><abbr class="name">H. P.</abbr> Lovecraft described himself as an aged antiquarian.</p>
    +
    7. +
  7. Academic degrees, except ones that include a lowercase letter (like PhD) are wrapped in an <abbr class="degree"> element. For example: BA, BD, BFA, BM, BS, DB, DD, DDS, DO, DVM, JD, LHD, LLB, LLD, LLM, MA, MBA, MD, MFA, MS, MSN. +
    <p>Judith Douglas, <abbr class="degree">DDS</abbr>.</p>
    +
    8. +
  8. State names and postal codes are wrapped in an <abbr class="postal"> element. +
    <p>Washington <abbr class="postal">DC</abbr>.</p>
    +
    9. +
  9. Abbreviations that are abbreviations of a single word, and that are not acronyms or initialisms (like Mr., Mrs., or lbs.) are set with <abbr>. +
      +
    1. Abbreviations ending in a lowercase letter are set without spaces and followed by a period.
      2. +
    2. Abbreviations without lowercase letters are set without spaces and without a trailing period.
      3. +
    3. Abbreviations that describes the next word, like Mr., Mrs., Mt., and St., are set with a no-break space between the abbreviation and its target. +
      <p>He called on <abbr>Mrs.</abbr>nbspJones yesterday.</p>
      +
      4. +
    +
    10. +
  10. Compass points are separated by periods and spaces. The group of points are wrapped in an <abbr class="compass"> element. +
    <p>He traveled <abbr class="compass">S.</abbr>, <abbr class="compass">N. W.</abbr>, then <abbr class="compass eoc">E. S. E.</abbr></p>
    +
    11. +
+
+
+

Times

+
    +
  1. Times in a.m. and p.m. format are set in lowercase, with periods, and without spaces.
    2. +
  2. “a.m.” and “p.m.” are wrapped in an <abbr class="time"> element.
    3. +
+
+

Times as digits

+
    +
  1. Digits in times are separated by a colon, not a period or comma.
    2. +
  2. Times written in digits followed by “a.m.” or “p.m.” are set with a no-break space between the digit and “a.m.” or “p.m.”. +
    <p>He called at 6:40nbsp<abbr class="time eoc">a.m.</abbr></p>
    +
    3. +
+
+
+

Times as words

+
    +
  1. Words in a spelled-out time are separated by spaces, unless they appear before a noun, where they are separated by a hyphen. +
    <p>He arrived at five thirty.</p>
    +
    <p>They took the twelve-thirty train.</p>
    +
    2. +
  2. Times written in words followed by “a.m.” or “p.m.” are set with a regular space between the time and “a.m.” or “p.m.”. +
    <p>She wasn’t up till seven <abbr class="time eoc">a.m.</abbr></p>
    +
    3. +
  3. Military times that are spelled out (for example, in dialog) are set with dashes. Leading zeros are spelled out as “oh”. +
    <p>He arrived at oh-nine-hundred.</p>
    +
    4. +
+
+
+
+

Chemicals and compounds

+
    +
  1. Molecular compounds are set in Roman, without spaces, and wrapped in an <abbr class="compound"> element. +
    <p>He put extra <abbr class="compound">NaCl</abbr> on his dinner.</p>
    +
    2. +
  2. Elements in a molecular compound are capitalized according to their listing in the periodic table.
    3. +
  3. Amounts of an element in a molecular compound are set in subscript with a <sub> element. +
    <p>She drank eight glasses of <abbr class="compound">H<sub>2</sub>O</abbr> a day.</p>
    +
    4. +
+
+
+

Temperatures

+
    +
  1. The minus sign glyph (− or u+2212), not the hyphen glyph, is used to indicate negative numbers.
    2. +
  2. Either the degree glyph (° or u+00B0) or the word “degrees” is acceptable. Works that use both are normalize to use the dominant method.
    3. +
+
+

Abbreviated units of temperature

+

Units of temperature measurement, like Farenheit or Celcius, may be abbreviated to “F” or “C”.

+
    +
  1. Units of temperature measurement do not have trailing periods.
    2. +
  2. If an abbreviate unit of temperature measurement is preceded by a number, the unit of measurement is first preceded by a hair space (u+200A).
    3. +
  3. Abbreviated units of measurement are set in small caps.
    4. +
  4. Abbreviated units of measurement are wrapped in an <abbr class="temperature"> element. +
    abbr.temperature{ + font-variant: all-small-caps; +}
    +
    <p>It was −23.33° Celsius (or −10°hairsp<abbr class="temperature">F</abbr>) last night.</p>
    +
    5. +
+
+
+
+

Scansion

+

Scansion is the representation of the metrical stresses in lines of verse.

+
    +
  1. × (u+00d7) indicates an unstressed sylllable and / (u+002f) indicates a stressed syllable. They are separated from each other with no-break spaces.
    2. +
+
+ +
+

Morse Code

+

Any Morse code that appears in a book will have to be changed to fit SE's format.

+
+

American Morse Code

+
    +
  1. The middle dot glyph (U+00B7) is used for the short mark or dot.
    2. +
  2. The en dash (U+2013) is used for the longer mark or short dash.
    3. +
  3. The em dash (U+2014) is used for the long dash (the letter L).
    4. +
  4. If two en dashes are placed next to each other, a hair space (U+200A) must be placed in between them to keep the glyphs from merging into a longer dash.
    5. +
  5. Only in American Morse Code, there are internal gaps used between glyphs in the letters C,O,R, or Z. Use a no-break space (U+00A0) for this gap.
    6. +
  6. Use en spaces (U+2002) between letters.
    7. +
  7. Use em spaces (U+2003) between words. +
    <p>-- .. .. __ .. - - __ . . .. __ -.. .. . .- -</p> +<p>My little old cat.</p>
    +
    <p>– – ·· ·· — ·· – – — · · · — –·· ·· · ·– –</p> +<p>My little old cat.</p>
    +
    8. +
+
+
+
+
+
+ diff --git a/www/manual/1.0/uncategorized-art-resources.php b/www/manual/1.0/uncategorized-art-resources.php new file mode 100644 index 00000000..2abc20cf --- /dev/null +++ b/www/manual/1.0/uncategorized-art-resources.php @@ -0,0 +1,121 @@ + + + + + Style Manual | Standard Ebooks + + + + + + + + + + + + + + + + + + + +
+ Standard Ebooks + +
+
+
+ +
+

Uncategorized art books

+

You may find these 1922-and-earlier art books useful as you conduct cover art research.

+ +
+
+
+