Standard Ebooks

The Standard Ebooks Manual of Style

The Standard Ebooks Manual of Style describes a complete approach to editing and producing ebooks, from internal code style to semantic enhancement and typography rules.

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 different 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 welcomed to contact the Standard Ebooks Editor in Chief for final-word guidance.

To contribute to this manual, including reporting issues or suggestions, please visit the GitHub repository or contact the mailing list.

Versioning

The manual follows a variant of semantic versioning. The latest version of the manual can always be accessed at https://standardebooks.org/manual/latest.

Typo fixes and minor corrections that do not make material changes to the manual do not increment a version number.

An update that contains more than just corrections, but does not change the numbering of existing sections (but may add new sections in a non-breaking manner), increments the patch number.

An update that changes the numbering of existing sections increments the minor number.

An update that changes top-level sections increments the major number.

License

The authors and contributors to this manual release it to the worldwide public domain via the CC0 1.0 Universal Public Domain Dedication.

Contributors

Editor-in-chief: Alex Cabal

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

XHTML, CSS, and SVG Code Style

The se clean tool in the Standard Ebooks toolset formats XML, 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

  1. The first line of all XHTML files is:

    <?xml version="1.0" encoding="utf-8"?>

  2. The second line of all XHTML files is (replace xml:lang="en-US" with the appropriate language tag for the file):

    <html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" epub:prefix="z3998: http://www.daisy.org/z3998/2012/vocab/structure/, se: https://standardebooks.org/vocab/1.0" xml:lang="en-US">

  3. Tabs are used for indentation.

  4. Tag names are lowercase.

  5. Elements whose content is phrasing content are on a single line, with no whitespace between the opening and closing tags and the content.

    <p> It was a dark and stormy night... </p>
    <p>It was a dark and stormy night...</p>

<br/> elements

  1. <br/> elements within phrasing content are on the same line as the preceding phrasing content, and are followed by a newline.

    <p>“Pray for the soul of the <br/> Demoiselle Jeanne D’Ys.</p>
    <p>“Pray for the soul of the <br/>Demoiselle Jeanne D’Ys.</p>
    <p>“Pray for the soul of the<br/> Demoiselle Jeanne D’Ys.</p>

  2. The next indentation level after a <br/> element is the same as the previous indentation level.

    <p>“Pray for the soul of the<br/> Demoiselle Jeanne D’Ys,<br/> who died<br/> in her youth for love of<br/> Philip, a Stranger.</p>
    <p>“Pray for the soul of the<br/> Demoiselle Jeanne D’Ys,<br/> who died<br/> in her youth for love of<br/> Philip, a Stranger.</p>

  3. The closing tag of the phrasing content broken by a <br/> element is on the same line as the last line of the phrasing content.

    <p>“Pray for the soul of the<br/> Demoiselle Jeanne D’Ys. </p>
    <p>“Pray for the soul of the<br/> Demoiselle Jeanne D’Ys.</p>

  4. <br/> elements have phrasing content both before and after; they don’t appear with phrasing content only before, or only after.

    <p>“Pray for the soul of the<br/> Demoiselle Jeanne D’Ys<br/></p>
    <p>“Pray for the soul of the<br/> Demoiselle Jeanne D’Ys</p>

Attributes

  1. Attributes are in alphabetical order.

  2. Attributes, their namespaces, and their values are lowercase, except for values which are IETF language tags. In IETF language tags, the country subtag is capitalized.

    <section EPUB:TYPE="CHAPTER" XML:LANG="EN-US">...</section>
    <section epub:type="chapter" xml:lang="en-US">...</section>

  3. The string utf-8 is lowercase.

Classes

  1. Classes are not used as one-time style hooks. There is almost always a clever selector that can be constructed instead of taking the shortcut of adding a class to an element.

  2. Classes are named semantically, describing what they are styling instead of the resulting visual style.

    <p>There was one great tomb more lordly than all the rest; huge it was, and nobly proportioned. On it was but one word</p> <blockquote class="small-caps"> <p>Dracula.</p> </blockquote>
    <p>There was one great tomb more lordly than all the rest; huge it was, and nobly proportioned. On it was but one word</p> <blockquote class="tomb"> <p>Dracula.</p> </blockquote>

CSS formatting

  1. The first two lines of all CSS files are:

    @charset "utf-8"; @namespace epub "http://www.idpf.org/2007/ops";

  2. Tabs are used for indentation.

  3. Selectors, properties, and values are lowercase.

Selectors

  1. Selectors are each on their own line, directly followed by a comma or a brace with no whitespace in between.

    abbr[epub|type~="se:era"], abbr[epub|type~="se:temperature"]{ font-variant: all-small-caps; }
    abbr[epub|type~="se:era"], abbr[epub|type~="se:temperature"]{ font-variant: all-small-caps; }

  2. Complete selectors are separated by exactly one blank line.

    abbr[epub|type~="se:era"]{ font-variant: all-small-caps; } strong{ font-weight: normal; font-variant: small-caps; }
    abbr[epub|type~="se:era"]{ font-variant: all-small-caps; } strong{ font-weight: normal; font-variant: small-caps; }

  3. Closing braces are on their own line.

Properties

  1. Properties are each on their own line (even if the selector only has one property) and indented with a single tab.

    abbr[epub|type~="se:era"]{ font-variant: all-small-caps; }
    abbr[epub|type~="se:era"]{ font-variant: all-small-caps; }

  2. Where possible, properties are in alphabetical order.

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

  3. Properties are directly followed by a colon, then a single space, then the property value.

    blockquote{ margin-left: 1em; margin-right: 1em; border:none; }
    blockquote{ margin-left: 1em; margin-right: 1em; border: none; }

  4. Property values are directly followed by a semicolon, even if it’s the last value in a selector.

    abbr[epub|type~="se:era"]{ font-variant: all-small-caps }
    abbr[epub|type~="se:era"]{ font-variant: all-small-caps; }

SVG Formatting

  1. SVG formatting follows the same directives as XHTML formatting.

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

Filesystem Layout and File Naming Conventions

A bare Standard Ebooks directory structure looks like this:

A directory tree representing the structure of a bare Standard Ebook.

File locations

  1. XHTML files containing the actual text of the ebook are located in ./src/epub/text/. All files in this directory end in .xhtml.

  2. CSS files used in the ebook are located in ./src/epub/css/. All files in this directory end in .css. This directory contains only three CSS files:

    1. ./src/epub/css/core.css is distributed with all ebooks and is not edited.

    2. ./src/epub/css/se.css is also distributed with all ebooks and is not edited.

    3. ./src/epub/css/local.css is used for custom CSS local to the particular ebook.

  3. Raw source images used in the ebook, but not distributed with the ebook, are located in ./images/. These images may be, for example, very high resolution that are later converted to lower resolution for distribution, or raw bitmaps that are later converted to SVG for distribution. Every ebook contains the following images in this directory:

    1. ./images/titlepage.svg is the editable titlepage file that is later compiled for distribution.

    2. ./images/cover.svg is the editable cover file that is later compiled for distribution.

    3. ./images/cover.source.(jpg|png|bmp|tif) is the raw cover art file that may be cropped, resized, or otherwise edited to create ./images/cover.jpg.

    4. ./images/cover.jpg is the final edited cover art that will be compiled into ./src/epub/images/cover.svg for distribution.

  4. Images compiled or derived from raw source images, that are then distributed with the ebook, are located in ./src/epub/images/.

  5. The table of contents is located in ./src/epub/toc.xhtml.

  6. The epub metadata file is located in ./src/epub/content.opf.

  7. The ONIX metadata file is located in ./src/epub/onix.xml. This file is identical for all ebooks.

  8. The ./src/META-INF/ and ./src/mimetype directory and files are epub structural files that are identical for all ebooks.

  9. The ./LICENSE.md contains the ebook license and is identical for all ebooks.

XHTML file naming conventions

  1. Numbers in filenames don’t include leading 0s.

  2. Files containing a short story, essay, or other short work in a larger collection, are named with the URL-safe title of the work, excluding any subtitles.

    Work Filename
    A short story named “The Variable Man” the-variable-man.xhtml
    A short story named “The Sayings of Limpang-Tung (The God of Mirth and of Melodious Minstrels)” the-sayings-of-limpang-tung.xhtml

  3. Works that are divided into larger parts (sometimes called “parts,” “books,” “volumes,” “sections,” etc.) have their part divisions contained in individual files named after the type of part, followed by a number starting at 1.

    book-1.xhtml

    book-2.xhtml

    part-1.xhtml

    part-2.xhtml

  4. Works that are composed of chapters, short stories, essays, or other short- to medium-length sections have each of those sections in an individual file.

    1. Chapters not contained in separate volumes are named chapter-N.xhtml, where N is the chapter number starting at 1.

      Section Filename
      Chapter 1 chapter-1.xhtml
      Chapter 2 chapter-2.xhtml

    2. Chapters contained in separate volumes, where the chapter number re-starts at 1 in each volume, are named chapter-X-N.xhtml, where X is the part number starting at 1, and N is the chapter number within the part, starting at 1.

      Section Filename
      Part 1 part-1.xhtml
      Part 1 Chapter 1 chapter-1-1.xhtml
      Part 1 Chapter 2 chapter-1-2.xhtml
      Part 1 Chapter 3 chapter-1-3.xhtml
      Part 2 part-2.xhtml
      Part 2 Chapter 1 chapter-2-1.xhtml
      Part 2 Chapter 2 chapter-2-2.xhtml

    3. Chapters contained in separate volumes, where the chapter number does not re-start at 1 in each volume, are named chapter-N.xhtml, where N is the chapter number, starting at 1.

      Section Filename
      Part 1 part-1.xhtml
      Chapter 1 chapter-1.xhtml
      Chapter 2 chapter-2.xhtml
      Chapter 3 chapter-3.xhtml
      Part 2 part-2.xhtml
      Chapter 4 chapter-4.xhtml
      Chapter 5 chapter-5.xhtml

    4. Works that are composed of extremely short sections, like a volume of short poems, are in a single file containing all of those short sections. The filename is the URL-safe name of the work.

      Section Filename
      A book of short poems called “North of Boston” north-of-boston.xhtml

    5. Frontmatter and backmatter sections have filenames that are named after the type of section, regardless of what the actual title of the section is.

      Section Filename
      A preface titled “Note from the author” preface.xhtml

    6. If a work contains more than one section of the same type (for example multiple prefaces), the filename is followed by -N, where N is a number representing the order of the section, starting at 1.

      Section Filename
      The work’s first preface, titled “Preface to the 1850 Edition” preface-1.xhtml
      The work’s second preface, titled “Preface to the Charles Dickens Edition” preface-2.xhtml

  5. If a work contains images other than the cover art, the filename of each image should be illustration- followed by -N, where N is a number representing the image’s order of appearance in the work, starting at 1.

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.

  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:

    <?xml version="1.0" encoding="utf-8"?> <se-lint-ignore> </se-lint-ignore>

  3. The <se-lint-ignore> root element contains one or more <file> elements.

    1. <file> elements have a path attribute containing a filename to match in ./src/epub/text/.

      <file path="chapter-3-1-11.xhtml"> </file>

    2. path attributes accept shell-style globbing to match files.

      <file path="chapter-*.xhtml"> </file>

    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. The value of <reason> is a prose explanation about why the code was ignored. This aids future producers or reviewers in understanding the reasoning behind why an error code was ignored.

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

Example

The following is an example of a complete se-lint-ignore.xml file from Tractatus Logico-Philosophicus.

<?xml version="1.0" encoding="utf-8"?> <se-lint-ignore> <file path="introduction.xhtml"> <ignore> <code>t-002</code> <reason>Punctuation is deliberately placed outside of quotes in this ebook to prevent confusion with mathematical symbols and formulas.</reason> </ignore> </file> <file path="tractatus-logico-philosophicus.xhtml"> <ignore> <code>s-021</code> <reason>The &lt;title&gt; tag is accurate; the work title appears in the half title.</reason> </ignore> <ignore> <code>t-002</code> <reason>Punctuation is deliberately placed outside of quotes in this ebook to prevent confusion with mathematical symbols and formulas.</reason> </ignore> </file> </se-lint-ignore>

The Structure of an Ebook

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

The list below is ordered in the manner in which the items appear in a typical book. Some books may make exceptions to this ordering.

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

Front matter

Front matter is material that appears before 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.

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.

Imprint

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

Dedication

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

Epigraph

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

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

Acknowledgements

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

Foreword

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

Preface

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

Introduction

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

Half title

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

  1. The half title lists the title of the book, but not the author.

  2. A half title is required if there is any front matter in the book.

Table of Contents

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

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

Body matter

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

Prologue

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

A prologue is generally part of the body matter, unless the prologue is a fictional element of a frame narrative. In that case, in order to preserve the frame narrative it may be placed in front of the half title and given frontmatter semantic inflection, while also keeping the prologue semantic inflection. For example, see The Narrative of Arthur Gordon Pym of Nantucket.

Epilogue

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

Back matter

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

Afterword

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

List of Illustrations

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

Endnotes

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

Colophon

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

Copyright Page

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

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

Semantics

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

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

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

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

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

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

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

Semantic Elements

Epub allows for the use of the full range of elements in the HTML5 spec. Each element has a semantic meaning, and each element in a Standard Ebook is carefully considered before use.

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

Block-level elements

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

  1. Sectioning block-level elements denote major structural divisions in a work.

    1. <body>: The top-level element in any XHTML file. Must contain a direct child that is either a <section> or <article>.

    2. <section>: A major structural division in a work. Typically a part, volume, chapter, or subchapter. Semantically a <section> cannot stand alone, but is part of a larger work.

    3. <article>: An item in a larger work that could be pulled out of the work and serialized or syndicated separately. For example, a single poem in a poetry collection, or a single short story in a short story collection; but not a single poem in a larger novel.

  2. Other block-level elements have well-defined semantic meanings.

    1. <p>: A paragraph of text.

    2. <blockquote>: A quotation displayed on the block level. This may include non-speech “quotations” like business cards, headstones, telegrams, letters, and so on.

    3. <figure>: Encloses a photograph, chart, or illustration, represented with an <img> element. Optionally includes a <figcaption> element for a context-appropriate caption.

    4. <figcaption>: Only appears as a child of <figure>. Represents a context-appropriate caption for the sibling <img>. A caption is not the same as an <img> element’s alt text. alt text is strictly a textual description of the image used for screen readers, whereas <figcaption> has more freedom in its contents, depending on its context.

    5. <header>: Denotes a header section applying to its direct parent. <header> is typically found in sections where there is additional header content besides the section title, but can also be used in <blockquote>s or other block-level elements that require header styling.

    6. <footer>: Denotes a footer section applying to its direct parent. Typically used to denote signatures in sections like prefaces, forewords, letters, telegrams, and so on.

    7. <hr/>: Denotes a thematic break. <hr/> is not used any place a black border is desired; it strictly denotes a thematic break.

    8. <ol>: Denotes an ordered list. Ordered lists are automatically numbered by the renderer.

    9. <ul>: Denotes an unordered list. Unordered lists are bulleted by the renderer.

    10. <li>: Denotes a list item in a parent <ol> or <ul>.

    11. <table>: Denotes a tabular section, for example when displaying tabular data, or reports or charts where a tabular appearance is desired.

  3. <div> elements are almost never appropriate, as they have no semantic meaning. However, they may in rare occasions be used to group related elements in a situation where no other semantic element is appropriate.

Inline elements

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

  1. <em>: Text rendered in italics, with the semantic meaning of emphasized speech, or speech spoken in a different tone of voice; for example, a person shouting, or putting stress on a particular word.

  2. <i>: Text rendered in italics, without any explicit semantic meaning. Because <i> lacks semantic meaning, the epub:type attribute is added with appropriate semantic inflection to describe the contents of the element.

    <p>The <abbr epub:type="z3998:initialism">H.M.S.</abbr> <i epub:type="se:name.vessel.ship">Bounty</i>.</p>

  3. <b>: Text rendered in small caps, without any explicit semantic meaning. Because <b> lacks semantic meaning, the epub:type attribute can be added with appropriate semantic inflection to describe the contents of the element; however, unlike <i>, it’s rare for <b> to require semantic meaning, as it is generally used only for visual styling.

  4. <span>: Plain inline text that requires specific styling or semantic meaning that cannot be achieved with any other semantically meaningful inline element. Typically used in conjunction with a class or epub:type attribute.

Semantic Inflection

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

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

<section epub:type="chapter">...</section>

  1. The epub spec includes a vocabulary that can be used in the epub:type attribute. This vocabulary has priority when selecting a semantic keyword, even if other vocabularies contain the same one.

  2. The epub spec might not contain a keyword necessary to describe the semantics of a particular element. In that case, the z3998 vocabulary is consulted next.

    Keywords using this vocabulary are preceded by the z3998 namespace.

    <blockquote epub:type="z3998:letter">...</blockquote>

  3. If the z3998 vocabulary doesn’t have an appropriate keyword, the Standard Ebooks vocabulary is consulted next.

    Keywords using this vocabulary are preceded by the se namespace.

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

    The <abbr epub:type="z3998:initialism">H.M.S.</abbr> <i epub:type="se:name.vessel.ship">Bounty</i>.

  4. The epub:type attribute can have multiple keywords separated by spaces, even if the vocabularies are different.

    <section epub:type="chapter z3998:letter">...</section>

  5. Child elements inherit the semantics of their parent element.

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

    <body epub:type="z3998:non-fiction"> <section id="chapter-1" epub:type="chapter"> <h2 epub:type="ordinal z3998:roman">I</h2> ... </section> <section id="chapter-2" epub:type="chapter"> <h2 epub:type="ordinal z3998:roman">II</h2> ... </section> </body>

General XHTML and CSS Patterns

This section covers general patterns used when producing XHTML and CSS that are not specific to ebooks.

id attributes

id attributes of <section> and <article> elements

  1. Each <section> and <article> element has an id attribute.

  2. <section> or <article> elements that are direct children of the <body> element have an id attribute identical to the filename containing that <section> or <article>, without the trailing extension.

  3. In files containing multiple <section> or <article> elements, each of those elements has an id attribute identical to what the filename would be if the section was in an individual file, without the trailing extension.

    <body epub:type="bodymatter z3998:fiction"> <article id="the-fox-and-the-grapes" epub:type="se:short-story"> <h2 epub:type="title">The Fox and the Grapes</h2> <p>...</p> </article> <article id="the-goose-that-laid-the-golden-eggs" epub:type="se:short-story"> <h2 epub:type="title">The Goose That Laid the Golden Eggs</h2> <p>...</p> </article> </body>

id attributes of other elements

  1. id attributes are generally used to identify parts of the document that a reader may wish to navigate to using a hash in the URL. That generally means major structural divisions. Therefore, elements that are not <section> or <article> elements do not have an id attribute, unless a part of the ebook, like an endnote, refers to a specific point in the book, and a direct link is desirable.

  2. id attributes are not used as hooks for CSS styling.

  3. <figure> elements have an id attribute set to figure-N, where N is the sequence number of the figure across the entire ebook, starting at 1.

    <!-- chapter-1.xhtml --> <section id="chapter-1" epub:type="chapter"> <p>...</p> <figure id="figure-1">...</figure> <p>...</p> </section> <!-- chapter-2.xhtml --> <section id="chapter-2" epub:type="chapter"> <p>...</p> <p>...</p> <figure id="figure-2">...</figure> </section>

  4. Noteref elements have their id attributes set to noteref-N, where N is the sequence number of the noteref across the entire ebook, starting at 1.

    <p>We threw an empty oil can down and it echoed for a terribly long time.<a href="endnotes.xhtml#note-228" id="noteref-228" epub:type="noteref">228</a></p>

  5. Endnote elements have their id attributes set to note-N, where N is the sequence number of the endnote, starting at 1.

    <li id="note-1" epub:type="endnote"> <p>Cook, <i epub:type="se:name.publication.book">A Voyage Towards the South Pole</i>, Introduction. <a href="introduction.xhtml#noteref-1" epub:type="backlink">↩</a></p> </li>

  6. <dt> elements have their id attribute set to the URL-safe version of the text contents of their child <dfn> element.

    <section id="glossary" epub:type="glossary"> <dl> <dt id="blizzard" epub:type="glossterm"> <dfn>Blizzard</dfn> </dt> </dl> </section>

  7. Other non <dt> children of semantic glossary elements do not have standardized id attributes, but rather should be set descriptively based on context.

  8. If an element whose id attribute is not otherwise standardized requires an id attribute, then the attribute’s value is formed by taking the id attribute of the closest parent <section>, <article>, or endnote, appending -, then the name of the element, then -N, where N is the sequence number of the element starting at 1 in the flattened document tree order of its closest parent sectioning element.

    <section id="chapter-1" epub:type="chapter"> <header> <h2 epub:type="title">...</h2> <p epub:type="bridgehead">...</p> </header> <p id="chapter-1-p-2">...</p> <section id="chapter-1-1" epub:type="z3998:subchapter"> <p>See <a href="#chapter-1-1-p-4">this paragraph</a> for more details.</p> <p>...</p> <p>See <a href="#chapter-1-p-2">this paragraph</a>.</p> <blockquote> <p id="chapter-1-1-p-4">...</p> </blockquote> <p>...</p> </section> </section>

  9. For poems with the z3998:poem semantic in which a child has an id attribute referring to a specific line number, the id attribute’s value is formed by taking the id attribute of the closest parent <section> or <article> that contains the z3998:poem semantic, appending -line, then -N, where N is the sequence number of the line starting at 1 in the flattened document tree order of the selected sectioning element, excluding <header> elements.

    <article id="the-waste-land" epub:type="z3998:poem"> <section id="the-waste-land-1" epub:type="z3998:subchapter"> <p> <span>April is the cruellest month, breeding</span> <br/> <span id="the-waste-land-line-2">Lilacs out of the dead land, mixing</span> <br/> <span>Memory and desire, stirring</span> </p> </section> <section id="the-waste-land-2" epub:type="z3998:subchapter"> <p> <span>The Chair she sat in, like a burnished throne,</span> <br/> <span>Glowed on the marble, where the glass</span> <br/> <span id="the-waste-land-line-6">Held up by standards wrought with fruited vines</span> </p> </section> </article>

  10. Individual id attributes are unique across the entire ebook.

    1. If an element requires an id attribute that would conflict with one in a different file, the id attribute of the closest parent sectioning element, followed by -, is prepended to each id attribute to differentiate them.

      <!-- chapter-1.xhtml --> <section id="chapter-1" epub:type="chapter"> <p id="p-1">...</p> </section> <!-- chapter-2.xhtml --> <section id="chapter-2" epub:type="chapter"> <p id="p-1">...</p> </section>
      <!-- chapter-1.xhtml --> <section id="chapter-1" epub:type="chapter"> <p id="chapter-1-p-1">...</p> </section> <!-- chapter-2.xhtml --> <section id="chapter-2" epub:type="chapter"> <p id="chapter-2-p-1">...</p> </section>

class attributes

Classes denote a group of elements sharing a similar style.

  1. Classes are not used as single-use style hooks. There is almost always a way to compose a CSS selector to select a single element without the use of a one-off class.

    .business-card{ border: 1px solid; padding: 1em; }
    <body epub:type="bodymatter z3998:fiction"> <section epub:type="chapter"> <p>...</p> <p>...</p> <p>...</p> <p>...</p> <blockquote class="business-card"> <p>John Doe, <abbr class="eoc">Esq.</abbr></p> </blockquote> </section> </body>
    #chapter-3 blockquote{ border: 1px solid; padding: 1em; }
    <body epub:type="bodymatter z3998:fiction"> <section id="chapter-3" epub:type="chapter"> <p>...</p> <p>...</p> <p>...</p> <p>...</p> <blockquote> <p>John Doe, <abbr class="eoc">Esq.</abbr></p> </blockquote> </section> </body>

  2. Classes are used to style a recurring class of elements, i.e. a class of element that appears more than once in an ebook.

    .business-card{ border: 1px solid; padding: 1em; }
    <body epub:type="bodymatter z3998:fiction"> <section id="chapter-3" epub:type="chapter"> <p>...</p> <p>...</p> <blockquote class="business-card"> <p>Jane Doe, <abbr class="eoc">Esq.</abbr></p> </blockquote> <p>...</p> <p>...</p> <blockquote class="business-card"> <p>John Doe, <abbr class="eoc">Esq.</abbr></p> </blockquote> </section> </body>

  3. Class names describe what they are styling semantically, not the actual style the class is applying.

    .black-border{ border: 1px solid; padding: 1em; }
    .business-card{ border: 1px solid; padding: 1em; }

xml:lang attributes

  1. When words are required to be pronounced in a language other than English, the xml:lang attribute is used to indicate the IETF language tag in use.

    1. The xml:lang attribute is used even if a word is not required to be italicized. This allows screen readers to understand that a particular word or phrase should be pronounced in a certain way. A <span xml:lang="TAG"> element is used to wrap text that has non-English pronunciation but that does not need further visual styling.

    2. The xml:lang attribute is included in any word that requires special pronunciation, including names of places and titles of books.

    She opened the book titled <i epub:type="se:name.publication.book" xml:lang="la">Mortis Imago</i>.

    1. The xml:lang attribute is applied to the highest-level element possible. If italics are required and moving the xml:lang attribute would also remove an <i> element, the parent element can be styled with body [xml|lang]{ font-style: italic; }. This style also requires a namespace declaration at the top of the file: @namespace xml "http://www.w3.org/XML/1998/namespace";.

    <blockquote> <p><i xml:lang="es">“¿Cómo estás?”, él preguntó.</i></p> <p><i xml:lang="es">“Bien, gracias,” dijo ella.</i></p> </blockquote>
    <blockquote xml:lang="es"> <p>“¿Cómo estás?”, él preguntó.</p> <p>“Bien, gracias,” dijo ella.</p> </blockquote>

The <title> element

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

  2. The value of the title element is determined by the algorithm used to determine the file's ToC entry, except that no XHTML tags are allowed in the <title> element.

Headers

  1. <header> elements have at least one direct child block-level element. This is usually a <p> element, but not necessarily.

Ordered/numbered and unordered lists

  1. All <li> children of <ol> and <ul> elements have at least one direct child block-level element. This is usually a <p> element, but not necessarily; for example, a <blockquote> element might also be appropriate.

    <ul> <li>Don’t forget to feed the pigs.</li> </ul>
    <ul> <li> <p>Don’t forget to feed the pigs.</p> </li> </ul>

Tables

Tables can often be difficult to represent semantically. For understanding the high-level concepts of tables and the semantic meaning of the various table-related elements, refer to the HTML Living Standard secton on tables. For detailed examples on how to represent complex tables in a semantic and accessible way, refer to the Web Accessibility Initiative guide on creating accessible tables.

  1. <table> elements have a direct child <tbody> element.

    <table> <tr> <td>1</td> <td>2</td> </tr> </table>
    <table> <tbody> <tr> <td>1</td> <td>2</td> </tr> </tbody> </table>

    1. More than one <tbody> element may be included if a table has additional headers in the middle of the table body.

      <table> <tbody> <tr> <th colspan="2" scope="rowgroup">Breakfast:</th> </tr> <tr> <td>1 <abbr>pt.</abbr> milk</td> <td>.05</td> </tr> <tr> <td>Cereal</td> <td>.01</td> </tr> <tr> <td>Fruit</td> <td>.02</td> </tr> </tbody> <tbody> <tr> <th colspan="2" scope="rowgroup">Late Supper:</th> </tr> <tr> <td>Soup (potato, pea, bean)</td> <td>.02</td> </tr> <tr> <td>Rolls</td> <td>.02</td> </tr> </tbody> <tfoot> <tr> <th scope="row">Total:</th> <td>.12</td> </tr> </tfoot> </table>

  2. <table> elements may have an optional direct child <thead> element, if a table heading is desired.

    1. <th> elements are used in <thead> elements, instead of <td>.

    2. <th> elements only appear in <thead> elements, unless they contain the scope attribute. The scope attribute may be used to semantically identify a table header which applies to a horizontal row instead of a vertical column, or to a row group in a table with multiple <tbody> elements.

  3. <table> elements that display a total or summary row at the bottom have that row contained in a <tfoot> element.

  4. <table> elements that are not used to format plays/dramas, and that do not otherwise inherit a visible margin (for example, they are not children of <blockquote>), have margin: 1em; or margin: 1em auto 1em auto;.

Blockquotes

  1. <blockquote> elements must contain at least one block-level child, like <p>.

  2. Blockquotes that have a citation include the citation as a direct child <cite> element.

    <blockquote> <p>“All things are ready, if our mind be so.”</p> <cite>—<i epub:type="se:name.publication.play">Henry <span epub:type="z3998:roman">V</span></i></cite> </blockquote>

Definition lists

Definition lists, i.e. combinations of the <dl>, <dt>, and <dd> elements, are often found in glossaries.

See here for glossaries.

  1. <dd> elements have at least one direct child block-level element. This is usually a <p> element, but not necessarily.

CSS rules

  • text-align: initial; is used instead of text-align: left; whenever it's necessary to explicitly set left-aligned text. This allows the reading system to opt to use text-align: justify; if the user prefers.

  • The vh unit is used instead of percent units when specifying height, max-height, top, or bottom.

    figure{ height: 100%; position: absolute; top: 5%; }
    figure{ height: 100vh; position: absolute; top: 5vh; }

Standard Ebooks Section Patterns

All Standard Ebooks contain a standardized 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 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 multiple authors.

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

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 build-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> element is a <nav> element with the semantic inflection toc.

  2. The first child of the <nav> element is a <h2 epub:type="title">Table of Contents</h2> element.

  3. The second child of the <nav> element is an <ol> element representing the items in the Table of Contents.

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. The second child is a link to the imprint.

    <li> <a href="text/imprint.xhtml">Imprint</a> </li>

  3. The second-to-last child is a link to the colophon.

    <li> <a href="text/colophon.xhtml">Colophon</a> </li>

  4. The last child is a link to the Uncopyright.

    <li> <a href="text/uncopyright.xhtml">Uncopyright</a> </li>

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

    1. In books that have a half title page, and whose body text is a single file without heading content (for example, Father Goriot or The Path to Rome), the half title page ToC entry text is set to Half-Titlepage.

    <li> <a href="text/halftitlepage.xhtml">Half-Titlepage</a> <ol> <li> <a href="text/father-goriot.xhtml">Father Goriot</a> </li>

<li> descendents

  1. Each <li> contains an <a> element pointing to a file or hash, and optionally also contains an <ol> element representing a nested series of ToC items.

  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/halftitlepage.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. Roman numerals in the ToC have a <span> element 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>

<a> descendents

  1. The title, subtitle, ordinal, and any related title epub semantics are not included in ToC entries. Their usage context is only within actual heading content.

  2. The text of the <a> element is decided as follows:

    1. If there is no <hgroup> in the section, the text becomes the inner XHTML of the top <h1>–<h6> element with any of the above semantics removed.

    2. If there is an <hgroup> element:

      1. If the <hgroup>’s closest parent <section> or <article> has an epub:type value of part, division, or volume, then keep all <hgroup> children.

      2. Otherwise, if the <hgroup>’s closest parent <section> or <article> has an epub:type value of halftitlepage, or if the first child of the <hgroup> has the title semantic, then discard any children with the subtitle semantic.

      3. Then, the text becomes the inner XHTML of the first <hgroup> child. If there is a second child, append a colon and space to the text, then the inner XHTML of the second child. The above semantics are then removed.

Examples
<article id="a-daughter-of-albion" epub:type="se:short-story"> <h2 epub:type="title">A Daughter of Albion</h2> <p>...</p> </article>

Result: A Daughter of Albion

<section id="book-1" epub:type="part"> <hgroup> <h2> <span epub:type="label">Book</span> <span epub:type="ordinal z3998:roman">I</span> </h2> <h3 epub:type="title">The Coming of the Martians</h3> </hgroup> <p>...</p> </section>

Result: Book <span epub:type="z3998:roman">I</span>: The Coming of the Martians

<section id="chapter-1" epub:type="chapter"> <hgroup> <h2 epub:type="ordinal z3998:roman">I</h2> <h3 epub:type="title">A Fellow Traveller</h3> </hgroup> <p>...</p> </section>

Result: <span epub:type="z3998:roman">I</span>: A Fellow Traveller

<section id="epilogue" epub:type="epilogue"> <hgroup> <h3 epub:type="title">Epilogue</h3> <h4 epub:type="subtitle">A Morning Call</h4> </hgroup> <p>...</p> </section>

Result: Epilogue

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. The second child is an <ol> element listing the major structural divisions of the book.

<li> descendents

Each <li> element contains a link to either the start of the main text (i.e. the start of the bodymatter, excluding a half titlepage), or to a major reference section (i.e. backmatter including endnotes, bibliography, glossary, index, LoI, etc.). See the IDPF a11y best practices document for more information.

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

    <li> <a href="text/endnotes.xhtml" epub:type="backmatter endnotes">Endnotes</a> </li>

  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>

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. The title page has a <title> element with the value Titlepage.

  3. The titlepage contains one <section id="titlepage" epub:type="titlepage"> element which in turn contains one <h1 epub:type="title"> element, author information, as well as one <img src="../images/titlepage.svg"> element.

  4. The titlepage does not contain the subtitle, if there is one.

  5. The <img> element has an empty alt attribute.

  6. 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"> <h1 epub:type="title">TITLE</h1> <p>By <b epub:type="z3998:author">AUTHOR</b>.</p> <p>Translated by <b epub:type="z3998:translator">TRANSLATOR</b>.</p> <p>Illustrated by <b>ILLUSTRATOR</b>.</p> <img alt="" src="../images/titlepage.svg" epub:type="se:color-depth.black-on-transparent"/> </section> </body> </html>

The imprint

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

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

  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. 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. 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 from <a href="IA_URL">the Internet Archive</a>.</p>
      <p>This particular ebook is based on digital scans from the <a href="IA_URL">Internet Archive</a>.</p>

    3. If an ebook is based on multiple sources or transcriptions (for example, a short story collection of a voluminous author), then the source sentence is altered to reflect that either the transcriptions, the page scans, or both, came from various sources.

      1. If transcriptions or page scans come from the same domain (like only the Internet Archive or HathiTrust):

        <p>This particular ebook is based on transcriptions from <a href="EBOOK_URL#transcriptions">Project Gutenberg</a> and on digital scans from the <a href="IA_URL">Internet Archive</a>.</p>
        <p>This particular ebook is based on a transcription from <a href="PG_URL">Project Gutenberg</a> and on digital scans from the <a href="EBOOK_URL#page-scans">Internet Archive</a>.</p>
        <p>This particular ebook is based on transcriptions from <a href="EBOOK_URL#transcriptions">Project Gutenberg</a> and on digital scans from the <a href="EBOOK_URL#page-scans">Internet Archive</a>.</p>

      2. If transcriptions or page scans come from more than one domain (like both the Internet Archive and HathiTrust):

        <p>This particular ebook is based on transcriptions from <a href="EBOOK_URL#transcriptions">various sources</a> and on digital scans from the <a href="IA_URL">Internet Archive</a>.</p>
        <p>This particular ebook is based on a transcription from <a href="PG_URL">Project Gutenberg</a> and on digital scans from <a href="EBOOK_URL#page-scans">various sources</a>.</p>
        <p>This particular ebook is based on transcriptions from <a href="EBOOK_URL#transcriptions">various sources</a> and on digital scans from <a href="EBOOK_URL#page-scans">various sources</a>.</p>

  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 se:color-depth.black-on-transparent"/> </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 from <a href="PG_URL">Project Gutenberg</a> and on digital scans from 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>

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. The half title page is located after the last item of front matter, before the body matter.

  3. The half title page has a <title> element containing the full title of the ebook.

  4. The half title page contains one <section id="halftitlepage" epub:type="halftitlepage"> element, which in turn contains either one <h2 epub:type="fulltitle"> element containing the full title of the ebook, or one <hgroup epub:type="fulltitle"> element containing one <h2 epub:type="title"> element and one <h3 epub:type="subtitle"> element.

  5. If the ebook has a subtitle, it is included in the half title page.

  6. The fulltitle semantic is applied to the top-level heading element in the half title page. This is usually either <hgroup> in works with subtitles or <h2> in works without.

  7. Formatting for the <h2> element follows patterns in 7.2.9.

  8. 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>His Last Bow</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"> <hgroup epub:type="fulltitle"> <h2 epub:type="title">His Last Bow</h2> <h3 epub:type="subtitle">Some Reminiscences of Sherlock Holmes</h3> </hgroup> </section> </body> </html>

The colophon

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

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

  3. The colophon 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.

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. If a name does not have a Wikipedia entry, the name is wrapped in <b epub:type="z3998:personal-name">.

  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 epub:type="z3998:personal-name">Fritz Ohrenschall</b>, <b epub:type="z3998:personal-name">Sania Ali Mirza</b> and <a href="https://www.pgdp.net">The Online Distributed Proofreading Team</a>
    <b epub:type="z3998:personal-name">Fritz Ohrenschall</b>, <b epub:type="z3998:personal-name">Sania Ali Mirza</b>, and <a href="https://www.pgdp.net">The Online Distributed Proofreading Team</a>

Anonymous contributors

  1. Anonymous or unknown primary contributors (like the author or cover artist) are listed as <b>Anonymous</b>.

  2. Anonymous volunteers working on digitization or the actual ebook production are listed as <b>An Anonymous Volunteer</b>. Note that their metadata entries are still listed as Anonymous, even though their colophon entries differ.

  3. Both types of volunteer string are not names, therefore their parent <b> elements do not have name semantics.

Sponsors

  1. An ebook may have a financial sponsor. If so, the following block:

    <p>This ebook was produced for<br/> <a href="https://standardebooks.org">Standard Ebooks</a><br/> by<br/>

    is replaced with:

    <p><a href="SPONSOR_HOMEPAGE_URL">SPONSOR_NAME</a><br/> sponsored the production of this ebook for<br/> <a href="https://standardebooks.org">Standard Ebooks</a>.<br/> It was produced by<br/>

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. 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> element. 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/> <a href="https://en.wikipedia.org/wiki/Henry_S._Spalding">Henry Spalding</a>.</p>

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

      <p>This ebook was produced for<br/> <a href="https://standardebooks.org">Standard Ebooks</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>An Anonymous Volunteer</b> and <b epub:type="z3998:personal-name">David Widger</b><br/> for<br/> <a href="https://www.gutenberg.org/ebooks/965">Project Gutenberg</a><br/> and on digital scans from the<br/> <a href="https://archive.org/details/worksofdumas24dumaiala">Internet Archive</a>.</p>

      1. If the Standard ebooks producer also transcribed the book in its entirety, then the first line becomes: <p>This ebook was transcribed and produced for<br/>.

      2. If an ebook is based on multiple sources or transcriptions (for example, a short story collection of a voluminous author), then the source sentence is altered to reflect that either the transcriptions, the page scans, or both, came from various sources. Individual transcriber names are ommitted.

        1. If the transcriptions or page scans all came from the same source (i.e., all of the transcriptions came from Project Gutenberg):

          <p>This ebook was produced for<br/> <a href="https://standardebooks.org">Standard Ebooks</a><br/> by<br/> <a href="https://www.robinwhittleton.com/">Robin Whittleton</a>,<br/> and is based on transcriptions from<br/> <a href="EBOOK_URL#transcriptions">Project Gutenberg</a><br/> and on digital scans from the<br/> <a href="https://archive.org/details/worksofdumas24dumaiala">Internet Archive</a>.</p>
          <p>This ebook was produced for<br/> <a href="https://standardebooks.org">Standard Ebooks</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>An Anonymous Volunteer</b> and <b epub:type="z3998:personal-name">David Widger</b><br/> for<br/> <a href="https://www.gutenberg.org/ebooks/965">Project Gutenberg</a><br/> and on digital scans from the<br/> <a href="EBOOK_URL#page-scans">Internet Archive</a>.</p>
          <p>This ebook was produced for<br/> <a href="https://standardebooks.org">Standard Ebooks</a><br/> by<br/> <a href="https://www.robinwhittleton.com/">Robin Whittleton</a>,<br/> and is based on transcriptions from<br/> <a href="EBOOK_URL#transcriptions">Project Gutenberg</a><br/> and on page scans from the<br/> <a href="EBOOK_URL#page-scans">Internet Archive</a>.</p>

        2. If the transcriptions or page scans came from different sources:

          <p>This ebook was produced for<br/> <a href="https://standardebooks.org">Standard Ebooks</a><br/> by<br/> <a href="https://www.robinwhittleton.com/">Robin Whittleton</a>,<br/> and is based on transcriptions from <br/> <a href="EBOOK_URL#transcriptions">various sources</a><br/> and on digital scans from the<br/> <a href="https://archive.org/details/worksofdumas24dumaiala">Internet Archive</a>.</p>
          <p>This ebook was produced for<br/> <a href="https://standardebooks.org">Standard Ebooks</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>An Anonymous Volunteer</b> and <b epub:type="z3998:personal-name">David Widger</b><br/> for<br/> <a href="https://www.gutenberg.org/ebooks/965">Project Gutenberg</a><br/> and on digital scans from<br/> <a href="EBOOK_URL#page-scans">various sources</a>.</p>
          <p>This ebook was produced for<br/> <a href="https://standardebooks.org">Standard Ebooks</a><br/> by<br/> <a href="https://www.robinwhittleton.com/">Robin Whittleton</a>,<br/> and is based on transcriptions from<br/> <a href="EBOOK_URL#transcriptions">various sources</a><br/> and on digital scans from<br/> <a href="EBOOK_URL#page-scans">various sources</a>.</p>

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

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 se:color-depth.black-on-transparent"/> </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 epub:type="z3998:given-name">P. F.</abbr> Collier and Son</a>.</p> <p>This ebook was produced for<br/> <a href="https://standardebooks.org">Standard Ebooks</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>An Anonymous Volunteer</b> and <b epub:type="z3998:personal-name">David Widger</b><br/> for<br/> <a href="https://www.gutenberg.org/ebooks/965">Project Gutenberg</a><br/> and on digital scans from 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="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. The Uncopyright page follows the template created by se create-draft exactly.

High Level Structural Patterns

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

Sectioning

  1. The <body> element may only have direct children that are <section>, <article>, or <nav>.

  2. Major structural divisions of a larger work, like parts, volumes, books, chapters, or subchapters, are contained in a <section> element.

  3. Individual items in a larger collection (like a poem in a poetry collection) are contained in a <article> element.

    1. Collections of very short work, like collections of poems, have all of their content in a single file, and break-* CSS is added to generate page breaks between items:

      article, section{ break-after: page; }

  4. In <section> or <article> elements that have titles, the first child element is an <h1>–<h6> element, an <hgroup> element for grouping ordinals, titles, and subtitles, or a <header> element containing the section’s title.

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 <article> elements that are semantic children of <section> or <article> elements in other files, have a data-parent attribute that contains the id of the parent sectioning element.

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> <span epub:type="label">Book</span> <span epub:type="ordinal z3998:roman">I</span> </h2> </section>

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

<section data-parent="book-1" id="part-1-2" epub:type="part"> <h3> <span epub:type="label">Part</span> <span epub:type="ordinal z3998:roman">II</span> </h3> </section>

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

<section data-parent="part-1-2" id="chapter-1-2-3" epub:type="chapter"> <h4> <span epub:type="label">Chapter</span> <span epub:type="ordinal z3998:roman">III</span> </h4> <p>...</p> <p>...</p> </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. A section containing an <h1>–<h6> appears in the table of contents.

  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. 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><span epub:type="label">Part</span> <span epub:type="ordinal 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="ordinal z3998:roman">III</h2> ... </section> </section>
    <section id="part-2" epub:type="part"> <section id="chapter-2-3" epub:type="chapter"> <h3 epub:type="ordinal z3998:roman">III</h3> ... </section> </section>

  5. Each <h1>–<h6> element has a direct parent <section>, <article>, <header>, or <hgroup> element.

  6. <hgroup> elements are used to group <h1>–<h6> elements together when a section’s title has multiple components, for example a header that contains an ordinal and a title, or a header that includes a title and a subtitle.

    1. <hgroup> elements only have <h1>–<h6> children.

    2. <hgroup> elements are only present if more than one <h1>–<h6> element must be grouped together.

    3. The first <h1>–<h6> child of an <hgroup> element is the header level for the entire <hgroup>. For example, the following <hgroup> is at the <h3> header level, even though it contains an <h4>:

      <hgroup> <h3 epub:type="ordinal z3998:roman">III</h3> <h4 epub:type="title">At the Villa Geneviève</h4> </hgroup>

    4. <hgroup> elements in which <h6> is the first child have all subsequent children as <h6> as well.

  7. Headers follow regular rules for italics, with the exception that headers that are entirely non-English-language are not italicized. Even though they are not italicized, they retain xml:lang semantics on the parent element.

    <hgroup> <h3 epub:type="ordinal z3998:roman">XI</h3> <h4 epub:type="title">The <i epub:type="se:name.vessel.ship">Nautilus</i></h4> </hgroup>
    <hgroup> <h3 epub:type="ordinal z3998:roman">XI</h3> <h4 epub:type="title" xml:lang="la">Christus Nos Liberavit</h4> </hgroup>
    <hgroup> <h3 epub:type="ordinal z3998:roman">XI</h3> <h4 epub:type="title">Miss Thorne’s <i xml:lang="fr">Fête Champêtre</i></h4> </hgroup>

  8. If a section does not have any header content, including epigraphs or other non-prose material, then it has margin-top: 8em;.

Parts of a section title

Within section titles, we distinguish between labels, ordinals, titles, and subtitles.

  1. Labels are the part of a title that precedes the ordinal. Because they only appear next to ordinals, they are usually wrapped in <span epub:type="label"> within their parent <h1>–<h6> element.

    <h2><span epub:type="label">Canto</span> <span epub:type="ordinal z3998:roman">III</span></h2>

  2. Ordinals are the number specifying the section’s numeric order in a sequence. They are usually wrapped in <span epub:type="ordinal"> or <span epub:type="ordinal z3998:roman">, if the ordinal is a Roman numeral.

    <h2><span epub:type="label">Chapter</span> <span epub:type="ordinal z3998:roman">IV</span></h2>

    Ordinals may also appear without a label:

    <h2 epub:type="ordinal z3998:roman">IV</h2>

  3. Labels and ordinals are wrapped in an <h1>–<h6> element, but that wrapper element is not a semantic title.

  4. Titles are the main title of the section. Often sections may have labels and ordinals, but not titles; or sections may have a title, but no label or ordinal.

    <h2 epub:type="title">The New Villa</h2>
    <hgroup> <h2 epub:type="ordinal z3998:roman">IV</h2> <h3 epub:type="title">The Letter Signed “Bella”</h3> </hgroup>

  5. Subtitles are supplementary titles in addition to the main title.

    <hgroup> <h2 epub:type="title">Between the Scenes</h2> <h3 epub:type="subtitle">Progress of the Story Through the Post</h3> </hgroup>

Header patterns

  1. Sections with ordinals but without titles:

    <h2 epub:type="ordinal z3998:roman">XI</h2>

  2. Sections with titles but without ordinals:

    <h2 epub:type="title">A Daughter of Albion</h2>

  3. Sections with titles and ordinals:

    <hgroup> <h2 epub:type="ordinal z3998:roman">XI</h2> <h3 epub:type="title">Who Stole the Tarts?</h3> </hgroup>

  4. Sections titles and subtitles but no ordinals:

    <hgroup> <h2 epub:type="title">An Adventure</h2> <h3 epub:type="subtitle">(A Driver’s Story)</h3> </hgroup>

  5. Sections with labels and ordinals:

    <h2> <span epub:type="label">Book</span> <span epub:type="ordinal z3998:roman">II</span> </h2>

  6. Sections with labels, ordinals, and titles:

    <hgroup> <h2> <span epub:type="label">Book</span> <span epub:type="ordinal z3998:roman">II</span> </h2> <h3 epub:type="title">The Man in the Street</h3> </hgroup>

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

    <hgroup> <h2 epub:type="title">Sonnet</h2> <h3 hidden="hidden" epub:type="subtitle">Happy Is England!</h3> </hgroup>

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

  9. Sections without any titles at all have margin-top: 20vh applied to their sectioning container.

    section[epub|type~="preface"]{ margin-top: 20vh; }
    <section epub:type="preface"> <p>Being observations or memorials of the most remarkable occurrences...</p> <p>...</p> </section>

  10. Half title pages without subtitles:

    <h2 epub:type="fulltitle">Eugene Onegin</h2>

  11. Half title pages with subtitles:

    <hgroup epub:type="fulltitle"> <h2 epub:type="title">His Last Bow</h2> <h3 epub:type="subtitle">Some Reminiscences of Sherlock Holmes</h3> </hgroup>

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. 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; } [epub|type~="z3998:poem"] [epub|type~="bridgehead"], [epub|type~="z3998:verse"] [epub|type~="bridgehead"], [epub|type~="z3998:song"] [epub|type~="bridgehead"], [epub|type~="z3998:hymn"] [epub|type~="bridgehead"]{ text-align: justify; }
    <header> <h2 epub:type="ordinal 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="ordinal 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>

  2. Bridgeheads are typically set in italics. Exceptions are allowed according to rules for italics.

  3. The last clause in a bridgehead ends in appropriate punctuation, like a period.

  4. Bridgeheads consisting of a series of clauses that summarize the following chapter have each clause separated by an em dash. Each clause is sentence-cased.

    <header> <h2 epub:type="ordinal z3998:roman">XI</h2> <p epub:type="bridgehead">How George, once upon a time, got up early in the morning⁠wj—George, Harris, and Montmorency do not like the look of the cold water⁠wj—Heroism and determination on the part of <abbr epub:type="z3998:given-name">J.</abbr>⁠wj—George and his shirt: story with a moral⁠wj—Harris as cook⁠wj—Historical retrospect, specially inserted for the use of schools.</p> </header>

Dedications

Dedications are typically either a short phrase centered on the page, or a longer prose-form dedication similar in appearance and typesetting to regular prose.

Dedications are frequently styled uniquely by authors. Therefore there is freedom to style dedications to match the author’s unique style choices, for example by including small caps, different font sizes, alignments, etc.

  1. Short-type dedications are centered on the page for ereaders that support advanced CSS. For all other ereaders, such dedications are horizontally centered with a small top margin. The following CSS is used for such dedications:

    /* Centered dedications */ section[epub|type~="dedication"]{ text-align: center; } 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 centered dedications */

  2. Prose-type dedications are styled like regular chapters, including a top margin if there is no heading material.

Epigraphs

  1. All epigraphs include this CSS:

    /* All epigraphs */ [epub|type~="epigraph"]{ font-style: italic; hyphens: none; -epub-hyphens: none; } [epub|type~="epigraph"] em, [epub|type~="epigraph"] i{ font-style: normal; } [epub|type~="epigraph"] cite{ font-style: normal; font-variant: small-caps; margin-top: 1em; } [epub|type~="epigraph"] cite i{ font-style: italic; } /* End all epigraphs */

  2. Epigraphs are typically set in italics. Exceptions are allowed according to rules for italics.

  3. Epigraphs may sometimes contain quotes from plays and drama. Such quotations use the standard play formatting and this additional CSS to remove italics from personas:

    [epub|type~="epigraph"] [epub|type~="z3998:persona"]{ font-style: normal; }

  4. Epigraphs may sometimes contain headings. Headings have italics removed with the following CSS:

    [epub|type~="epigraph"] h2{ font-style: normal; }

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="ordinal 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="ordinal 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. In addition to the CSS used for all epigraphs, this additional CSS is included for epigraphs in section headers:

    /* Epigraphs in section headers */ article > header [epub|type~="epigraph"], section > header [epub|type~="epigraph"]{ display: inline-block; margin: auto; max-width: 80%; text-align: initial; } article > header [epub|type~="epigraph"] + *, section > header [epub|type~="epigraph"] + *{ margin-top: 3em; } @supports(display: table){ article > header [epub|type~="epigraph"], section > header [epub|type~="epigraph"]{ display: table; } } /* End epigraphs in section headers */

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. Full-page epigraphs that contain multiple quotations are represented by multiple <blockquote> elements.

  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: initial; } @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. 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>

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: initial; text-indent: 0; } [epub|type~="z3998:poem"] p + p{ margin-top: 1em; }

  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; padding-left: 1em; text-indent: -1em; }

  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. 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{ padding-left: 2em; text-indent: -1em; } p span.i2{ padding-left: 3em; text-indent: -1em; }

  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. The parent element of poetry, verse, or song, has the semantic inflection of z3998:poem, z3998:verse, z3998:song, or z3998:hymn.

    1. The z3998 vocabulary does not explicitly define their terms for each of the above; these are the standards for our productions.

      1. z3998:poem is used when an entire poem is quoted, even a short one.

      2. z3998:verse is used for poem or verse fragments.

      3. z3998:song is used when song lyrics are quoted, in whole or in part.

      4. z3998:hymn is used when the song lyrics are for a hymn, either well known (e.g. “Amazing Grace”) or specifically labeled as such in the source text. When in doubt, use z3998:song.

  7. If a poem is quoted and has one or more lines removed, the removed lines are represented with a vertical ellipsis (⋮ 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>

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: initial; text-indent: 0; } [epub|type~="z3998:poem"] p > span{ display: block; padding-left: 1em; text-indent: -1em; } [epub|type~="z3998:poem"] p > span + br{ display: none; } [epub|type~="z3998:poem"] p + p{ margin-top: 1em; } p span.i1{ padding-left: 2em; text-indent: -1em; } p span.i2{ padding-left: 3em; text-indent: -1em; }
<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. Each <tr> is either a block of dialog or a standalone stage direction.

  3. Personas are typically characters that have speaking roles. They are set in small caps and never in italics, even if the surrounding text is in italics.

  4. Works that are plays or that contain sections of dramatic dialog have this core CSS:

    [epub|type~="z3998:drama"] table, table[epub|type~="z3998:drama"]{ border-collapse: collapse; margin: 1em auto; width: 100%; } [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{ padding: .5em; vertical-align: top; } [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; -epub-hyphens: none; text-align: right; width: 20%; } [epub|type~="z3998:stage-direction"]{ font-style: italic; } [epub|type~="z3998:stage-direction"] [epub|type~="z3998:persona"], em [epub|type~="z3998:persona"], i [epub|type~="z3998:persona"]{ font-style: normal; } [epub|type~="z3998:stage-direction"]::before{ content: "("; font-style: normal; } [epub|type~="z3998:stage-direction"]::after{ content: ")"; font-style: normal; } [epub|type~="z3998:persona"]{ font-variant: all-small-caps; } section[epub|type~="z3998:scene"] > p{ margin: 1em auto; width: 75%; }

Dialog rows

  1. The first child of a row of dialog is a <td> element with the semantic inflection of z3998:persona.

  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>

    1. Dialog rows that have dialog broken over several lines, i.e. in dialog in verse form, have semantics, structure, and CSS for verse. The <td> element has the z3998:verse semantic.

      <tr> <td epub:type="z3998:persona">Queen Isabel</td> <td epub:type="z3998:verse"> <p> <span>Our gracious brother, I will go with them.</span> <br/> <span>Haply a woman’s voice may do some good,</span> <br/> <span>When articles too nicely urg’d be stood on.</span> </p> </td> </tr>

  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{ break-inside: avoid; } 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>

Stage direction

  1. Stage direction is wrapped in an <i epub:type="z3998:stage-direction"> element.

    1. Stage directions that are included from a different edition additionally have the class="editorial" attribute, with this additional CSS:

      [epub|type~="z3998:stage-direction"].editorial::before{ content: "["; } [epub|type~="z3998:stage-direction"].editorial::after{ content: "]"; }

  2. Personas mentioned in stage direction are wrapped in a <b epub:type="z3998:persona"> element.

    1. Possessive ’s or ’ are included within the associated <b> element.

      <i epub:type="z3998:stage-direction">Lowering his voice for <b epub:type="z3998:persona">Maury’s</b> ear alone.</i>

  3. Stage direction in shorthand (for example, Large French window, R. 3 E.) is wrapped in an <abbr epub:type="z3998:stage-direction"> element, with this additional CSS:

    abbr[epub|type~="z3998:stage-direction"]{ font-style: normal; font-variant: all-small-caps; } abbr[epub|type~="z3998:stage-direction"]::before, abbr[epub|type~="z3998:stage-direction"]::after{ content: ''; }

Stage direction rows

  1. The first child of a row containing only stage direction is an empty <td> element.

  2. The second child of a row containing only stage direction is a <td> element containing the stage direction.

Examples
<tr> <td/> <td> <i epub:type="z3998:stage-direction">Large French window, <abbr class="eoc" epub:type="z3998:stage-direction">R. 3 E.</abbr> <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>

Inline stage direction

  1. Inline stage direction that is not an interjection within a containing clause begins with a capital letter and ends in punctuation, usually a period.

  2. Inline stage direction that is an interjection within a containing clause does not begin with a capital letter, and ending punctuation is optional and usually omitted.

Examples
<tr> <td epub:type="z3998:persona">Jackson</td> <td>I see you don’t know much! A costume <i epub:type="z3998:stage-direction">putting his finger on his forehead</i> is a thing which calls for deep thought. Have you seen my Sun here? <i epub:type="z3998:stage-direction">Strikes his posterior.</i> I looked for it two years.</td> </tr>

Works that are complete plays

  1. The top-level element (usually <body>) has the z3998:drama semantic inflection.

  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. 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><span epub:type="label">Act</span> <span epub:type="ordinal 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. Dramatis personae are presented as a <ul> element listing the characters.

    [epub|type~="z3998:dramatis-personae"]{ text-align: center; } [epub|type~="z3998:dramatis-personae"] p{ text-indent: 0; } [epub|type~="z3998:dramatis-personae"] ul{ list-style: none; margin: 0; padding: 0; } [epub|type~="z3998:dramatis-personae"] ul li{ font-style: italic; margin: 1em; } [epub|type~="z3998:dramatis-personae"] ul + p{ margin-top: 2em; }
    <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>

Letters

Letters require particular attention to styling and semantic inflection. 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.

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. If there is only a salutation and no other header content, the <header> element is omitted.

  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. The salutation (for example, “Dear Sir” or “My dearest Jane”) has the semantic inflection of z3998:salutation.

  5. The first line of a letter after the salutation is not indented.

  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. The name of the recipient of the letter, when set out other than within a salutation (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.

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. The <footer> element has the following CSS:

    footer{ margin-top: 1em; text-align: right; }

  3. The valediction (for example, “Yours Truly” or “With best regards”) has the semantic inflection of z3998:valediction.

  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 z3998:signature semantic inflection and corresponding CSS.

    [epub|type~="z3998:signature"]{ font-variant: small-caps; }
    <footer> <p epub:type="z3998:sender z3998:signature"><abbr epub:type="z3998:given-name">R. A.</abbr> Johnson</p> </footer>
    <footer> <p epub:type="z3998:sender"><span epub:type="z3998:signature">John Doe</span>, President</p> </footer>

  5. Postscripts have the semantic inflection of z3998:postscript and the following CSS:

    [epub|type~="z3998:postscript"]{ margin-top: 1em; text-align: initial; text-indent: 0; }

    1. Postscripts that contain multiple paragraphs are grouped by having their contents wrapped in <div epub:type="z3998:postscript">.

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"], [epub|type~="z3998:signature"]{ font-variant: small-caps; } [epub|type~="z3998:postscript"]{ margin-top: 1em; text-align: initial; text-indent: 0; }
<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 epub:type="z3998:sender z3998:signature">Mabel</p> <p epub:type="z3998:postscript"><abbr epub:type="z3998:initialism">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, <abbr>etc.</abbr></p> <p epub:type="z3998:sender z3998:signature">Edward Gardner</p> </footer> </blockquote>

Images

  1. Each image has a unique id attribute.

    1. That attribute's name is illustration- followed by -N, where N is the sequence number of the element starting at 1.

    2. If the image is inline with the text, the id attribute is on the <img> element.

      <img alt="..." src="..." id="illustration-1" />

    3. When contained in a <figure> element, the <img> element does not have an id attribute; instead the <figure> element has the id attribute.

      <figure id="illustration-3"> <img alt="..." src="..." />

  2. <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="..." />

      1. The alt attribute does not contain no-break spaces or word joiners.

    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. The alt attribute is not necessarily the same as text in the image’s sibling <figcaption> element, if one is present.

  3. <img> elements have semantic inflection denoting the type of image. Common values are z3998:illustration or z3998:photograph.

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

    1. If such an image is drawn in a “realistic” style (i.e., like a Gustave Doré or John Tenniel woodcut, and not like a flat map in an Agatha Christie murder mystery), it has the additional semantic of se:image.style.realistic.

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

    2. All figure elements, regardless of positioning, have this CSS:

      figure{ break-inside: avoid; } figure img{ display: block; margin: auto; max-width: 100%; } figcaption{ font-size: .75em; font-style: italic; margin: 1em; } figcaption p + p{ text-indent: 0; }

    3. <figure> elements that are meant to be displayed as full-page images have the full-page class and this additional CSS:

      figure.full-page{ break-after: page; break-before: page; margin: 0; max-height: 100vh; text-align: center; } @supports(display: flex){ figure.full-page{ display: flex; flex-direction: column; } figure.full-page img{ height: 100vh; object-fit: contain; } }

    4. <figure> elements that are meant to be aligned block-level with the text have this additional CSS:

      figure{ margin: 1em auto; text-align: center; }

Examples

/* If the image is meant to be on its own page, use this selector... */ figure.full-page{ break-after: page; break-before: page; break-inside: avoid; margin: 0; max-height: 100vh; text-align: center; } @supports(display: flex){ figure.full-page{ display: flex; flex-direction: column; } figure.full-page img{ height: 100vh; object-fit: contain; } } /* If the image is meant to be aligned block-level with the text, use this selector... */ figure{ break-inside: avoid; margin: 1em auto; text-align: center; } /* In all cases, also include the below styles */ figure{ break-inside: avoid; } figure img{ display: block; margin: auto; max-width: 100%; } figcaption{ font-size: .75em; font-style: italic; margin: 1em; } figcaption p + p{ text-indent: 0; }
<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 named ./src/epub/text/loi.xhtml.

  2. The LoI file has the backmatter semantic inflection.

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

  4. The LoI file contains a single <nav id="loi" epub:type="loi"> element, which in turn contains an <h2 epub:type="title">List of Illustrations</h2> element, followed by an <ol> element, which in turn contains list items representing the images.

  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. Links to the images go directly to the image’s corresponding id hashes, not just the top of the containing file.

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: https://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"> <nav id="loi" epub:type="loi"> <h2 epub:type="title">List of Illustrations</h2> <ol> <li> <p> <a href="preface.xhtml#the-edge-of-the-world">The Edge of the World</a> </p> </li> ... </ol> </nav> </body> </html>

Endnotes

  1. Ebooks do not have footnotes, only endnotes. Footnotes are instead converted to endnotes.

  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.

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> element with the semantic inflection noteref.

    1. Noterefs point directly to the corresponding endnote <li> element in the endnotes file.

    2. Noterefs have an id attribute like noteref-n, where n is identical to the endnote number.

    3. The text of the noteref is the endnote number.

  2. If located at the end of a sentence, noterefs are placed after ending punctuation.

  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.

The endnotes file

  1. Endnotes are in an XHTML file named ./src/epub/text/endnotes.xhtml.

  2. The endnotes file has the backmatter semantic inflection.

  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. Each endnote’s id attribute is in sequential ascending order.

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. 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. 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. Endnotes with ending citations have those citations wrapped in a <cite> element, including any em dashes. A space follows the <cite> element, before the backlink.

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: https://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 epub:type="z3998:given-name">G.</abbr> Volkens, “Uber die Karolinen Insel Yap.” <cite>—<abbr class="eoc" epub:type="z3998:personal-name">W. T. G.</abbr></cite> <a href="chapter-2.xhtml#noteref-1" epub:type="backlink">↩</a></p> </li> <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>

Glossaries

Glossaries may be included if there are a large number of domain-specific terms that are unlikely to be in a common dictionary, or which have unique meanings to the work.

Glossaries follow the EPUB Dictionaries and Glossaries 1.0 spec.

The glossary search key map file

When including a glossary, a search key map file is required according to the EPUB Dictionaries and Glossaries 1.0 spec.

  1. The search key map file is named ./src/epub/glossary-search-key-map.xml.

  2. The search key map file contains <value> elements describing all stemmed variations of the parent search term that occur in the ebook. Variations that don't occur in the ebook are excluded.

  3. If a <match> element only has one <value> element, the <value> element is removed in favor of <match value="...">.

The glossary file

  1. Glossaries are in an XHTML file named ./src/epub/text/glossary.xhtml.

  2. The glossary file has the backmatter semantic inflection.

  3. The glossary file contains a single <section id="glossary" epub:type="glossary"> element, which may contain a title, followed by a <dl> element containing the glossary entries. While the EPUB glossaries spec suggests the glossary epub:type attribute be placed on the <dl> element, in a Standard Ebook it is placed on the <dl> element’s parent <section> element.

  4. All glossaries include the following CSS:

    dd + dt{ margin-top: 1em; }

Glossary entries

  1. The <dl> element contains sets of <dt> and <dd> elements.

  2. The <dt> element has epub:type="glossterm".

  3. The <dt> element contains a single <dfn> element, which in turn contains the term to be defined.

  4. The <dd> element has epub:type="glossdef".

  5. A <dd> element appears after one or more <dt> elements, and contains the definition for the preceding <dt> element(s). It must contain at least one block-level child, usually <p>.

    <dt epub:type="glossterm"> <dfn>Coccus</dfn> </dt> <dd epub:type="glossdef"> <p>The genus of Insects including the Cochineal. In these the male is a minute, winged fly, and the female generally a motionless, berrylike mass.</p> </dd>

  6. <dt> may appear more than once for a single glossary entry, if different variations of a term have the same definition.

    <dt epub:type="glossterm"> <dfn>Compositae</dfn> </dt> <dt epub:type="glossterm"> <dfn>Compositous Plants</dfn> </dt> <dd epub:type="glossdef"> <p>Plants in which the inflorescence consists of numerous small flowers (florets) brought together into a dense head, the base of which is enclosed by a common envelope. (Examples, the Daisy, Dandelion, <abbr class="eoc">etc.</abbr>)</p> </dd>

Typography

Section titles and ordinals

  1. Section ordinals in the body text are set in Roman numerals.

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

  3. Section titles do not have trailing periods.

  4. 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, wrapped in <span epub:type="label">.

    <h2>Chapter <span epub:type="ordinal z3998:roman">II</span></h2>
    <h2 epub:type="ordinal z3998:roman">II</h2>
    <h2> <span epub:type="label">Stave</span> <span epub:type="ordinal z3998:roman">III</span> </h2>

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

Italics

  1. Using both italics and quotes (outside of the context of quoted dialog) is usually not necessary. Either one or the other is used, with rare exceptions.

  2. Words and phrases that require emphasis are italicized with the <em> element.

    <p>“Perhaps <em>he</em> was there,” Raoul said, at last.</p>

  3. Strong emphasis, like shouting, may be set in small caps with the <strong> element.

    <p>“<strong>Can’t</strong> I?” screamed the unhappy creature to himself.</p>

  4. When a short phrase within a longer clause is italicized, trailing punctuation that may belong to the containing clause is not italicized.

    <p>“Look at <em>that!</em>” she shouted.</p>
    <p>“Look at <em>that</em>!” she shouted.</p>

  5. When an entire clause is italicized, trailing punctuation is italicized, unless that trailing punctuation is a comma at the end of dialog.

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

  6. Words written to be read as sounds are italicized with <i>.

    <p>He could hear the dog barking: <i>Ruff, ruff, ruff!</i></p>

  7. A person's internal thoughts, if they are italicized in the source, are formatted with <q>, styled with italics. If the thoughts are quoted, they are left as quoted.

    q{ font-style: italic; }
    <p>The thought flashed to me: <q>it’s a city you’re firing at, not a plane</q>, and I flinched.</p>

Italicizing individual letters

  1. Individual letters that are used in context as a phoneme are italicized with an <i epub:type="z3998:phoneme"> element. They are sentence-cased and not followed by periods.

    <p>“<i xml:lang="ru-Latn">Mamochka</i>, let’s play <i xml:lang="ru-Latn">priatki</i>,” (hide and seek), cried Lelechka, pronouncing the <i epub:type="z3998:phoneme">r</i> like the <i epub:type="z3998:phoneme">l</i>, so that the word sounded “pliatki.”</p>

    1. Plural phonemes are formed with ’s, to aid in clarity.

      <p>Her <i epub:type="z3998:phoneme">a</i>s were nasally.</p>
      <p>Her <i epub:type="z3998:phoneme">a</i>’s were nasally.</p>

  2. Graphemes are italicized with an <i epub:type="z3998:grapheme"> element.

    <p>“It’s such a pity,” she would say pensively, “that July hasn’t got an <i epub:type="z3998:grapheme">r</i> in it.</p>

    1. When a word is being spelled out, the individual letters of the word are set as graphemes.

      <p>I rattled off, “<i epub:type="z3998:grapheme">t</i>-<i epub:type="z3998:grapheme">h</i>-<i epub:type="z3998:grapheme">i</i>-<i epub:type="z3998:grapheme">r</i>-<i epub:type="z3998:grapheme">d</i>, third.”</p>

  3. Individual letters that are not graphemes or phonemes (for example letters that might be referring to names, the shapes of the letters themselves, musical notes or keys, or concepts) are not italicized.

    <p>...due to the loss of what is known in New England as the “L”: that long deep roofed adjunct usually built at right angles to the main house...</p>
    <p>She was learning her A.B.C.s.</p>
    <p>His trident had the shape of an E.</p>
    <p>The piece was in the key of C major.</p>

  4. The ordinal nth is set with an italicized n, without a hyphen.

    <p>The <i>n</i>th degree.</p>

Italicizing non-English words and phrases

  1. Non-English words and phrases that are not in Merriam-Webster are italicized, unless they are in a non-Roman script like Chinese or Japanese.

    <p>The <i xml:lang="fr">corps de ballet</i> was flung into consternation.</p>

  2. Non-English words that are proper names, or are in proper names, are not italicized, unless the name itself would be italicized according to the rules for italicizing or quoting names and titles. If words in the name might be mispronounced in English pronunciation, they are wrapped in a <span xml:lang="LANGUAGE"> element to assist screen readers with pronunciation. Most proper names of people or places do not require this, but occasionally there may be some that do.

    <p>“<i xml:lang="fr">Où est le métro?</i>” he asked, and she pointed to <i xml:lang="fr">Place de Clichy</i>, next to the <i xml:lang="fr">Le Bon Petit Déjeuner</i> restaurant.</p>
    <p>“<i xml:lang="fr">Où est le métro?</i>” he asked, and she pointed to <span xml:lang="fr">Place de Clichy</span>, next to the <span xml:lang="fr">Le Bon Petit Déjeuner</span> restaurant.

  3. If certain non-English words are used so frequently in the text that italicizing them at each instance would be distracting to the reader, then only the first instance is italicized. Subsequent instances are wrapped in a <span xml:lang="LANGUAGE"> element.

  4. Words and phrases that are originally non-English in origin, but that can now be found in Merriam-Webster’s basic online search results, are not italicized. “Basic online search results” means that results from other dictionaries that may appear alongside basic search results, including results from the unabridged or legal dictionaries, do not fall under this rule and may still be obscure enough to be italicized.

    <p>Sir Percy’s bon mot had gone the round of the brilliant reception-rooms.</p>

  5. Inline-level italics are set using the <i> element with an xml:lang attribute corresponding to the correct IETF language tag.

  6. Block-level italics are set using an xml:lang attribute on the closest encompassing block element, with the style of font-style: italic.

    In this example, note the additional namespace declaration, and that we target only <blockquote> elements that have the language tag. This is because there can be other elements, e.g. <span>, that have a language tag but should not be italicized.

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

  7. Words that are in a non-English “alien” language (i.e. one that is made up, like in a science fiction or fantasy work) are italicized and given an IETF languate tag in a custom namespace. Custom namespaces begin consist of x-TAG, where TAG is a custom descriptor of 8 characters or less.

    <p>“<i xml:lang="x-arcturan">Dolm</i>,” said Haunte.</p>

  8. Words that are in an unknown language have their xml:lang attribute set to und.

  9. Some phrases that are not English in origin but that that are common in English prose, and which begin in a word that could be confused with an English word, are always italicized to prevent confusion. An incomplete list follows:

    • sic

    • a posteriori

    • a priori

    • a fortiori

    • ad absurdum

    • ad hominem

    • ad infinitum

    • ad interim

    • ad nauseam

    • in absentia

    • in camera

    • in loco parentis

    • in situ

    • in statu quo

    • in toto

    • in vitro

    • more suo

Italicizing or quoting newly-used English words

  1. When introducing new terms, non-English or technical terms are italicized, but terms composed of common English are set in quotation marks.

    <p>English whalers have given this the name “ice blink.”</p> <p>The soil consisted of that igneous gravel called <i>tuff</i>.</p>

  2. English neologisms in works where a special vocabulary is a regular part of the narrative are not italicized. For example science fiction works may necessarily contain made-up English technology words, and those are not italicized.

Italics in names and titles

  1. Place names, like pubs, bars, or buildings, are not quoted.

  2. The names of publications, music, and art that can stand alone are italicized; additionally, the names of transport vessels are italicized. These include, but are not limited to:

    • Periodicals like magazines, newspapers, and journals.

    • Publications like books, novels, plays, and pamphlets, except “holy texts,” like the Bible or books within the Bible.

    • Long poems and ballads, like the Iliad, that are book-length.

    • Long musical compositions or audio, like operas, music albums, or radio shows.

    • Long visual art, like films or a TV show series.

    • Visual art, like paintings or sculptures.

    • Transport vessels, like ships.

  3. The names of short publications, music, or art, that cannot stand alone and are typically part of a larger collection or work, are quoted. These include, but are not limited to:

    • Short musical compositions or audio, like pop songs, arias, or an episode in a radio series.

    • Short prose like novellas, short stories, or short (i.e. not epic) poems.

    • Chapter titles in a prose work.

    • Essays or individual articles in a newspaper or journal.

    • Short visual art, like short films or episodes in a TV series.

Examples

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

Taxonomy

  1. Binomial names (generic, specific, and subspecific) are italicized with a <i> element having the z3998:taxonomy semantic inflection.

    <p>A bonobo monkey is <i epub:type="z3998:taxonomy">Pan paniscus</i>.</p>

  2. Family, order, class, phylum or division, and kingdom names are capitalized but not italicized.

    <p>A bonobo monkey is in the phylum Chordata, class Mammalia, order Primates.</p>

  3. If a taxonomic name is the same as the common name, it is not italicized.

  4. The second part of the binomial name follows the capitalization style of the source text. Modern usage requires lowercase, but older texts may set it in uppercase.

Exceptions

  1. Epigraphs, bridgeheads, and some other types of heading matter are set in italics by default. Text that in a Roman-set context would be italicized (like non-English words or phrases, or titles of books) are thus set in Roman in that heading matter, to contrast against the default italics. However, if due to this rule the entire block would be set in Roman instead of italics, thus lending the block an unexpected appearance, then the contrasting Roman is discarded and the default italics are preserved.

    [epub|type~="epigraph"]{ font-style: italic; /* ... */ } [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; }
    <blockquote epub:type="epigraph"> <p>“<i xml:lang="fr">En administration, toutes les sottises sont mères.</i>”</p> <cite><i epub:type="se:name.publication.book">Maximes</i>, <i xml:lang="la">fr</i> <abbr epub:type="z3998:given-name">M. G.</abbr> De Levis.</cite> </blockquote>
    [epub|type~="epigraph"]{ font-style: italic; /* ... */ } [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; }
    <blockquote epub:type="epigraph"> <p xml:lang="fr">“En administration, toutes les sottises sont mères.”</p> <cite><i epub:type="se:name.publication.book">Maximes</i>, <i xml:lang="la">fr</i> <abbr epub:type="z3998:given-name">M. G.</abbr> De Levis.</cite> </blockquote>

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

  3. 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>
    <p>The sign read <b>Bob’s Restaurant</b>.</p>
    <p>“<strong>Charge!</strong>” he cried.</p>

  4. When something is addressed as an apostrophe, O is capitalized.

    <p>I carried the bodies into the sea, O walker in the sea!</p>

  5. Names followed by a generational suffix, like Junior or Senior, have the suffix uppercased if the suffix is part of the person's name.

    Occasionally, junior or senior may be used to refer to a younger or elder person having the same last name, but not necessarily the same first name. In these cases, the suffix is lowercased as it is not part of their name, but rather describing their generational relation.

    <p>He talked to Bob Smith Junior.</p> <p>He talked to John Doe <abbr class="eoc">Jr.</abbr></p> <p>Madame Bovary junior was afraid of accidents for her husband.</p>

Indentation

  1. Paragraphs that directly follow another paragraph are indented by 1em.

  2. The first line of body text in a section, or any text following a visible break in text flow (like a header, a scene break, a figurem etc.), is not indented, with the exception of block quotations.

    1. Body text following a block quotation is indented only if the text begins a new semantic paragraph. Otherwise, if the body text following a block quotation is semantically part of the paragraph preceding the block quotation, it is not indented. Such non-indented paragraphs have class="continued", which removes the default indentation.

      <p>He sat down before a writing-table and, taking pen and ink, wrote on a slip of paper as follows:⁠—</p> <blockquote epub:type="z3998:letter"> <p>The Bishop of Barchester is dead.</p> </blockquote> <p>“There,” said he. “Just take that to the telegraph office at the railway station and give it in as it is.”</p>
      <p>He opened the cover in which the message was enclosed and, having read it, he took his pen and wrote on the back of it⁠—</p> <blockquote epub:type="z3998:letter"> <p epub:type="z3998:salutation">For the Earl of ⸻,</p> <footer> <p epub:type="z3998:valediction">With the Earl of ⸻’s compliments</p> </footer> </blockquote> <p class="continued">and sent it off again on its journey.</p>

Headers

  1. Titles or subtitles that are entirely non-English-language are not italicized. However, they do have an xml:lang attribute to assist screen readers in pronunciation. Titles or subtitles that are in English but contain non-English components have those components italicized according to the general rules for italics.

    <h2 epub:type="title" xml:lang="la">Ex Oblivione</h2> <hgroup> <h2 epub:type="ordinal z3998:roman">XI</h2> <h3 epub:type="title">The <i epub:type="se:name.vessel.ship">Nautilus</i></h3> </hgroup> <hgroup> <h2 epub:type="ordinal z3998:roman">XXXV</h2> <h3 epub:type="title">Miss Thorne’s <i xml:lang="fr">Fête Champêtre</i></h3> </hgroup> <hgroup> <h2 epub:type="ordinal z3998:roman">XI</h2> <h3 epub:type="title" xml:lang="la">Christus Nos Liberavit</h3> </hgroup>

Chapter headers

  1. Epigraphs in chapters have the quote source set in small caps, without a leading em dash and without a trailing period.

    <header> <h2 epub:type="ordinal 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="ordinal z3998:roman">II</h2> <blockquote epub:type="epigraph"> <p>“Desire no more than to thy lot may fall. …”</p> <cite>Chaucer</cite> </blockquote> </header>

Ligatures

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

Words in non-English languages like French may use ligatures to differentiate words or pronunciations. In these cases, ligatures are retained.

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

Punctuation and spacing

  1. Sentences are single-spaced.

  2. Periods and commas are placed within quotation marks; i.e. American-style punctuation is used, not logical (AKA “British” or “new”) style.

    <p>Bosinney ventured: “It’s the first spring day”.</p>
    <p>Bosinney ventured: “It’s the first spring day.”</p>

  3. Ampersands are preceded by a no-break space (U+00A0).

    <p>The firm of Hawkinsnbsp&amp; Harker.</p>

  4. Some older works include spaces in common contractions; these spaces are removed.

    <p>Would n’t it be nice to go out? It ’s such a nice day.</p>
    <p>Wouldn’t it be nice to go out? It’s such a nice day.</p>

Quotation marks

  1. “Curly” or typographer’s quotes, both single and double, are always used instead of straight quotes. This is known as “American-style” quotation, which is different from British-style quotation which is also commonly found in both older and modern books.

    <p>“Don’t do it!” she shouted.</p>

  2. Quotation marks that are directly side-by-side are separated by a hair space ( or U+200A) character.

    <p>“hairsp‘Green?’ Is that what you said?” asked Dave.</p>

  3. Words with missing letters represent the missing letters with a right single quotation mark (’ or U+2019) character to indicate elision.

    <p>He had pork ’n’ beans for dinner</p>

    1. Elision is not to be confused with a glottal stop, which may sometimes occur in non-English languages like Hawaiian. Glottal stops that are not elided letters are represented with a turned comma (ʻ or U+02BB), not the similar-looking left single quotation mark (‘ or U+2018).

      <p><i xml:lang="haw">ʻŌlelo Hawaiʻi</i></p>

    2. Rarely, in older texts some commonly-recongizable last names were rendered using a left single quotation mark (‘ or U+2018) instead of a superscript c. This is a matter of typography and not actual spelling, and is to the expected modern spelling of the last name.

      <p>His friends were James M‘Donald and Sam M‘Daniel.</p>
      <p>His friends were James McDonald and Sam McDaniel.</p>

  4. Ditto marks are set with the right double quotation mark glyph (” or U+201D), This is not to be confused with the ditto mark glyph (〃 or U+3003), which is for non-Latin scripts only, or the quotation mark glyph (" or U+0022).

    <table> <tbody> <tr> <td>3</td> <td>lbs.</td> </tr> <tr> <td>12</td> <td>”</td> </tr> </tbody> </table>

  5. Some idiomatic phrases are not set with scare quotes:

    • ... to a T.

Ellipses

  1. The ellipsis glyph (… or U+2026) is used for ellipses, instead of consecutive or spaced periods.

  2. When ellipses are used as suspension points (for example, to indicate dialog that pauses or trails off), the ellipses are not preceded by a comma.

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

  3. A word joiner (U+2060), followed by a hair space ( or U+200A) glyph, followed by another word joiner (U+2060), are located before all ellipses that do not begin a paragraph, and that are not directly preceded by “.

  4. A regular space is located after all ellipses that do not end a paragraph and that are not followed by punctuation.

  5. A hair space ( or U+200A) glyph is located between an ellipsis and any punctuation that follows directly after the ellipsis, unless that punctuation is a quotation mark, in which case there is no space at all between the ellipsis and the quotation mark.

    <p>“I’m so hungrywjhairspwj…hairsp! What were you saying about eatingwjhairspwj…?”

Dashes

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

  1. Dashes of all types do not have white space around them.

  2. Figure dashes (‒ or U+2012) are used to indicate a dash in numbers that aren’t a range, like phone numbers.

    <p>His number is 555‒1234.</p>

  3. Hyphens (- or U+002D) are used to join words, including double-barrel names, or to separate syllables in a word.

    <p>Pre- and post-natal.</p>
    <p>The Smoot-Hawley act.</p>

  4. Minus sign glyphs (− or U+2212) are used to indicate negative numbers, and are used in mathematical equations instead of hyphens to represent the “subtraction” operator.

    <p>It was −5° out yesterday!</p>
    <p>5 − 2 = 3</p>

  5. En dashes (– or U+2013) are used to indicate a numeric or date range; to indicate a relationships where two concepts are connected by the word “to,” for example a distance between locations or a range between numbers; or to indicate a connection in location between two places. En dashes are preceded and followed by the invisible word joiner glyph (U+2060).

    <p>We talked 2wj–wj3 days ago.</p>
    <p>We took the Berlinwj–wjMunich train yesterday.</p>
    <p>I saw the torpedo-boat in the Ems⁠wj–wj⁠Jade Canal.</p>

  6. Non-break hyphens (‑ or U+2011) are used when a single word is stretched out by a speaker for prosodic effect.

    <p>When you wa‑ake, you shall ha‑ave, all the pretty little hawsiz—</p>

Em dashes

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

  1. Em dashes are preceded by the invisible word joiner glyph (U+2060).

  2. Interruption in dialog is set by a single em dash, not two em dashes or a two-em dash.

    <p>“I wouldn’t go as far as that, not myself, butwj——”</p>
    <p>“I wouldn’t go as far as that, not myself, butwj—”</p>

Partially-obscured words

A partially-obscured word is a word that the author chooses to not divulge by consistently obscuring some or all of it. This is not the same as an interruption in dialog, which may interrupt a word, but not obscure it in the same stylistic sense.

  1. Em dashes are used for partially-obscured years and totally-obscured days of the month.

    <p>It was the year 19wj— in the town of Metropolis.</p> <p>She arrived on May —, 1922.</p>

  2. A regular hyphen is used in partially-obscured years where only the last number is obscured, and in partially-obscured days of the month.

    <p>It was the year 192- in the town of Metropolis.</p> <p>His birthday was August 1-, 1911.</p>

  3. A non-breaking hyphen (‑ or U+2011) is used when a single letter is obscured in a word.

    <p>He performed Mozart’s famous canon, “Leck mich im A‑sche.”</p>

  4. A two-em dash (⸺ or U+2E3A) preceded by a word joiner glyph (U+2060) is used in partially obscured words.

    <p>Sally Jwj⸺ walked through town.</p>

    1. If both the start and end of a partially-obscured word are visible, a word joiner is placed on both sides of the two-em-dash.

      <p>A blwj⸺wjy murder!</p>

  5. A three-em dash (⸻ or U+2E3B) is used for completely obscured words.

    <p>It was night in the town of ⸻.</p>

Numbers, measurements, and math

  1. Coordinates are set with the prime (′ or U+2032) or double prime (″ or U+2033) glyphs, not single or double quotes.

    <p><abbr>Lat.</abbr> 27° 0' <abbr epub:type="se:compass">N.</abbr>, <abbr>long.</abbr> 20° 1' <abbr class="eoc" epub:type="se:compass">W.</abbr></p> <p><abbr>Lat.</abbr> 27° 0’ <abbr epub:type="se:compass">N.</abbr>, <abbr>long.</abbr> 20° 1’ <abbr class="eoc" epub:type="se:compass">W.</abbr></p>
    <p><abbr>Lat.</abbr> 27° 0′ <abbr epub:type="se:compass">N.</abbr>, <abbr>long.</abbr> 20° 1′ <abbr class="eoc" epub:type="se:compass">W.</abbr></p>

  2. Ordinals for Arabic numbers are as follows: st, nd, rd, th.

    <p>The 1st, 2d, 3d, 4th.</p>
    <p>The 1st, 2nd, 3rd, 4th.</p>

  3. Numbers in a non-mathematical context are spelled out in the following cases:

    • If they are from 0–100.

    • If they are whole numbers from 0–100 and are made greater by being paired with words like hundred, thousand, million, and so on.

    • If they begin a sentence.

    • If they are simple fractions.

    <p>“They had a gun on the West Front⁠—a seventy-five,” said O’Keefe.</p> <p>Allowing her twelve thousand miles of straight-line travel through Uranus’ frigid soupy atmosphere.</p> <p>He died in the year 619.</p> <p>The vote needed two-thirds majority.</p> <p>The army consisted of 113,000 soldiers.</p> <p>He reached out of the unlived depths of nineteen hundred years.</p>

    1. If a series of numbers is close together in a sentence, and one would be spelled out but another wouldn’t, spell out all numbers within that context to maintain visual consistency.

      <p>There the Gulf Stream is 75 miles wide and two hundred ten meters deep.</p>
      <p>There the Gulf Stream is seventy-five miles wide and two hundred ten meters deep.</p>

    2. The plural form of spelled-out numbers is formed without an apostrophe. However the possessive or contracted form does include an apostrophe.

      <p>There were, the other answered, half a dozen two four two’s.</p>
      <p>There were, the other answered, half a dozen two four twos.</p> <p>Twice two’s four, and a stone’s a stone.</p> <p>He was allowed a day or two’s shooting in September.</p>

  4. Numbers of four or more digits should include commas at every 3rd decimal place.

    <p>“You will agree to do me service for the sum of 4000 guilders?”</p>
    <p>“You will agree to do me service for the sum of 4,000 guilders?”</p>

Roman numerals

  1. Roman numerals are set using uppercase ASCII, not the Unicode Roman numeral glyphs.

  2. Roman numerals have the semantic inflection of z3998:roman.

  3. Roman numerals are not followed by trailing periods, except for grammatical reasons.

  4. Roman numerals are not followed by ordinal indicators.

    <p>Henry <span epub:type="z3998:roman">VIII</span>th had six wives.</p>
    <p>Henry <span epub:type="z3998:roman">VIII</span> had six wives.</p>

Fractions

  1. Fractions are set in their appropriate Unicode glyph, if a glyph available; for example, ½, ¼, ¾ and U+00BC–U+00BE and U+2150–U+2189.

    <p>I need 1/4 cup of sugar.</p>
    <p>I need ¼ cup of sugar.</p>

  2. If a fraction doesn’t have a corresponding Unicode glyph, it is composed using the fraction slash Unicode glyph (⁄ or U+2044) and superscript/subscript Unicode numbers. See this Wikipedia entry for more details.

    <p>Roughly 6/10 of a mile.</p>
    <p>Roughly ⁶⁄₁₀ of a mile.</p>

  3. There is no space between a whole number and its fraction.

    <p>There are 365¼ days in a year.</p>

Measurements

  1. Dimension measurements are set using the Unicode multiplication glyph (× or U+00D7), not the ASCII letter x or X.

    <p>The board was 4 x 3 x 7 feet.</p>
    <p>The board was 4 × 3 × 7 feet.</p>

  2. Feet and inches in shorthand are set using the prime (′ or U+2032) or double prime (″ or U+2033) glyphs (not single or double quotes), with a no-break space (U+00A0) separating consecutive feet and inch measurements.

    <p>He was 6'nbsp1" in height.</p> <p>He was 6’nbsp1” in height.</p>
    <p>He was 6′nbsp1″ in height.</p>

  3. When forming a compound of a number and unit of measurement in which the measurement is abbreviated, the number and unit of measurement are separated with a no-break space (U+00A0), not a dash. For exceptions in money, see 8.8.8.

    <p>A 12-<abbr>mm</abbr> pistol.</p>
    <p>A 12nbsp<abbr>mm</abbr> pistol.</p>

Punctuation in abbreviated measurements

See here for general abbreviation rules that also apply to measurements.

  1. Abbreviated SI units are set in lowercase without periods. They are not initialisms.

    <p>A 12nbsp<abbr>mm</abbr> pistol.</p>

  2. Abbreviated English, Imperial, or US customary units that are one word are set in lowercase with a trailing period. They are not initialisms.

    <p>We had two 9nbsp<abbr>ft.</abbr> sledges, of 41nbsp<abbr>lbs.</abbr> each.</p>

    The one exception is G (i.e. G-force), which is an initialism that is set without a period.

    <p>There’s a force of over a hundred thousand <abbr epub:type="z3998:initialism">G</abbr>’s.</p>

  3. Abbreviated English, Imperial, or US customary units that are more than one word (like hp for horse power or mph for miles per hour) are set in lowercase without periods. They are not initialisms.

    <p>He drove his 40nbsp<abbr>hp</abbr> car at 20nbsp<abbr>mph</abbr>.</p>

Math

  1. In works that are not math-oriented or that don’t have a significant amount of mathematical equations, equations are set using regular HTML and Unicode.

    1. Operators and operands in mathematical equations are separated by a space.

      <p>6−2+2=6</p>
      <p>6 − 2 + 2 = 6</p>

    2. Operators like subtraction (− or U+2212), multiplication (× or U+00D7), and equivalence (≡ or U+2261) are set using their corresponding Unicode glyphs, not a hyphen or x. Almost all mathematical operators have a corresponding special Unicode glyph.

      <p>6 - 2 x 2 == 2</p>
      <p>6 − 2 × 2 ≡ 2</p>

    3. Simple in-line variables are set individually with the <var> tag.

      <p>If the value of the labour = <var>x</var> and the force of demand = <var>y</var>, the exchangeable value of the commodity is <var>x</var><var>y</var></p>

  2. In works that are math-oriented or that have a significant amount of math, all variables, equations, and other mathematical objects are set using MathML.

    1. When MathML is used in a file, the m namespace is declared at the top of the file and used for all subsequent MathML code, as follows:

      xmlns:m="http://www.w3.org/1998/Math/MathML"

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

      <html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" ub:prefix="z3998: http://www.daisy.org/z3998/2012/vocab/structure/, se: https://standardebooks.org/vocab/1.0" xml:lang="en-GB"> ... <p> <math xmlns="http://www.w3.org/1998/Math/MathML" alttext="x"> <ci>x</ci> </math> </p>
      <html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" xmlns:m="http://www.w3.org/1998/Math/MathML" epub:prefix="z3998: http://www.daisy.org/z3998/2012/vocab/structure/, se: https://standardebooks.org/vocab/1.0" xml:lang="en-GB"> ... <p> <m:math alttext="x"> <m:ci>x</m:ci> </m:math> </p>

    2. When possible, Content MathML is used over Presentation MathML. (This may not always be possible depending on the complexity of the work.)

      <p> <m:math alttext="x + 1 = y"> <m:apply> <m:eq/> <m:apply> <m:plus/> <m:ci>x</m:ci> <m:cn>1</m:cn> </m:apply> <m:ci>y</m:ci> </m:apply> </m:math> </p>

    3. Each <m:math> element has an alttext attribute.

      1. The alttext attribute describes the contents in the element in plain-text Unicode according to the rules in this specification.

      2. Operators in the alttext attribute are surrounded by a single space.

        <p> <m:math alttext="x+1=y"> <m:apply> <m:eq/> <m:apply> <m:plus/> <m:ci>x</m:ci> <m:cn>1</m:cn> </m:apply> <m:ci>y</m:ci> </m:apply> </m:math> </p>
        <p> <m:math alttext="x + 1 = y"> <m:apply> <m:eq/> <m:apply> <m:plus/> <m:ci>x</m:ci> <m:cn>1</m:cn> </m:apply> <m:ci>y</m:ci> </m:apply> </m:math> </p>

    4. When using Presentation MathML, <m:mrow> is used to group subexpressions, but only when necessary. Many elements in MathML, like <m:math> and <m:mtd>, imply <m:mrow>, and redundant elements are not desirable. See this section of the MathML spec for more details.

      <p> <m:math alttext="x"> <m:mrow> <m:mi>x</m:mi> </m:mrow> </m:math> </p>
      <p> <m:math alttext="x"> <m:mi>x</m:mi> </m:math> </p>

    5. If a Presentation MathML expression contains a function, the invisible Unicode function application glyph (U+2061) is used as an operator between the function name and its operand. This element looks exactly like the following, including the comment for readability: <m:mo>⁡<!--hidden U+2061 function application--></m:mo>. (Note that the preceding element contains an invisible Unicode character! It can be revealed with the se unicode-names tool.)

      <p> <m:math alttext="f(x)"> <m:mi>f</m:mi> <m:mrow> <m:mo fence="true">(</m:mo> <m:mi>x</m:mi> <m:mo fence="true">)</m:mo> </m:mrow> </m:math> </p>
      <p> <m:math alttext="f(x)"> <m:mi>f</m:mi> <m:mo>⁡U+2061<!--hidden U+2061 function application--></m:mo> <m:mrow> <m:mo fence="true">(</m:mo> <m:mi>x</m:mi> <m:mo fence="true">)</m:mo> </m:mrow> </m:math> </p>

    6. Expressions grouped by parenthesis or brackets are wrapped in an <m:mrow> element, and fence characters are set using the <m:mo fence="true"> element. Separators are set using the <m:mo separator="true"> element. <m:mfenced>, which used to imply both fences and separators, is deprecated in the MathML spec and thus is not used.

      <p> <m:math alttext="f(x,y)"> <m:mi>f</m:mi> <m:mo>⁡U+2061<!--hidden U+2061 function application--></m:mo> <m:mfenced> <m:mi>x</m:mi> <m:mi>y</m:mi> </m:mfenced> </m:math> </p>
      <p> <m:math alttext="f(x,y)"> <m:mi>f</m:mi> <m:mo>⁡U+2061<!--hidden U+2061 function application--></m:mo> <m:mrow> <m:mo fence="true">(</m:mo> <m:mi>x</m:mi> <m:mo separator="true">,</m:mo> <m:mi>x</m:mi> <m:mo fence="true">)</m:mo> </m:mrow> </m:math> </p>

    7. If a MathML variable includes an overline, it is set by combining the variable’s normal Unicode glyph and the Unicode overline glyph, ‾ (U+203E), in a <m:mover> element. However in the alttext attribute, the Unicode combining overline, ◌̅ (U+0305), is used to represent the overline in Unicode.

      <p> <m:math alttext="x̅"> <m:mover> <m:mi>x</m:mi> <m:mo>‾</m:mo> </m:mover> </m:math> </p>

  3. Ratios are expressed with the Unicode ratio character (∶ or U+2236) surrounded by spaces, not a colon. The ratio character is also used for logical comparisons in non-mathematical contexts, like analogies in running prose.

    <p>And so we get four names⁠—two for intellect, and two for opinion⁠—reason or mind, understanding, faith, perception of shadows⁠—which make a proportion⁠—being ∶ becoming ∶∶ intellect ∶ opinion⁠— and science ∶ belief ∶∶ understanding ∶ perception of shadows.

Money

  1. Typographically-correct symbols are used for currency symbols.

    <p>The exchange rate was L2 for $1.</p>
    <p>The exchange rate was £2 for $1.</p>

  2. Currency symbols are not abbreviations.

£sd shorthand

£sd shorthand is a way of denoting pre-decimal currencies (pounds, shillings, and pence) common in England and other parts of the world until the 1970s.

  1. There is no white space between a number and an £sd currency symbol.

    <p>£ 14 8 s. 2 d. is known as a “tuppence.”</p>
    <p>£14 8<abbr>s.</abbr> 2<abbr>d.</abbr> is known as a “tuppence.”</p>

  2. Abbreviated currencies used in £sd shorthand are wrapped in <abbr> elements.

    <p>£14 8s. 2d. is known as a “tuppence.”</p>
    <p>£14 8<abbr>s.</abbr> 2<abbr>d.</abbr> is known as a “tuppence.”</p>

  3. Abbreviated currencies used in £sd shorthand are followed by periods.

Dates

  1. Years with 4 digits are set without commas, but years with 5 digits or more include commas at every 3rd decimal place.

    <p>Tutankhamun ruled till 1,325 <abbr epub:type="se:era">BC</abbr>.</p>
    <p>Tutankhamun ruled till 1325 <abbr epub:type="se:era">BC</abbr>, but ancient aliens built the pyramids in 12,633 <abbr epub:type="se:era">BC</abbr>.</p>

Latinisms

  1. Latinisms (except sic) that can be found in a modern dictionary are not italicized, with some exceptions. Examples include e.g., i.e., ad hoc, viz., ibid., etc..

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

  3. &c. is not used, and is replaced with etc..

  4. For Ibid., see Endnotes.

  5. Latinisms that are abbreviations are set in lowercase with periods between words and no spaces between them, except BC, AD, BCE, and CE, which are set without periods, in small caps, and wrapped with <abbr epub:type="se:era">:

    abbr[epub|type~="se:era"]{ font-variant: all-small-caps; }
    <p>Julius Caesar was born around 100 <abbr epub:type="se:era">BC</abbr>.</p>

Initials and abbreviations

  1. Acronyms (terms made up of initials and pronounced as one word, like NASA, SCUBA, or NATO) are set in small caps, without periods, and are wrapped in an <abbr epub:type="z3998:acronym"> element with corresponding CSS.

    [epub|type~="z3998:acronym"]{ font-variant: all-small-caps; }
    <p>He was hired by <abbr epub:type="z3998:acronym">NASA</abbr> last week.</p>

  2. Initialisms (terms made up of initials in which each initial is pronounced separately, like M.P., P.S., or U.S.S.R.) are set with periods and without spaces (with some exceptions that follow) and are wrapped in an <abbr epub:type="z3998:initialism"> element.

    <p>He was hired by the <abbr epub:type="z3998:initialism">U.S.</abbr> <abbr epub:type="z3998:initialism">F.B.I.</abbr> last week.</p>

  3. When an abbreviation that is not an acronym contains a terminal period, its <abbr> element has the additional eoc class (End of Clause) if the terminal period is also the last period in clause. Such sentences do not have two consecutive periods.

    <p>She loved Italian food like pizza, pasta, <abbr class="eoc">etc.</abbr></p>
    <p>He lists his name alphabetically as Johnson, <abbr class="eoc" epub:type="z3998:given-name">R. A.</abbr></p>
    <p>His favorite hobby was <abbr epub:type="z3998:acronym">SCUBA</abbr>.</p>

  4. Initials of people’s names are each separated by periods and spaces. The group of initials is wrapped in an <abbr epub:type="z3998:*-name"> element. The correct semantic is selected from z3998:personal-name (a complete personal name including last name), z3998:given-name (a person's given, or first, name(s), and/or middle name), or z3998:surname (a person's last name). If it’s unclear whether a name is a first or last name, z3998:personal-name is used as a catchall.

    <p><abbr epub:type="z3998:given-name">H. P.</abbr> Lovecraft described himself as an aged antiquarian.</p> <p>William <abbr epub:type="z3998:given-name">H.</abbr> Taft was our twenty-seventh president.</p> <footer> <p epub:type="z3998:signature"><abbr epub:type="z3998:personal-name">A. A. C.</abbr></p> <p>Dec 12, 1933</p> </footer>

  5. Academic degrees are wrapped in an <abbr epub:type="z3998:name-title"> element. Degrees that consist of initials are set with a period between each initial. Degrees that consist of initials followed by abbreviated words are set with a hair space before the word.

    <p>Judith Douglas, <abbr class="eoc" epub:type="z3998:name-title">D.D.S</abbr></p> <p>Abraham Van Helsing, <abbr epub:type="z3998:name-title">M.D.</abbr>, <abbr epub:type="z3998:name-title">D.hairspPh.</abbr>, <abbr epub:type="z3998:name-title">D.hairspLit.</abbr>, <abbr>etc.</abbr>, <abbr class="eoc">etc.</abbr></p>

    1. Some degrees are exceptions:

      • LL.D. does not have a period in LL, because it indicates the plural Legum.

  6. Postal codes and abbreviated US states are set in all caps, without periods or spaces, and are wrapped in an <abbr epub:type="z3998:place"> element.

    <p>Washington <abbr epub:type="z3998:place">DC</abbr>.</p>

  7. Abbreviations that are abbreviations of a single word, and that are not acronyms or initialisms (like Mr., Mrs., or lbs.) are set with <abbr>.

    1. Abbreviations ending in a lowercase letter are set without spaces between the letters, and have a trailing period.

    2. Abbreviations without lowercase letters are set without spaces and without a trailing period.

    3. Abbreviations that describes the next word, like Mr., Mrs., Mt., and St., are set with a no-break space (U+00A0) between the abbreviation and its target.

      <p>He called on <abbr>Mrs.</abbr>nbspJones yesterday.</p>

  8. Compass points are separated by periods and spaces. The group of points are wrapped in an <abbr epub:type="se:compass"> element.

    <p>He traveled <abbr epub:type="se:compass">S.</abbr>, <abbr epub:type="se:compass">N. W.</abbr>, then <abbr class="eoc" epub:type="se:compass">E. S. E.</abbr></p>

Exceptions

  1. The following are not abbreviations, and are set without periods or spaces.

    • OK

    • SOS

    • BB, when referring to a BB gun or its projectiles.

    • SS, when referring to collars of SS.

  2. The following are initialisms, but are set without periods or spaces:

    • TV, i.e. television.

    • AC and DC, when referring to electrical current.

    • G, when used in the sense of G-force. Also see 8.8.7.4.2.

    • Stock ticker symbols.

      <p>She bought 125 shares of <abbr epub:type="z3998:initialism">XYZ</abbr> corporation.</p>

  3. The following are abbreviations, but are not initialisms. Unlike almost all other abbreviations, they are in all caps and only have a period at the end.

    • MS. (manuscript)

    • MSS. (manuscripts)

    • M. (Monsieur)

    • MM. (Messieurs)

    <p><abbr>MM.</abbr>nbspGuy and Luc were putting the finishing touches on the <abbr>MS.</abbr> of their new novel.</p>

  4. A.B.C., when used in the sense of the alphabet, is not an abbreviation, and is set with periods between the letters. But other uses, like A.B.C. shops, are abbreviations. (The abbreviation in A.B.C. shop stands for “Australian Broadcasting Corporation.”)

    <p>She was learning her A.B.C.s</p> <p>He stopped by the <abbr epub:type="z3998:initialism">A.B.C.</abbr> shop.</p>

  5. Company names and brand marks which may be abbreviations, but are stylized without periods by the brand, are kept in the style preferred by the brand.

    <p>He read an <abbr epub:type="z3998:initialism">AP</abbr> news wire story.</p> <p>She called her colleague at <abbr epub:type="z3998:initialism">IBM</abbr>.</p>

  6. The abbreviations 1D, 2D, 3D, and 4D, meaning first, second, third, and fourth dimensions, are abbreviations but do not have a trailing period.

  7. The words recto and verso are sometimes abbreviated with an initial and a superscript o. They are regular abbreviations, set without periods, and the o is superscripted with <sup>.

    <p><abbr>Ch.</abbr> 1, <abbr>fol.</abbr> 2 <abbr>r<sup>o</sup></abbr>.</p>

Times

  1. Times in a.m. and p.m. format are set in lowercase, with periods, and without spaces.

  2. a.m. and p.m. are wrapped in an <abbr> element.

Times as digits

  1. Digits in times are separated by a colon, not a period or comma.

  2. Times written in digits followed by a.m. or p.m. are set with a no-break space (U+00A0) between the digit and a.m. or p.m..

    <p>He called at 6:40nbsp<abbr class="eoc">a.m.</abbr></p>

Times as words

  1. Words in a spelled-out time are separated by spaces, unless they appear before a noun, where they are separated by a hyphen.

    <p>He arrived at five thirty.</p>
    <p>They took the twelve-thirty train.</p>

  2. Times written in words followed by a.m. or p.m. are set with a regular space between the time and a.m. or p.m..

    <p>She wasn’t up till seven <abbr class="eoc">a.m.</abbr></p>

  3. Military times that are spelled out (for example, in dialog) are set with dashes. Leading zeros are spelled out as oh.

    <p>He arrived at oh-nine-hundred.</p>

Chemicals and compounds

  1. Molecular compounds are set in Roman, without spaces, and wrapped in an <abbr epub:type="se:compound"> element.

    <p>He put extra <abbr epub:type="se:compound">NaCl</abbr> on his dinner.</p>

  2. Elements in a molecular compound are capitalized according to their listing in the periodic table.

  3. Amounts of an element in a molecular compound are set in subscript with a <sub> element.

    <p>She drank eight glasses of <abbr epub:type="se:compound">H<sub>2</sub>O</abbr> a day.</p>

Temperatures

  1. The minus sign glyph (− or U+2212), not the hyphen glyph, is used to indicate negative numbers.

  2. Either the degree glyph (° or U+00B0) or the word degrees is acceptable. Works that use both are normalized to use the dominant method.

Abbreviated units of temperature

  1. Units of temperature measurement, like Farenheit or Celsius, may be abbreviated to F or C.

  2. Units of temperature measurement do not have trailing periods.

  3. If an abbreviated unit of temperature measurement is preceded by a number, the unit of measurement is first preceded by a hair space ( or U+200A).

  4. Abbreviated units of measurement are set in small caps.

  5. Abbreviated units of measurement are wrapped in an <abbr epub:type="se:temperature"> element.

    [epub|type~="se:temperature"]{ font-variant: all-small-caps; }
    <p>It was −23.33° Celsius (or −10°hairsp<abbr epub:type="se:temperature">F</abbr>) last night.</p>

Scansion

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

  1. When scansion marks are next to, instead of above, letters, × (U+00d7) indicates an unstressed sylllable and / (U+002f) indicates a stressed syllable. They are separated from each other with no-break spaces (U+00A0).

    <p>Several of his types, however, constantly occur; <abbr>e.g.</abbr> A and a variant (/ × | / ×) (/ × × | / ×); B and a variant (× / | × /) (× × / | × /); a variant of D (/ × | / × ×); E (/ × × | /). </p>

  2. When scansion marks are above letters, a combining breve, ◌̆ (U+0306), is used to indicate an unstressed syllable and a combining vertical line above, ◌̍ (U+030D), is used to indicate a stressed syllable. Vertical lines are always above letters, not next to them. Indicating unstressed symbols is optional.

    <p>I̍f wĕ sha̍dŏws ha̍ve ŏffe̍ndĕd, / Thi̍nk bŭt thi̍s ănd a̍ll ĭs me̍ndĕd.</p>

  3. Lines of poetry listed on a single line (like in a quotation) are separated by a space, then a forward slash, then a space. Capitalization is preserved for each line.

    <p>The famous lines “Wake! For the Sun, who scatter’d into flight / The Stars before him from the Field of Night” are from <i epub:type="se:name.publication.book">The Rubáiyát of Omar Khayyám</i>.</p>

Legal cases and terms

  1. Legal cases are set in italics.

  2. Either versus or v. are acceptable in the name of a legal case; if using v., a period follows the v., and it is wrapped in an <abbr> element.

    <p>He prosecuted <i epub:type="se:name.legal-case">Johnson <abbr>v.</abbr> Smith</i>.</p>

Morse code

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

American Morse Code

  1. Middle dot glyphs (· or U+00B7) are used for the short mark or dot.

  2. En dash (– or U+2013) are used for the longer mark or short dash.

  3. Em dashes (— or U+2014) are used for the long dash (the letter L).

  4. If two en dashes are placed next to each other, a hair space ( or U+200A) is placed between them to keep the glyphs from merging into a longer dash.

  5. Only in American Morse Code, there are internal gaps used between glyphs in the letters C, O, R, or Z. No-break spaces (U+00A0) are used for these gaps.

  6. En spaces (U+2002) are used between letters.

  7. Em spaces (U+2003) are used between words.

    <p>-- .. .. __ .. - - __ . . .. __ -.. .. . .- -</p> <p>My little old cat.</p>
    <p>– – ·· ·· — ·· – – — · · · — –·· ·· · ·– –</p> <p>My little old cat.</p>

Citations

  1. Citations are wrapped in a <cite> element.

  2. Citations that are the source of a quote are preceded by a space and an em dash, within the <cite> element.

    <p>“The Moving Finger writes; and, having writ, moves on.” <cite>—<i epub:type="se:name.publication.book">The Rubaiyat of Omar Khayyam</i></cite>.</p>

  3. Citations within a <blockquote> element have the <cite> element as the last direct child of the <blockquote> parent.

    <blockquote> <p>“The Moving Finger writes; and, having writ, moves on.”</p> <p> <cite>—<i epub:type="se:name.publication.book">The Rubaiyat of Omar Khayyam</i></cite> </p> </blockquote>
    <blockquote> <p>“The Moving Finger writes; and, having writ, moves on.”</p> <cite>—<i epub:type="se:name.publication.book">The Rubaiyat of Omar Khayyam</i></cite> </blockquote>

Verses and Chapters of the Bible

  1. Citations of passages from the Bible include the name of the book, followed by the chapter number and the verse number. The chapter and the verse numbers are separated by a colon.

    1. All chapter and verse numbers are written in Arabic numerals. Similarly, if a book being cited is a “numbered” book, the number is also written in Arabic numerals.

    <blockquote> <p>“Though I speak with the tongues of men and of angels, and have not charity, I am become as sounding brass, or a tinkling cymbal.”</p> <cite>—<span epub:type="z3998:roman">I</span> Corinthians <span epub:type="z3998:roman">XIII</span> 1</cite> </blockquote>
    <blockquote> <p>“Though I speak with the tongues of men and of angels, and have not charity, I am become as sounding brass, or a tinkling cymbal.”</p> <cite>—1 Corinthians 13:1</cite> </blockquote>

  2. If an entire chapter, instead of a particular verse, is being cited, then the citation includes the name of the book followed by the chapter number.

    <p>“In the beginning God created the heaven and the earth” is the first verse of Genesis <span epub:type="z3998:roman">I</span>.</p>
    <p>“In the beginning God created the heaven and the earth” is the first verse of Genesis 1.</p>

  3. If a continuous range of verses is being cited, an en dash (– or U+2013) is placed between the verse numbers indicating the beginning and the end of the range.

    <p>Matthew 5:3–11.</p>

    Ranges may also span multiple chapters within the same book:

    <p>Matthew 5:1–7:29.</p>

  4. If a discontinuous group of verses in the same chapter is being cited, each distinct verse number is separated by a comma followed by a space.

    <p>Matthew 6:2, 16.</p>

  5. If there are multiple citations of the same book, each citation is separated by a semicolon followed by a space, and the name of the book is omitted after the first citation.

    <p>Matthew 5:3–11; 5:1–7:29; 6:2, 16</p>

Non-Latin Scripts and Transliterations

  1. Greek script is set in italics. All other scripts are not set in italics unless specially required by the text.

Greek

  1. Rough breathing marks are set using their precomposed character, if available; for example, Ἁ, ἇ, and Ἧ. If a precomposed character is not available, ̔ (U+0314) is used when the mark must be combined with a character, and ʽ (U+02BD) is used in all other cases.

  2. Smooth breathing marks are set with ◌̓ (U+0313) when the mark must be combined with a character. ᾿ (U+1FBF) is used in all other cases.

Chinese

  1. Wade-Giles is the preferred method of transliterating Chinese script. (See here for discussion.) Transliteration to Wade-Giles from Legge is permitted, but not required.

  2. In Wade-Giles transliteration, rough breathing marks are set using ʽ (U+02BD).

Tables

For ditto marks, see 8.7.5.4.

  1. <table> elements that are used to display tabular numerical data, for example columns of sums, have CSS styling for tabular numbers: font-variant-numeric: tabular-nums;.

    table td:last-child{ text-align: right; font-variant-numeric: tabular-nums; }
    <table> <tbody> <tr> <td>Amount 1</td> <td>100</td> </tr> <tr> <td>Amount 2</td> <td>300</td> </tr> <tr> <td>Total</td> <td>400</td> </tr> </tbody> </table>

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.

General URL rules

  1. URLs used in metadata are https where possible.

  2. URLs used in metadata do not contain query strings, or if a query string is required, only contain the minimum necessary query string to render the base resource.

  3. URLs used for Project Gutenberg page scans look like: https://www.gutenberg.org/ebooks/<BOOK-ID>.

  4. URLs used for HathiTrust page scans look like: https://catalog.hathitrust.org/Record/<RECORD-ID>.

  5. URLs used for Google Books page scans look like: https://books.google.com/books?id=<BOOK-ID>.

  6. URLs used for Internet Archive page scans look like: https://archive.org/details/<BOOK-ID>.

The ebook identifier

  1. The <dc:identifier> element contains the unique identifier for the ebook. The identifier is the Standard Ebooks URL for the ebook, prefaced by url:.

    <dc:identifier id="uid">url:https://standardebooks.org/ebooks/anton-chekhov/short-fiction/constance-garnett</dc:identifier>

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

  • Start with the URL-safe author of the work, as it appears on the titlepage. If there is more than one author, continue appending subsequent URL-safe authors, separated by an underscore. Do not alpha-sort the author name.

  • Append a forward slash, then the URL-safe title of the work. Do not alpha-sort the title.

  • If the work is translated, append a forward slash, then the URL-safe translator. If there is more than one translator, continue appending subsequent URL-safe translators, separated by an underscore. Do not alpha-sort translator names.

  • If the work is illustrated, append a forward slash, then the URL-safe illustrator. If there is more than one illustrator, continue appending subsequent URL-safe illustrators, separated by an underscore. Do not alpha-sort illustrator names.

  • Finally, do not append a trailing forward slash.

Publication date and release identifiers

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

  1. <dc:date> is a timestamp representing the first publication date of this ebook file. Once the ebook is released to the public, this value doesn’t change.

  2. <meta property="dcterms:modified"> is a timestamp representing the last time this ebook file was modified. This changes often.

Book titles

Books without subtitles

  1. The <dc:title id="title"> element contains the title.

  2. The <meta property="file-as" refines="#title"> element contains alpha-sorted title, even if the alpha-sorted title is identical to the unsorted title.

<dc:title id="title">The Moon Pool</dc:title> <meta property="file-as" refines="#title">Moon Pool, The</meta>
<dc:title id="title">Short Fiction</dc:title> <meta property="file-as" refines="#title">Short Fiction</meta>

Books with subtitles

  1. The <meta property="title-type" refines="#title">main</meta> element identifies the main part of the title.

  2. A second <dc:title id="subtitle"> element contain the subtitle, and is refined with <meta property="title-type" refines="#subtitle">subtitle</meta>.

  3. A third <dc:title id="fulltitle"> element contains the complete title on one line, with the main title and subtitle separated by a colon and space, and is refined with <meta property="title-type" refines="#fulltitle">extended</meta>.

  4. All three <dc:title> elements have an accompanying <meta property="file-as"> element, even if the file-as value is the same as the title.

<dc:title id="title">The Moon Pool</dc:title> <meta property="file-as" refines="#title">Moon Pool, The</meta>
<dc:title id="title">The Man Who Was Thursday</dc:title> <meta property="file-as" refines="#title">Man Who Was Thursday, The</meta> <meta property="title-type" refines="#title">main</meta> <dc:title id="subtitle">A Nightmare</dc:title> <meta property="file-as" refines="#subtitle">Nightmare, A</meta> <meta property="title-type" refines="#subtitle">subtitle</meta> <dc:title id="fulltitle">The Man Who Was Thursday: A Nightmare</dc:title> <meta property="file-as" refines="#fulltitle">Man Who Was Thursday, The</meta> <meta property="title-type" refines="#fulltitle">extended</meta>

Books with a more popular alternate title

Some books are commonly referred to by a shorter name than their actual title. For example, The Adventures of Huckleberry Finn is often simply known as Huck Finn.

  1. The <dc:title id="title-short"> element contains the common title. It is refined with <meta property="title-type" refines="#title-short">short</meta> and <meta property="file-as">.

Books published with multiple titles

Some books may have been published under more than one official title. This is not the same as a book being more commonly known by a popular title. For example, The Mark of Zorro was originally serialized as The Curse of Capistrano.

  1. The <meta property="dcterms:alternative" refines="#title"> element contains the alternate title. It is not refined with <meta property="file-as">.

    <dc:title id="title">The Mark of Zorro</dc:title> <meta property="file-as" refines="#title">Mark of Zorro, The</meta> <meta property="dcterms:alternative" refines="#title">The Curse of Capistrano</meta>

Books with numbers or abbreviations in the title

Books that contain numbers or abbreviations in their title may be difficult to find with a search query, because there can be different ways to search for numbers or abbreviations. For example, a reader may search for Around the World in Eighty Days by searching for “80” instead of “eighty”.

  1. If a book title contains numbers or abbreviations, a <meta property="dcterms:alternate" refines="#title"> element is placed after the main title block, containing the title with expanded or alternate spelling to facilitate possible search queries.

    <dc:title id="title">Around the World in Eighty Days</dc:title> <meta property="file-as" refines="#title">Around the World in Eighty Days</meta> <meta property="dcterms:alternate" refines="#title">Around the World in 80 Days</meta>
    <dc:title id="title">File No. 113</dc:title> <meta property="file-as" refines="#title">File No. 113</meta> <meta property="dcterms:alternate" refines="#title">File Number One Hundred and Thirteen</meta>

Book subjects

The <dc:subject> element

<dc:subject> elements describe the categories the ebook belongs to.

  1. Each <dc:subject> has the id attribute set to subject-#, where # is a number starting at 1, without leading zeros, that increments with each subject.

  2. The <dc:subject> elements are arranged sequentially in a single block.

  3. <dc:subject> values are sourced from Library of Congress Subject Headings.

  4. If the transcription for the ebook comes from Project Gutenberg, the values of the <dc:subject> elements come from the Project Gutenberg “bibrec” page for the ebook. Otherwise, the values come from the Library of Congress catalog listing for the book.

  5. After the block of <dc:subject> elements there is a block of <meta property="authority" refines="#subject-N"> and <meta property="term" refines="#subject-N"> element pairs.

    1. <meta property="authority" refines="#subject-N"> contains the source for the category. For Library of Congress categories, the value is LCSH.

    2. <meta property="term" refines="#subject-N"> contains term ID for that subject heading.

Examples

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

<dc:subject id="subject-1">Science fiction</dc:subject> <dc:subject id="subject-2">Psychological fiction</dc:subject> <dc:subject id="subject-3">Quests (Expeditions) -- Fiction</dc:subject> <dc:subject id="subject-4">Life on other planets -- Fiction</dc:subject> <meta property="authority" refines="#subject-1">LCSH</meta> <meta property="term" refines="#subject-1">sh85118629</meta> <meta property="authority" refines="#subject-2">LCSH</meta> <meta property="term" refines="#subject-2">sh85108438</meta> <meta property="authority" refines="#subject-3">LCSH</meta> <meta property="term" refines="#subject-3">sh2008110314</meta> <meta property="authority" refines="#subject-4">LCSH</meta> <meta property="term" refines="#subject-4">sh2008106912</meta>

SE subjects

Along with the Library of Congress categories, a set of SE subjects is included in the ebook metadata. Unlike Library of Congress categories, SE subjects are purposefully broad. They’re more like the subject categories in a small bookstore, as opposed to the precise, detailed, hierarchical Library of Congress categories.

  1. SE subjects are included with one or more <meta property="se:subject"> elements.

    <meta property="se:subject">Fantasy</meta> <meta property="se:subject">Philosophy</meta>

  2. There is at least one SE subject.

  3. SE subjects are in alphabetical order.

All SE subjects

  • Adventure

  • Autobiography

  • Biography

  • Children’s

  • Comedy

  • Drama

  • Fantasy

  • Fiction

  • Horror

  • Memoir

  • Mystery

  • Nonfiction

  • Philosophy

  • Poetry

  • Satire

  • Science Fiction

  • Shorts

  • Spirituality

  • Travel

Required SE subjects for specific types of books

  1. Ebooks that are collections of short stories have the SE subject Shorts as one of the SE subjects.

  2. Ebooks that are young adult or children’s books have the SE subject Children’s as one of the SE subjects.

Book descriptions

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

The short description

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

  1. The description is a single complete sentence ending in a period, not a sentence fragment or restatement of the title.

  2. The description summarizes the main theme or plot thread in the book, in an active voice, without using proper names.

    Sally the witch curses Bob Smith. He is turned in to a frog. His career as a barber is put on hold.
    This is a book about love, loss, and recovering from tragedy.
    An evil witch transforms a garrulous barber into a frog, putting his career on hold as he comes to grips with his new station in life.

  3. For collections, compilations, and omnibuses, a sentence fragment is acceptable as a description.

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

The long description

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

  1. The long description is a non-biased, encyclopedia-like description of the book, including any relevant publication history, backstory, or historical notes. It is as detailed as possible without giving away plot spoilers. It does not impart the producer’s opinions of the book, or include content warnings. Think along the lines of a Wikipedia-like summary of the book and its history, but under no circumstances can a producer copy and paste from Wikipedia! (Wikipedia licenses articles under a CC license which is incompatible with Standard Ebooks’ CC0 public domain dedication.)

  2. The long description is typogrified, i.e. it contains Unicode curly quotes, em dashes, and the like.

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

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

  5. The first occurrence of the author’s name is linked to the Standard Ebooks author page. For example, for Arthur Conan Doyle this would look like <a href="https://standardebooks.org/ebooks/arthur-conan-doyle">Arthur Conan Doyle</a>. If the long description references other authors, books and story collections that already have pages on Standard Ebooks then the first occurrence of these are linked as well.

  6. The long description does not contain external links other than links to other Standard Ebooks books or authors.

Book language

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

Book transcription and page scan sources

  1. The <dc:source> elements represent URLs to sources for the transcription the ebook is based on, and page scans of the print sources used to correct the transcriptions.

  2. <dc:source> URLs are in https where possible.

  3. A book can contain more than one such element if multiple sources for page scans were used.

    1. If the ebook is a collection in which different parts appear across different page scan sources (like a short story or poetry collection), an XML comment is included above each <dc:source> element specifying which part of the ebook is included in the following source URL.

      <!--The Man of the Crowd, Eleanora, The Oval Portrait--> <dc:source>https://archive.org/details/worksofedgaralla01poeeuoft</dc:source> <!--The Gold-Bug, A Tale of the Rugged Mountains, Mesmeric Revelation--> <dc:source>https://archive.org/details/worksofedgaralla02poeeuoft</dc:source>

Additional book metadata

  1. <meta property="se:url.encyclopedia.wikipedia"> contains the English Wikipedia URL for the book. This element is not present if there is no English Wikipedia entry for the book.

  2. <meta property="se:url.vcs.github"> contains the SE GitHub URL for this ebook. This is calculated by taking the string https://github.com/standardebooks/ and appending the SE identifier, without https://standardebooks.org/ebooks/, and with forward slashes replaced by underscores.

  3. <meta property="belongs-to-collection" id="collection-N"> contains the name of the collection the ebook belongs to.

    1. The value for this element must be the same for all ebooks in the collection.

    2. The id attribute is collection-N where N is a positive integer starting at 1.

    3. The element is further refined by a <meta property="collection-type" refines="#collection-N"> element with the value of set or series. See the EPUB spec for more details.

    4. <meta property="se:is-a-collection">true</meta> is present if the ebook is a collection of items which a reader may wish to search by item title. For example, this would include ebooks like a collection of short stories, or a collection of short works by an author from antiquity.

Book production notes

  1. The <meta property="se:production-notes"> element contains any of the ebook producer’s production notes. For example, the producer might note that page scans were not available, so an editorial decision was made to add commas to sentences deemed to be transcription typos; or that certain archaic spellings were retained as a matter of prose style specific to this ebook.

  2. The <meta property="se:production-notes"> element is not present if there are no production notes.

Readability metadata

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

  1. The <meta property="se:word-count"> element contains an integer representing the ebook’s 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.

General contributor rules

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

  1. If there is exactly one contributor in a set (for example, only one author, or only one translator) then the <meta property="display-seq"> element is omitted for that contributor.

  2. If there is more than one contributor in a set (for example, multiple authors, or translators) then the <meta property="display-seq"> element is specified for each contributor, with a value equal to their position in the SE identifier.

  3. The EPUB spec specifies that in a set of contributors, if at least one has the display-seq property, then other contributors in the set without the display-seq value are ignored. For SE purposes, this also means they will be excluded from the SE identifier.

  4. By SE convention, contributors with <meta property="display-seq">0</meta> are excluded from the SE identifier.

  5. The EPUB spec allows for up to one (but not more than one) role to be specified for a contributor using the <meta property="role" refines="..." scheme="marc:relators">. element. However, it is not uncommon for one contributor to have multiple roles; for example, an author (aut) who also illustrated (ill) the book. In these cases, the primary role is assigned using the role property, and additional roles are assigned using the se:role property.

Example

<dc:creator id="author">Jonathan Swift</dc:creator> ... <meta property="role" refines="#author" scheme="marc:relators">aut</meta> <meta property="se:role" refines="#author" scheme="marc:relators">ill</meta> <meta property="se:role" refines="#author" scheme="marc:relators">win</meta> <meta property="se:role" refines="#author" scheme="marc:relators">wpr</meta>

The author metadata block

  1. <dc:creator id="author"> contains the author’s name as it appears on the cover.

  2. If there is more than one author, the first author’s id is author-1, the second author-2, and so on.

  3. <meta property="file-as" refines="#author"> contains the author’s name as filed alphabetically. This element is included even if it’s identical to <dc:creator>.

  4. <meta property="se:name.person.full-name" refines="#author"> contains the author’s full name, with any initials or middle names expanded, and including any titles. If the author uses a pseudonym, then this should be the full pseudonym, not the author’s real name. This element is not included if the value is identical to <dc:creator>.

  5. <meta property="alternate-script" refines="#author"> contains the author’s name as it appears on the cover, but transliterated into their native alphabet if applicable. For example, Anton Chekhov’s name would be contained here in the Cyrillic alphabet. This element is not included if not applicable.

  6. <meta property="se:url.encyclopedia.wikipedia" refines="#author"> contains the URL of the author’s English Wikipedia page. This element is not included if there is no English Wikipedia page.

  7. <meta property="se:url.authority.nacoaf" refines="#author"> contains the URI of the author’s Library of Congress Names Database page. It uses a plain http: prefix, and does not include the .html file extension. This element is not included if there is no LoC Names database entry.

  8. <meta property="role" refines="#author" scheme="marc:relators"> contains the MARC relator tag for the roles the author played in creating this book.

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

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

The translator metadata block

  1. If the work is translated, the <dc:contributor id="translator"> metadata block follows the author metadata block.

  2. If there is more than one translator, then the first translator’s id is translator-1, the second translator-2, and so on.

  3. Each block is identical to the author metadata block, but with <dc:contributor id="translator"> instead of <dc:creator id="author">.

  4. The MARC relator tag is trl: <meta property="role" refines="#translator" scheme="marc:relators">trl</meta>.

  5. Translators often annotate the work; if this is the case, the additional MARC relator tag ann is included in a separate <meta property="se:role" refines="#translator" scheme="marc:relators"> element.

The illustrator metadata block

  1. If the work is illustrated by a person who is not the author, the illustrator metadata block follows.

  2. If there is more than one illustrator, the first illustrator’s id is illustrator-1, the second illustrator-2, and so on.

  3. Each block is identical to the author metadata block, but with <dc:contributor id="illustrator"> instead of <dc:creator id="author">.

  4. The MARC relator tag is ill: <meta property="role" refines="#illustrator" scheme="marc:relators">ill</meta>.

The cover artist metadata block

The “cover artist” is the artist who painted the art the producer selected for the Standard Ebook cover.

  1. The cover artist metadata block is identical to the author metadata block, but with <dc:contributor id="artist"> instead of <dc:creator id="author">.

  2. The MARC relator tag is art: <meta property="role" refines="#artist" scheme="marc:relators">art</meta>.

Metadata for additional contributors

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

  1. Additional contributor blocks are identical to the author metadata block, but with <dc:contributor> instead of <dc:creator>.

  2. The id attribute of the <dc:contributor> is the lowercase, URL-safe, fully-spelled out version of the MARC relator tag. For example, if the MARC relator tag is wpr, the id attribute would be writer-of-preface.

  3. The MARC relator tag is one that is appropriate for the role of the additional contributor. Common roles for ebooks are: wpr, ann, and aui.

Transcriber metadata

  1. If the ebook is based on a transcription by someone else, like Project Gutenberg, then transcriber blocks follow the general contributor metadata blocks.

  2. If the transcriber is anonymous, the value for the producer’s <dc:contributor> element is Anonymous.

  3. If there is more than one transcriber, the first transcriber is transcriber-1, the second transcriber-2, and so on.

  4. The <meta property="file-as" refines="#transcriber-1"> element contains an alpha-sorted representation of the transcriber’s name.

  5. The MARC relator tag is trc: <meta property="role" refines="#transcriber-1" scheme="marc:relators">trc</meta>.

  6. If the transcriber’s personal homepage is known, the element <meta property="se:url.homepage" refines="#transcriber-1"> is included, whose value is the URL of the transcriber’s homepage. The URL must link to a personal homepage only; no products, services, or other endorsements, commercial or otherwise.

Sponsor metadata

  1. If an ebook has a financial sponsor, then the sponsor block follows the transcriber block.

  2. The <meta property="file-as" refines="#sponsor"> element contains an alpha-sorted representation of the sponsor’s name.

  3. The MARC relator tag is spn: <meta property="role" refines="#sponsor" scheme="marc:relators">spn</meta>.

  4. If the sponsor’s personal homepage is known, the element <meta property="se:url.homepage" refines="#sponsor"> is included, whose value is the URL of the sponsor’s homepage. Since sponsors may be corporations, linking to a corporate homepage is permitted; however linking to specific product or service is disallowed.

Producer metadata

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

  1. Producer names must sound like complete real names, i.e., they must have at least a first initial and full last name. Anonymous producers are allowed, and if the producer is anonymous then the value for the producer’s <dc:contributor> element is Anonymous.

  2. If there is more than one producer, the first producer is producer-1, the second producer-2, and so on.

  3. The producer metadata block is identical to the author metadata block, but with <dc:contributor id="producer-1"> instead of <dc:creator id="author">.

  4. If the producer’s personal homepage is known, the element <meta property="se:url.homepage" refines="#producer-1"> is included, whose value is the URL of the transcriber’s homepage. The URL must link to a personal homepage only; no products, services, or other endorsements, commercial or otherwise.

  5. The MARC relator tags for the SE producer usually include all of the following:

    • bkp: The producer produced the ebook as role.

    • blw: The producer wrote the blurb (the long description) as se:role.

    • cov: The producer selected the cover art as se:role.

    • mrk: The producer wrote the HTML markup for the ebook as se:role.

    • pfr: The producer proofread the ebook as se:role.

    • tyg: The producer reviewed the typography of the ebook as se:role.

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. Files which contain SVG images have the additional properties attribute with the value svg in their manifest item.

  4. The manifest item for the table of contents file has the additional properties attribute with the value nav.

  5. The manifest item for the cover image has the additional properties attribute with the value cover-image.

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.

Accessibility metadata

Accessibility metadata is added to bring the final ebook into conformance with the EPUB Accessibility spec, with the following considerations.

  1. Accessibility metadata is arranged in the metadata file in groups by property, with items in each group ordered by their text values. The groups appear in this order:

    1. a11y:certifiedBy

    2. schema:accessMode

    3. schema:accessModeSufficient

    1. schema:accessibilityFeature

    2. schema:accessibilityHazard

    3. schema:accessibilitySummary

  2. If the ebook has images not including the cover, titlepage, and publisher logo, then the following metadata is included in addition to any boilerplate accessibility metadata:

    <meta property="schema:accessMode">visual</meta> <meta property="schema:accessibilityFeature">alternativeText</meta>

    The cover, titlepage, and publisher logo are ignored because they are present in most ebooks; if they were to be counted in accessibilty metadata, that metadata would appear in most ebooks, making it meaningless.

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.

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

Complete list of files

A complete set of image source files consists of:

  • ./images/cover.source.jpg: The full source image used for the cover art, in as high a resolution as possible. Can be of any image format, but typically we end up with JPGs.

  • ./images/cover.jpg: A cropped part of the source image that will serve as the actual image file we use in the cover. Must be exactly 1400w × 2100h.

  • ./images/cover.svg: The SVG source file for the cover, with any text represented as actual, editable text. Must be exactly 1400w × 2100h pixels. Since the final cover image SVG has the text converted to paths, we keep this file around to make it easier to make changes to the cover in the future.

  • ./src/epub/images/cover.svg: The final SVG cover image. This image should be exactly like ./images/cover.svg, but with the text converted to paths.

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

  • ./images/titlepage.svg: The SVG source file for the titlepage, with any text represented as actual, editable text. Must be exactly 1400 pixels wide, but the height must exactly match the text height plus some padding (described below).

  • ./src/epub/images/titlepage.svg: The final SVG titlepage image, with text converted to paths just like the cover page.

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

SVG patterns

  1. SVGs are only sized with viewBox, not height or width.

    1. The viewBox attribute consists of whole numbers, without fractions.

  2. The only attributes on the <svg> root element are: xmlns, version, and viewBox.

  3. The contents of the SVG’s <title> element matches the alt attribute of its <img> element in the text.

  4. Grouping with <g> is avoided, unless it makes semantic sense. Groups whose sole purpose is to apply transforms should have those transforms applied to the children, and the group removed.

  5. The use of fill color is avoided unless strictly necessary. Not defining a fill color allows for night mode compatibility.

  6. The transform attribute is illegal; transforms are applied to their elements directly.

The cover image

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

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

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

    1. If the author is Anonymous, then the author is omitted from the cover image.

  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. Translators, illustrators, and other contributors besides the author do not appear on the cover.

  4. The group of both the title and author lines is horizontally centered in the black title box.

Title line dimensions

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

  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. 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. 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. One-line authors: the line is 40px tall.

  3. 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. ./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. 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. Cover art is in the “fine art oil painting” style, and in full color. Art not in this style, like ink drawings, woodcuts, medieval-style “flat” paintings, pencil sketches, modern CG art, or black-and-white scans, is not acceptable. Generally watercolor is not acceptable, though some watercolor may be acceptable if its appearance is oil-paining-like.

  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. The cropped ./images/cover.jpg is not larger than 1.5 MB.

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 book published before January 1, 1929 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 book published before January 1, 1929.

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

Because of the difficulty, finding suitable cover art is all about compromise. You’re unlikely to find the perfect cover image. You’ll find a lot of paintings that would be great matches, but that you can’t find reproductions of and thus we can’t use. So, be ready to compromise.

Note that in ./images/cover.svg, the black title and author box always goes in the lower half of the work. Thus, paintings in which some important detail would be obscured by the box cannot be used.

  • Before you can go looking for a reproduction of a specific painting to prove its PD status, you have to find a suitable painting to begin with. Wikiart and Artvee are great resources for searching for paintings by keyword. Museum online collections are another good place to look for inspiration.

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

  • Many museum online catalogs have a “bibliography” or “references” section for each painting in their collection. This is usually a list of books in which the painting was either mentioned or reproduced. This is a good shortcut to finding the names of books in which a painting was reproduced, and if you’re lucky, a search for the book title in Google Books will turn up scans.

  • Visit Google Books, HathiTrust, and the Internet Archive to begin searching for books where your art is reproduced.

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

    When searching for cover art, remember that artist names and painting titles may be spelled in many different ways. Often a painting went by multiple titles, or if the title was not in English, by many different translations. Your best bet is to simply search for an artist’s last name, and not the painting title.

  • Once you locate a book with reproductions, open the book up in thumbnail view and quickly eyeball the pages to see if the artwork is reproduced there.

Gotchas

  • In older books it was common to have etchings of paintings. Etchings are not strict reproductions, and so we cannot count them for PD clearance.

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

    Before completing PD clearance, carefully compare the reproduction in the page scan with the high-resolution scan to ensure they are the same painting. Small details like the position of trees, clouds, reflections, or water are good ways to check if the painting is identical, or if you’re looking at a different version.

  • Sometimes the catalog record for a book has an incorrect publication year. Please verify the page scan of the copyright page to ensure the book was published before January 1, 1929.

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.

  • Rijksmuseum (Open the “Object Data” section and check the “Copyright” entry under the “Acquisition and right” section to confirm CC0.)

  • Met Museum (CC0 items have an “OA Public Domain” icon under the picture, which leads to the Met's Open Access Initiative page that clarifies a CC0 license.)

  • National Museum Sweden (CC-PD items have the CC-PD mark in the lower left of the item’s detail view.)

  • Minneapolis Institute of Art (Public domain items are listed as such under “Rights.”)

  • The Walters Art Museum (Public domain items are listed as "CC Creative Commons License" which links to a CC0 rights page.)

  • Art Institute of Chicago (CC0 items say CC0 in the lower left of the painting in the art detail page.)

  • Cleveland Museum of Art (CC0 items have the CC0 logo near the download button.)

  • Paris Musées (CC0 items have the CC0 logo near the download button.)

  • The Smithsonian (CC0 items say CC0 under the Usage header in the item details.)

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

  • National Museum in Krakow (CC0 items say CC0 - Public Domain under the Copyright section.)

  • National Gallery of Denmark (CC0 items have “No copyright” icon and a “Free to use” notice, and the About page states that such images are released via CC0.)

  • Finnish National Gallery (CC0 items say “CC Copyright Free,” and the general rights statement in the original Finnish indicates that such images are CC0 licensed.)

  • National Gallery of Art (CC0 items have a “0 Public Domain” icon under the picture, which leads to an Open Access policy mentioning a CC0 license.)

  • Nivaagaards Malerisamling (CC0 items say “Public Domain” by the picture, which leads to a license details page, which links to a CC0 license.)

  • RISD Museum (CC0 items have a link to the CC0 license in the “Use” section.)

  • Aberdeen Archives, Gallery & Museums (CC0 items say “Out of copyright - CC0” on the copyright line.)

  • Brighton & Hove Museums (CC0 items have the URL of the CC0 license in the “License” field.)

  • Grand Rapids Public Museum (CC0 items have a link to the CC0 license in the “Rights” section.)

Clearance FAQ

  • I found a great painting, and Wikipedia says it’s public domain, but I can’t find a reproduction in a book. Can I use it?

    No. You must find a reproduction of your selected painting in a book published before January 1, 1929.

  • I found a great painting, and it’s really old, and the author died a long time ago, but I can’t find a reproduction in a book. Can I use it?

    No. You must find a reproduction of your selected painting in a book published before January 1, 1929.

  • I’ve found a reproduction in a book, but the book was published after January 1, 1929. Is that OK?

    No. You must find a reproduction of your selected painting in a book published before January 1, 1929.

  • I’ve found painting on a museum site and it says they think it’s in the public domain, but there’s no other license information. Is that OK?

    No. You must find a reproduction of your selected painting in a book published before January 1, 1929.

  • I’ve found painting on a museum site, and it has a CC license other than CC0. Is that OK?

    No. You must find a reproduction of your selected painting in a book published before January 1, 1929.

  • But...

    No. You must find a reproduction of your selected painting in a book published before January 1, 1929.

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.

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

Titlepage image layout

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

    1. If the author or a contributor is Anonymous, then they are omitted from the titlepage image.

  2. The titlepage does not include subtitles.

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

  3. Names of contributors besides the author are preceded by translated by or illustrated by. translated by and illustrated by are set in lowercase Sorts Mill Goudy Italic font.

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

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

  6. The viewbox width is exactly 1400px wide.

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

Title line dimensions

  1. Each title line is 80px tall.

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

  3. 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. Each author line is 60px tall.

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

  4. 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. The first contributor descriptor line begins 150px below the last author line.

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

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

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

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

Other images

Ebooks often have illustrations outside of the cover and titlepage images. Standard Ebooks ebook repositories distinguish between the source image copy, which is a high-resolution image saved in the repository for future needs, and the distributable image copy, which uses the source image copy as a base but is typically scaled down or otherwise processed, and which is the copy of the image that is distributed with the final ebook.

  1. JPEG and TIFF image filenames end in .jpg and .tif, respectively, not .jpeg or .tiff.

Source images

The source image is an unedited, raw copy of the image that is in the highest-resolution possible.

  1. Source images are located in ./images/.

  2. There is always a source image for each corresponding distributable image, even if they are identical.

Distributable images

Distributable images are source images that have been processed for distribution, for example by scaling them down, removing frames, or converting them to SVG.

  1. Distributable images are located in ./src/epub/images/.

  2. The maximum dimensions for distributable images is 2,000 × 2,000 pixels.

  3. Images that consist of plain black line drawings are converted to SVG for distribution.

  4. Distributable images are not larger than 1.5MB in file size, with the exception of the cover image SVG.