From 6783e0e1a913c672357053eefedc64f3728b5dc5 Mon Sep 17 00:00:00 2001 From: Alex Cabal Date: Thu, 26 Mar 2020 18:57:38 -0500 Subject: [PATCH] Update manual to new draft version --- www/css/manual.css | 10 + www/css/monokai.css | 4 + www/manual/1.0.0/1-code-style.php | 6 +- www/manual/1.0.0/10-art-and-images.php | 132 +-- www/manual/1.0.0/2-filesystem.php | 6 +- .../1.0.0/3-the-structure-of-an-ebook.php | 6 +- www/manual/1.0.0/4-semantics.php | 2 +- www/manual/1.0.0/5-general-xhtml-patterns.php | 2 +- .../6-standard-ebooks-section-patterns.php | 403 +++++++ .../7-high-level-structural-patterns.php | 980 ++++++++++++++++++ www/manual/1.0.0/8-typography.php | 14 +- www/manual/1.0.0/9-metadata.php | 16 +- www/manual/1.0.0/index.php | 6 +- 13 files changed, 1496 insertions(+), 91 deletions(-) create mode 100644 www/manual/1.0.0/6-standard-ebooks-section-patterns.php create mode 100644 www/manual/1.0.0/7-high-level-structural-patterns.php diff --git a/www/css/manual.css b/www/css/manual.css index 820c0609..d2e8cee1 100644 --- a/www/css/manual.css +++ b/www/css/manual.css @@ -132,6 +132,10 @@ margin-top: -3px; /* to match poor crimson alignment */ } +code.bash > span{ + color: var(--dark-button-highlight); +} + figure code.html .ws, code.full .ws{ border-color: #fff; @@ -185,6 +189,12 @@ main.manual > nav ol{ list-style: none; } +figure code.html, +figure code.css{ + white-space: pre; + overflow-x: auto; +} + @media(max-width: 1700px){ main.manual > article{ margin-left: 10rem; diff --git a/www/css/monokai.css b/www/css/monokai.css index ff0b5d77..6078a8a0 100644 --- a/www/css/monokai.css +++ b/www/css/monokai.css @@ -47,8 +47,10 @@ .mh { color: #ae81ff } /* Literal.Number.Hex */ .mi { color: #ae81ff } /* Literal.Number.Integer */ .mo { color: #ae81ff } /* Literal.Number.Oct */ +.sa { color: #e6db74 } /* Literal.String.Affix */ .sb { color: #e6db74 } /* Literal.String.Backtick */ .sc { color: #e6db74 } /* Literal.String.Char */ +.dl { color: #e6db74 } /* Literal.String.Delimiter */ .sd { color: #e6db74 } /* Literal.String.Doc */ .s2 { color: #e6db74 } /* Literal.String.Double */ .se { color: #ae81ff } /* Literal.String.Escape */ @@ -59,7 +61,9 @@ .s1 { color: #e6db74 } /* Literal.String.Single */ .ss { color: #e6db74 } /* Literal.String.Symbol */ .bp { color: #f8f8f2 } /* Name.Builtin.Pseudo */ +.fm { color: #a6e22e } /* Name.Function.Magic */ .vc { color: #f8f8f2 } /* Name.Variable.Class */ .vg { color: #f8f8f2 } /* Name.Variable.Global */ .vi { color: #f8f8f2 } /* Name.Variable.Instance */ +.vm { color: #f8f8f2 } /* Name.Variable.Magic */ .il { color: #ae81ff } /* Literal.Number.Integer.Long */ diff --git a/www/manual/1.0.0/1-code-style.php b/www/manual/1.0.0/1-code-style.php index 501159ba..9151e550 100644 --- a/www/manual/1.0.0/1-code-style.php +++ b/www/manual/1.0.0/1-code-style.php @@ -1,12 +1,12 @@ '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, CSS, and SVG 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.

+

The se clean tool in the Standard Ebooks toolset formats XHTML, CSS, and SVG 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

    @@ -181,7 +181,7 @@ Demoiselle Jeanne D’Ys</pCommits and Commit Messages

    1. Commits are broken into single units of work. A single unit of work may be, for example, "fixing typos across 10 files", or "adding cover art", or "working on metadata".

      2. -

    2. Commits that introduce material changes to the ebook text (for example modernizing spelling or fixing a probable printer's typo; but not fixing a transcriber's typo) are prefaced with the string [Editorial], followed by a space, then the commit message. This makes it easy to search the repo history for commits that make editorial changes to the work.

      3. +

    3. Commits that introduce material changes to the ebook text (for example modernizing spelling or fixing a probable printer’s typo; but not fixing a transcriber’s typo) are prefaced with the string [Editorial], followed by a space, then the commit message. This makes it easy to search the repo history for commits that make editorial changes to the work.

diff --git a/www/manual/1.0.0/10-art-and-images.php b/www/manual/1.0.0/10-art-and-images.php index 6c769fc6..65ea6add 100644 --- a/www/manual/1.0.0/10-art-and-images.php +++ b/www/manual/1.0.0/10-art-and-images.php @@ -1,13 +1,13 @@ '10. Art and Images - The Standard Ebooks Manual', 'highlight' => 'contribute', 'manual' => true]) ?> -
+

Art and Images

-

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.

+

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

@@ -17,11 +17,11 @@ require_once('Core.php');

  • ./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.

    +

    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.

    +

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

    • @@ -46,49 +46,52 @@ require_once('Core.php');

    The SE Editor-in-Chief must review and approve of the cover art you select before you can commit it to your repository.

    Do not commit cover art without contacting the mailing list first!

    -

    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.

    +

    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.

      -

    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. +

    5. The <title> element has a value of The cover for the Standard Ebooks edition of followed by the title string.

    -
    +
    +

    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. +

    5. One-line titles: the line is 80px tall. Example: The Prince, by Niccolò Machiavelli.

      6. +

    6. 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.

      7. +

    7. 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.

      8. +

    8. 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.

    -
    +

    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. +

    4. The first author line begins 60px below the last title line.

      5. +

    5. One-line authors: the line is 40px tall.

      6. +

    6. Two-line authors: each line is 40px tall, and the second author line is 20px below the first line.

    -
    +

    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, and in full color. Art not in this style, like modern CG art or black-and-white scans, 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. +

    6. ./images/cover.svg links to ./images/cover.jpg as the canvas background.

      7. +

    7. ./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.

      8. +

    8. 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.

      9. +

    9. Cover art is in the “fine art oil painting” style, and in full color. Art not in this style, like modern CG art or black-and-white scans, is not acceptable.

      10. +

    10. ./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.

    -
    +

    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.

    @@ -105,7 +108,7 @@ require_once('Core.php');

  • 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. @@ -116,7 +119,7 @@ require_once('Core.php');

    -
    +
    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.

      @@ -157,7 +160,7 @@ require_once('Core.php');

    • Birmingham Museums (CC0 items say CC0 under the Usage Rights section in the item details.)

    -
    +
    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? @@ -182,48 +185,51 @@ require_once('Core.php');

    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.

    -
    +

    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.

    +
      +

    1. The <title> element has a value of The titlepage for the Standard Ebooks edition of followed by the title string.

      2. +
    +

    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. +

    3. The title, author, other contributors are in League Spartan font with 5px letter spacing in ALL CAPS.

      4. +

    4. 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.

      5. -

    5. 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.

      6. -

    6. Only the author, translator, and illustrator are on the titlepage. Other contributors like writers of introductions or annotators are not included.

      7. -

    7. The canvas has a padding area of 50px vertically and 100px horizontally in which text must not enter.

      8. -

    8. The viewbox width is exactly 1400px wide.

      9. -

    9. The viewbox height must precisely fit the titlepage contents, plus 50px padding.

      10. +

    10. 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.

      11. +

    11. Only the author, translator, and illustrator are on the titlepage. Other contributors like writers of introductions or annotators are not included.

      12. +

    12. The canvas has a padding area of 50px vertically and 100px horizontally in which text must not enter.

      13. +

    13. The viewbox width is exactly 1400px wide.

      14. +

    14. The viewbox height must precisely fit the titlepage contents, plus 50px padding.

    -
    +

    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. +

    4. Each title line is 80px tall.

      5. +

    5. The title is split into as many lines as necessary to fit.

      6. +

    6. Title lines are separated by a 20px margin between each line.

    -
    +

    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. +

    5. The first author line begins 100px below the last title line.

      6. +

    6. Each author line is 60px tall.

      7. +

    7. If an author line must be split, the next line begins 20px below the previous one.

      8. +

    8. For works with multiple authors, subsequent author lines begin 20px below the last author line.

    -
    +

    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. +

    8. “Contributors” are a “contributor descriptor,” like translated by, followed by the contributor name on a new line.

      9. +

    9. The first contributor descriptor line begins 150px below the last author line.

      10. +

    10. Contributor descriptor lines are 40px tall, all lowercase, in the Sorts Mill Goudy Italic font.

      11. +

    11. The contributor name begins 20px below the contributor descriptor line.

      12. +

    12. The contributor name is 40px tall, ALL CAPS, in the League Spartan font.

      13. +

    13. 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.

      14. +

    14. 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.

    diff --git a/www/manual/1.0.0/2-filesystem.php b/www/manual/1.0.0/2-filesystem.php index c03553a0..db151a48 100644 --- a/www/manual/1.0.0/2-filesystem.php +++ b/www/manual/1.0.0/2-filesystem.php @@ -1,7 +1,7 @@ '2. Filesystem Layout and File Naming Conventions - The Standard Ebooks Manual', 'highlight' => 'contribute', 'manual' => true]) ?> -
    +
    @@ -229,7 +229,7 @@ require_once('Core.php');

    The se-lint-ignore.xml file

    -

    The se lint tool makes best guesses to alert the user to potential issues in an ebook production, and it may sometimes guess wrong. An se-lint-ignore.xml file can be placed in the ebook root to make se lint ignore specific error numbers in an ebook.

    +

    The se lint tool makes best guesses to alert the user to potential issues in an ebook production, and it may sometimes guess wrong. An se-lint-ignore.xml file can be placed in the ebook root to make se lint ignore specific error numbers in an ebook.

    1. se-lint-ignore.xml is optional. If it exists, it is in the ebook root.

    2. An empty se-lint-ignore.xml file looks like this: @@ -249,7 +249,7 @@ require_once('Core.php');

    3. Each <file> element contains one or more <ignore> elements. Each <ignore> element contains one <code> element and one <reason> element.

        -

      1. The value of <code> is the error/warning code provided by se lint. This code will be ignored for its parent file(s) when se lint is next run.

        2. +

      2. The value of <code> is the error/warning code provided by se lint. This code will be ignored for its parent file(s) when se lint is next run.

      3. The value of <reason> is a prose explanation about why the code was ignored. This is to aid future producers or reviewers in understanding the reasoning behind why a code was ignored.

        1. <reason> is required to have a non-whitespace value.

          2. diff --git a/www/manual/1.0.0/3-the-structure-of-an-ebook.php b/www/manual/1.0.0/3-the-structure-of-an-ebook.php index 2611786f..b9d39022 100644 --- a/www/manual/1.0.0/3-the-structure-of-an-ebook.php +++ b/www/manual/1.0.0/3-the-structure-of-an-ebook.php @@ -1,7 +1,7 @@ '3. The Structure of an Ebook - The Standard Ebooks Manual', 'highlight' => 'contribute', 'manual' => true]) ?> -
          +
          @@ -14,11 +14,11 @@ require_once('Core.php');

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

          Cover

          -

          An image presenting 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.

          +

          An image presenting 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

          -

          A page listing 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.

          +

          A page listing 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

          diff --git a/www/manual/1.0.0/4-semantics.php b/www/manual/1.0.0/4-semantics.php index 96252678..f9a6261d 100644 --- a/www/manual/1.0.0/4-semantics.php +++ b/www/manual/1.0.0/4-semantics.php @@ -1,7 +1,7 @@ '4. Semantics - The Standard Ebooks Manual', 'highlight' => 'contribute', 'manual' => true]) ?> -
          +
          diff --git a/www/manual/1.0.0/5-general-xhtml-patterns.php b/www/manual/1.0.0/5-general-xhtml-patterns.php index d5f68117..6ed46267 100644 --- a/www/manual/1.0.0/5-general-xhtml-patterns.php +++ b/www/manual/1.0.0/5-general-xhtml-patterns.php @@ -1,7 +1,7 @@ '5. General XHTML Patterns - The Standard Ebooks Manual', 'highlight' => 'contribute', 'manual' => true]) ?> -
          +
          diff --git a/www/manual/1.0.0/6-standard-ebooks-section-patterns.php b/www/manual/1.0.0/6-standard-ebooks-section-patterns.php new file mode 100644 index 00000000..300b0663 --- /dev/null +++ b/www/manual/1.0.0/6-standard-ebooks-section-patterns.php @@ -0,0 +1,403 @@ + '6. Standard Ebooks Section Patterns - The Standard Ebooks Manual', 'highlight' => 'contribute', 'manual' => true]) ?> +
          +
          + +
          +

          Standard Ebooks Section Patterns

          +

          All Standard Ebooks set of sections that are included in each ebook, and which are usually generated from template files. These sections include sections like the titlepage, imprint, and Uncopyright.

          +
          +

          The title string

          +

          The title string is a sentence listing the title of the ebook, its author, and any other contributors. It is used in various Standard Ebooks template files.

          +
            +

          1. The title string is formed with the following algorithm. +

              +

            • Start with an empty string.

              • +

            • Append the title of the work, without any subtitles.

              • +

            • Append , by, then the author. If there are two authors, separate them with :html:` and`. If there are three or more authors, each one is separated by ,, and the final one is preceded by , and.

              • +

            • If there is a translator, append . Translated by, then the translator name. Multiple translators are handled in the same manner as multiple authors.

              • +

            • If there is an illustrator, append . Illustrated by, then the illustrator name. Multiple illustrators are handled in the same manner as mutliple authors.

              • +
            +
            2. +

          2. While the title string may contain periods, it never ends in a period.

            3. +
          +
          +
          +

          The table of contents

          +

          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 se print-toc tool constructs the ToC according to these rules, without further changes being necessary.

          +
          +

          The <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, plus one element representing the beginning 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, as a single unit regardless of internal divisions, 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. +
          +
          +
          +
          +
          +

          The titlepage

          +
            +

          1. The Standard Ebooks titlepage is the first item in the ebook’s content flow. Standard Ebooks do not have a separate cover page file within the content flow.

            2. +

          2. The title page has a <title> element with the value Titlepage.

            3. +

          3. The titlepage contains one <section id="titlepage" epub:type="titlepage"> element which in turn contains one <img src="../images/titlepage.svg"> element.

            4. +

          4. The <img> element has its alt attribute set to The titlepage for the Standard Ebooks edition of 6. Standard Ebooks Section Patterns - The Standard Ebooks Manual_STRING, where 6. Standard Ebooks Section Patterns - The Standard Ebooks Manual_STRING is the Standard Ebooks title string for the ebook.

            5. +

          5. A complete titlepage looks like the following template: +

            <?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: https://standardebooks.org/vocab/1.0" xml:lang="en-US"> + <head> + <title>Titlepage</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="frontmatter"> + <section id="titlepage" epub:type="titlepage"> + <img alt="The titlepage for the Standard Ebooks edition of 6. Standard Ebooks Section Patterns - The Standard Ebooks Manual_STRING" src="../images/titlepage.svg"/> + </section> + </body> +</html>
            +
            6. +
          +
          +
          +

          The imprint

          +
            +

          1. The Standard Ebooks imprint is the second item in the ebook’s content flow.

            2. +

          2. The imprint has a <title> element with the value Imprint.

            3. +

          3. The imprint contains one <section id="imprint" epub:type="imprint"> element, which in turn contains one <header> element with the Standard Ebooks logo, followed by a series of <p> elements containing the imprint’s content.

            4. +

          4. The second <p> element contains links to the online transcription that the ebook is based off of, followed by a link to the online page scans used to proof against. +

              +

            1. While the template lists Project Gutenberg and the Internet Archive as the default sources for transcriptions and scans, these may be adjusted to the specific sources used for a particular ebook.

              2. +

            2. When a source is preceded by “the”, “the” is outside of the link to the source. +

              <p>This particular ebook is based on digital scans available at <a href="IA_URL">the Internet Archive</a>.</p>
              +
              <p>This particular ebook is based on digital scans available at the <a href="IA_URL">Internet Archive</a>.</p>
              +
              3. +
            +
            5. +

          5. A complete imprint looks like the following template: +

            <?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: https://standardebooks.org/vocab/1.0" xml:lang="en-US"> + <head> + <title>Imprint</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="frontmatter"> + <section id="imprint" epub:type="imprint"> + <header> + <h2 epub:type="title">Imprint</h2> + <img alt="The Standard Ebooks logo" src="../images/logo.svg" epub:type="z3998:publisher-logo"/> + </header> + <p>This ebook is the product of many hours of hard work by volunteers for <a href="https://standardebooks.org">Standard Ebooks</a>, and builds on the hard work of other literature lovers made possible by the public domain.</p> + <p>This particular ebook is based on a transcription produced for <a href="PG_URL">Project Gutenberg</a> and on digital scans available at the <a href="IA_URL">Internet Archive</a>.</p> + <p>The writing and artwork within are believed to be in the <abbr>U.S.</abbr> public domain, and Standard Ebooks releases this ebook edition under the terms in the <a href="https://creativecommons.org/publicdomain/zero/1.0/">CC0 1.0 Universal Public Domain Dedication</a>. For full license information, see the <a href="uncopyright.xhtml">Uncopyright</a> at the end of this ebook.</p> + <p>Standard Ebooks is a volunteer-driven project that produces ebook editions of public domain literature using modern typography, technology, and editorial standards, and distributes them free of cost. You can download this and other ebooks carefully produced for true book lovers at <a href="https://standardebooks.org">standardebooks.org</a>.</p> + </section> + </body> +</html>
            +
            6. +
          +
          +
          +

          The half title page

          +
            +

          1. A half title page is included when there is front matter of any type in an ebook besides the titlepage and imprint.

            2. +

          2. The half title page located after the last item of front matter, before the body matter.

            3. +

          3. The half title page has a <title> element with the value Half Title.

            4. +

          4. The half title page contains one <section id="halftitlepage" epub:type="halftitlepage"> element, which in turn contains one <h1 epub:type="fulltitle"> element containing the full title of the ebook, including subtitles. The half title page is the only place where an <h1> element may appear in a Standard Ebook.

            5. +

          5. Formatting for the <h1> element follows patterns in 7.2.6.6 and 7.2.6.7.

            6. +

          6. A complete half title page looks like the following template: +

            <?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: https://standardebooks.org/vocab/1.0" xml:lang="en-GB"> + <head> + <title>Half Title</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="frontmatter"> + <section id="halftitlepage" epub:type="halftitlepage"> + <h1 epub:type="fulltitle"> + <span epub:type="title">His Last Bow</span> + <span epub:type="subtitle">Some Reminiscences of Sherlock Holmes</span> + </h1> + </section> + </body> +</html>
            +
            7. +
          +
          +
          +

          The colophon

          +
            +

          1. The colophon is the second-to-last item in the ebook’s content flow.

            2. +

          2. The colophon has a <title> element with the value Colophon.

            3. +

          3. The half title page contains one <section id="colophon" epub:type="colophon"> element, which in turn contains one <header> element with the Standard Ebooks logo, followed by a series of <p> elements containing the colophon’s content.

            4. +
          +
          +

          Names

          +
            +

          1. Within <p> elements, proper names except for the book title and cover art title are wrapped in an <a> element pointing to the name’s Wikipedia page, or to a link representing the name, like a personal homepage.

            2. +

          2. If a name does not have a Wikipedia entry, the name is wrapped in <b class="name">.

            3. +

          3. Two names are separated by and. Three or more names are separated by commas, with the final name separated by , and. (I.e., with an Oxford comma.) +

            <b class="name">Fritz Ohrenschall</b>, <b class="name">Sania Ali Mirza</b> and <a href="https://www.pgdp.net">The Online Distributed Proofreading Team</a>
            +
            <b class="name">Fritz Ohrenschall</b>, <b class="name">Sania Ali Mirza</b>, and <a href="https://www.pgdp.net">The Online Distributed Proofreading Team</a>
            +
            4. +

          4. Any anonymous contributor is listed as An Anonymous Volunteer.

            5. +
          +
          +
          +

          Subsections

          +
            +

          1. Subsections are represented by a <p> element. +

              +

            1. Within each <p> element, a <br/> element is placed before and after any proper name block. A proper name block may contain more than one name in a direct series (like a list of transcribers). +

              <p><i epub:type="se:name.publication.book">The Moon Pool</i><br/> +was published in 1919 by<br/> +<a href="https://en.wikipedia.org/wiki/Abraham_Merritt">Abraham Merritt</a>.</p>
              +
              2. +

            2. The first <p> block names the book, its publication year, and its author. +

              <p><i epub:type="se:name.publication.book">The Moon Pool</i><br/> +was published in 1919 by<br/> +<a href="https://en.wikipedia.org/wiki/Abraham_Merritt">Abraham Merritt</a>.</p>
              +
                +

              1. If the book has a translator, a translator block follows the author name in the same <p> tag. The translator block follows this formula: It was translated from LANGUAGE in YEAR by <a href="TRANSLATOR_WIKI_URL">TRANSLATOR</a>.. +

                <p><i epub:type="se:name.publication.book">Eugene Onegin</i><br/> +was published in 1837 by<br/> +<a href="https://en.wikipedia.org/wiki/Alexander_Pushkin">Alexander Pushkin</a>.<br/> +It was translated from Russian in 1881 by<br/> +<b class="name">Henry Spalding</b>.</p>
                +
                2. +
              +
              3. +

            3. The second <p> block names the Standard Ebooks producer, the original transcribers, and the page scan sources. +

              <p>This ebook was produced for the<br/> +<a href="https://standardebooks.org">Standard Ebooks project</a><br/> +by<br/> +<a href="https://www.robinwhittleton.com/">Robin Whittleton</a>,<br/> +and is based on a transcription produced in 1997 by<br/> +<b class="name">An Anonymous Volunteer</b> and <b class="name">David Widger</b><br/> +for<br/> +<a href="https://www.gutenberg.org/ebooks/965">Project Gutenberg</a><br/> +and on digital scans available at the<br/> +<a href="https://archive.org/details/worksofdumas24dumaiala">Internet Archive</a>.</p>
              +
              4. +

            4. The third <p> block names the cover art, cover artist, and the typefaces used on the cover and title pages. +

              <p>The cover page is adapted from<br/> +<i epub:type="se:name.visual-art.painting">Floral Still Life</i>,<br/> +a painting completed in 1639 by<br/> +<a href="https://en.wikipedia.org/wiki/Hans_Gillisz._Bollongier">Hans Bollongier</a>.<br/> +The cover and title pages feature the<br/> +<b epub:type="se:name.visual-art.typeface">League Spartan</b> and <b epub:type="se:name.visual-art.typeface">Sorts Mill Goudy</b><br/> +typefaces created in 2014 and 2009 by<br/> +<a href="https://www.theleagueofmoveabletype.com">The League of Moveable Type</a>.</p>
              +
              5. +

            5. The fourth <p> block lists the original release date of the ebook and its Standard Ebooks page URL. +

              <p>The first edition of this ebook was released on<br/> +<b>May 11, 2018, 2:13 <abbr class="time eoc">a.m.</abbr></b><br/> +You can check for updates to this ebook, view its revision history, or download it for different ereading systems at<br/> +<a href="https://standardebooks.org/ebooks/alexandre-dumas/the-black-tulip/p-f-collier-and-son">standardebooks.org/ebooks/alexandre-dumas/the-black-tulip/p-f-collier-and-son</a>.</p>
              +
              6. +

            6. The fifth <p> block is a short formula inviting volunteers. +

              <p>The volunteer-driven Standard Ebooks project relies on readers like you to submit typos, corrections, and other improvements. Anyone can contribute at <a href="https://standardebooks.org">standardebooks.org</a>.</p>
              +
              7. +
            +
            2. +
          +
          +
          +

          An example of a complete colophon

          +
          <?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: https://standardebooks.org/vocab/1.0" xml:lang="en-US"> + <head> + <title>Colophon</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="colophon" epub:type="colophon"> + <header> + <h2 epub:type="title">Colophon</h2> + <img alt="The Standard Ebooks logo" src="../images/logo.svg" epub:type="z3998:publisher-logo"/> + </header> + <p><i epub:type="se:name.publication.book">The Black Tulip</i><br/> + was published in 1850 by<br/> + <a href="https://en.wikipedia.org/wiki/Alexandre_Dumas">Alexandre Dumas</a>.<br/> + It was translated from French in 1902 by<br/> + <a href="https://en.wikipedia.org/wiki/Peter_F._Collier"><abbr class="name">P. F.</abbr> Collier and Son</a>.</p> + <p>This ebook was produced for the<br/> + <a href="https://standardebooks.org">Standard Ebooks project</a><br/> + by<br/> + <a href="https://www.robinwhittleton.com/">Robin Whittleton</a>,<br/> + and is based on a transcription produced in 1997 by<br/> + <b class="name">An Anonymous Volunteer</b> and <b class="name">David Widger</b><br/> + for<br/> + <a href="https://www.gutenberg.org/ebooks/965">Project Gutenberg</a><br/> + and on digital scans available at the<br/> + <a href="https://archive.org/details/worksofdumas24dumaiala">Internet Archive</a>.</p> + <p>The cover page is adapted from<br/> + <i epub:type="se:name.visual-art.painting">Floral Still Life</i>,<br/> + a painting completed in 1639 by<br/> + <a href="https://en.wikipedia.org/wiki/Hans_Gillisz._Bollongier">Hans Bollongier</a>.<br/> + The cover and title pages feature the<br/> + <b epub:type="se:name.visual-art.typeface">League Spartan</b> and <b epub:type="se:name.visual-art.typeface">Sorts Mill Goudy</b><br/> + typefaces created in 2014 and 2009 by<br/> + <a href="https://www.theleagueofmoveabletype.com">The League of Moveable Type</a>.</p> + <p>The first edition of this ebook was released on<br/> + <b>May 11, 2018, 2:13 <abbr class="time eoc">a.m.</abbr></b><br/> + You can check for updates to this ebook, view its revision history, or download it for different ereading systems at<br/> + <a href="https://standardebooks.org/ebooks/alexandre-dumas/the-black-tulip/p-f-collier-and-son">standardebooks.org/ebooks/alexandre-dumas/the-black-tulip/p-f-collier-and-son</a>.</p> + <p>The volunteer-driven Standard Ebooks project relies on readers like you to submit typos, corrections, and other improvements. Anyone can contribute at <a href="https://standardebooks.org">standardebooks.org</a>.</p> + </section> + </body> +</html>
          +
          +
          +
          +

          The Uncopyright

          +

          Where traditionally published ebooks may contain a copyright page at the front of the ebook, Standard Ebooks contain an Uncopyright page at the end of the ebook.

          +
            +

          1. The Uncopyright page is the last item in the ebook’s content flow.

            2. +

          2. The Uncopyright page follows the template created by se create-draft exactly.

            3. +
          +
          +
          +
          +
          + diff --git a/www/manual/1.0.0/7-high-level-structural-patterns.php b/www/manual/1.0.0/7-high-level-structural-patterns.php new file mode 100644 index 00000000..9c7d1d3e --- /dev/null +++ b/www/manual/1.0.0/7-high-level-structural-patterns.php @@ -0,0 +1,980 @@ + '7. 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 Standard 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 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. An <h1> element is only present if the ebook contains a half title page. 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 have a non-unique title, but that are required to be identifed in the ToC with a unique title (e.g., multiple poems identified as “Sonnet” in the body matter, which require their ToC entry to contain the poem’s first line to differentiate them): +

            span[epub|type~="subtitle"]{ + display: block; + font-weight: normal; +}
            +
            <h2 epub:type="title"> + <span>Sonnet</span> + <span hidden="hidden" epub:type="subtitle">Happy Is England!</span> +</h2>
            +
            6. +

          6. 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>
            +
            7. +

          7. Half title pages without subtitles: +

            <h1 epub:type="fulltitle">Eugene Onegin</h1>
            +
            8. +

          8. Half title pages with subtitles: +

            <h1 epub:type="fulltitle"> + <span epub:type="title">His Last Bow</span> + <span epub:type="subtitle">Some Reminiscences of Sherlock Holmes</span> +</h1>
            +
            9. +
          +
          +
          +

          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⁠wj—Under canvas⁠wj—An appeal for help⁠wj—Contrariness of teakettles, how to overcome⁠wj—Supper⁠wj—How to feel virtuous⁠wj—Wanted! a comfortably-appointed, well-drained desert island, neighbourhood of South Pacific Ocean preferred⁠wj—Funny thing that happened to George’s father⁠wj—A restless night.</p> +</header>
            +
            3. +
          +
          +
          +
          +

          Dedications

          +
            +

          1. Dedications are typically full-page, centered on the page for ereaders that support advanced CSS. For all other ereaders, the dedication is horizontally centered with a small margin above it.

            2. +

          2. All dedications include this base CSS: +

            /* All dedications */ +section[epub|type~="dedication"] > *{ + display: inline-block; + margin: auto; + margin-top: 3em; + max-width: 80%; +} + +@supports(display: flex){ + section[epub|type~="dedication"]{ + 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~="dedication"] > *{ + margin: 0; + } +} +/* End all dedications */
            +
            3. +

          3. Dedications are frequently styled uniquely by the authors. Therefore Standard Ebooks producers have freedom to style dedications to match page scans, for example by including small caps, different font sizes, alignments, etc.

            4. +
          +
          +
          +

          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 styled with this CSS: +

            [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, styled with this CSS: +

            [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, styled with this CSS: +

            [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 styled with this CSS: +

            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 and 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 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 omitted.

            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"><abbr>P.S.</abbr>wj—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⁠wj—</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.

          +
            +

          1. The LoI is an XHTML file located in ./src/epub/text/loi.xhtml.

            2. +

          2. The LoI file has the backmatter semantic inflection.

            3. +

          3. 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. +
            +
            4. +

          4. 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.

            5. +

          5. 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.

            6. +

          6. Links to the images go directly to the image’s corresponding id hashes, not just the top of the containing file.

            7. +
          +
          +

          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.0/8-typography.php b/www/manual/1.0.0/8-typography.php index f14d6540..bfdc6390 100644 --- a/www/manual/1.0.0/8-typography.php +++ b/www/manual/1.0.0/8-typography.php @@ -1,7 +1,7 @@ '8. Typography - The Standard Ebooks Manual', 'highlight' => 'contribute', 'manual' => true]) ?> -
          +
          @@ -14,7 +14,7 @@ require_once('Core.php');

          <title>Chapter VII</title>
          <title>Chapter 7</title>
          -

        2. Section titles are titlecased according to the output of se titlecase. Section titles are not all-caps or small-caps.

          3. +

        3. Section titles are titlecased according to the output of se titlecase. Section titles are not all-caps or small-caps.

        4. Section titles do not have trailing periods.

        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>
          @@ -161,7 +161,7 @@ require_once('Core.php');

          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. Titlecasing, or the capitalization of titles, follows the formula used in the se titlecase tool.

            3. +

          3. Titlecasing, or the capitalization of titles, follows the formula used in the se titlecase tool.

          4. 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 Standard Ebooks.

            <p>The sign read BOB’S RESTAURANT.</p>
            <p>“CHARGE!” he cried.</p>
            @@ -467,7 +467,7 @@ require_once('Core.php'); </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.) +

          6. 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> @@ -536,10 +536,10 @@ require_once('Core.php');

          7. See here for times.

              8. -

            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. 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.

            3. Whole passages of Latin language and Latinisms that aren’t found in a modern dictionary are italicized.

            4. “&c;” is not used, and is replaced with “etc.”

              5. -

            5. For “Ibid.,” see Endnotes.

              6. +

            6. For “Ibid.,” see Endnotes.

            7. 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; @@ -682,7 +682,7 @@ require_once('Core.php');
          6. -

          Morse Code

          +

          Morse code

          Any Morse code that appears in a book is changed to fit Standard Ebooks’ format.

          American Morse Code

          diff --git a/www/manual/1.0.0/9-metadata.php b/www/manual/1.0.0/9-metadata.php index f7c42ed8..6bb17497 100644 --- a/www/manual/1.0.0/9-metadata.php +++ b/www/manual/1.0.0/9-metadata.php @@ -1,13 +1,13 @@ '9. Metadata - The Standard Ebooks Manual', 'highlight' => 'contribute', 'manual' => true]) ?> -
          +

          Metadata

          Metadata in a Standard Ebook 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 generated by se create-draft. Don’t rearrange the order of anything in there.

          +

          Follow the general structure of the content.opf file generated by se create-draft. Don’t rearrange the order of anything in there.

          General URL rules

            @@ -29,7 +29,7 @@ require_once('Core.php');

            Forming the SE URL

            The SE URL is formed by the following algorithm.

            -

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

            +

            (Note: Strings 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.

              • @@ -41,7 +41,7 @@ require_once('Core.php');

            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.

            +

            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. <meta property="dcterms:modified"> is a timestamp representing the last time this ebook file was modified. This changes often.

              3. @@ -199,7 +199,7 @@ require_once('Core.php');

            3. 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! (Wikipedia licenses articles under a CC license which is incompatible with Standard Ebooks’ CC0 public domain dedication.)

            4. The long descriptions is typogrified, i.e. it contains Unicode curly quotes, em-dashes, and the like.

            5. The long description is in escaped HTML, with the HTML beginning on its own line after the <meta property="se:long-description"> element. -

              +

            6. Long description HTML follows the general code style conventions.

            7. The long description element is directly followed by: <meta property="meta-auth" refines="#long-description">https://standardebooks.org</meta>

              8. @@ -235,7 +235,7 @@ require_once('Core.php');

            Readability metadata

            -

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

            +

            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. The <meta property="se:reading-ease.flesch"> element contains a decimal representing the computed Flesch reading ease for the book.

              3. @@ -350,7 +350,7 @@ require_once('Core.php');

              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. The id attribute is the basename of the href attribute.

                3. @@ -362,7 +362,7 @@ require_once('Core.php');

                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.0/index.php b/www/manual/1.0.0/index.php index e7433a90..5c655f70 100644 --- a/www/manual/1.0.0/index.php +++ b/www/manual/1.0.0/index.php @@ -10,6 +10,8 @@ require_once('Core.php');

          If a rule is not covered in this manual, the directive is to follow the rules in the Chicago Manual of Style, 16th edition.

          These rules align closely with the style rules used in modern publishing. However, books from the turn of the 20th century and older may appear to follow a different set of rules. Producers are expected to adjust those older conventions to match this manual.

          Having said that, literature is a complex and multifaceted art, and in the process of converting older books some may call for a bending of a rule, or for an outright exception. Producers should not feel bound to slavishly follow these directives if a book seems to cry out for an exception. As Ralph Waldo Emerson once wrote, “a foolish consistency is the hobgoblin of little minds.” If unsure, producers are urged and welcomed to contact the Standard Ebooks Editor in Chief for final-word guidance.

          +

          Editor-in-chief: Alex Cabal

          +

          Contributors (in alpha order): David Grigg, B. Timothy Keith, Vince Rice, Emma Sweeney, Robin Whittleton, Kenny Williams.

          Table of Contents

            @@ -18,8 +20,8 @@ require_once('Core.php');

          1. The Structure of an Ebook

          2. Semantics

          3. General XHTML Patterns

            4. -

          4. High-Level Structural Patterns

            5. -

          5. Table of Contents Patterns

            6. +

          6. Standard Ebooks Section Patterns

            7. +

          7. High-Level Structural Patterns

          8. Typography

          9. Metadata

          10. Art and Images