High Level Structural Patterns
Section should contain high-level structural patterns for common formatting situations.
Sectioning
The
<body>
element may only have direct children that are<section>
,<article>
, or<nav>
.Major structural divisions of a larger work, like parts, volumes, books, chapters, or subchapters, are contained in a
<section>
element.Individual items in a larger collection (like a poem in a poetry collection) are contained in a
<article>
element.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:
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.
XHTML files that contain
<section>
or<article>
elements that are semantic children of<section>
or<article>
elements in other files, are wrapped in stubs of all parent<section>
or<article>
elements, up to the root.Each such included parent element has the identical
id
andepub:type
attributes of its real counterpart.
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
):
Book 1, Part 2 (part-1-2.xhtml
):
Book 1, Part 2, Chapter 3 (chapter-1-2-3.xhtml
):
Headers
<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.A section containing an
<h1>
–<h6>
appears in the table of contents.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>
.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 namedpart-2.xhtml
containing:Consider this example for the file
chapter-2-3.xhtml
:Each
<h1>
–<h6>
element has a direct parent<section>
,<article>
,<header>
, or<hgroup>
element.<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.<hgroup>
elements only have<h1>
–<h6>
children.<hgroup>
elements are only present if more than one<h1>
–<h6>
element must be grouped together.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>
elements in which<h6>
is the first child have all subsequent children as<h6>
as well.
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.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.
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.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.Ordinals may also appear without a label:
Labels and ordinals are wrapped in an
<h1>
–<h6>
element, but that wrapper element is not a semantic title.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.
Subtitles are supplementary titles in addition to the main title.
Header patterns
Sections with ordinals but without titles:
Sections with titles but without ordinals:
Sections with titles and ordinals:
Sections titles and subtitles but no ordinals:
Sections with labels and ordinals:
Sections with labels, ordinals, and titles:
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):
Sections that require titles, but that are not in the table of contents:
Sections without any titles at all have
margin-top: 20vh
applied to their sectioning container.Half title pages without subtitles:
Half title pages with subtitles:
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.
The last clause in a bridgehead ends in appropriate punctuation, like a period.
Bridgeheads have the following CSS and HTML structure:
Bridgeheads are typically set in italics. Exceptions are allowed according to rules for italics.
Dedications
Dedications are typically full-page, centered on the page for ereaders that support advanced CSS. For all other ereaders, the dedication is horizontally centered with a small margin above it.
All dedications include this base CSS:
Dedications are frequently styled uniquely by the authors. Therefore Standard Ebooks producers have freedom to style dedications to match page scans, for example by including small caps, different font sizes, alignments, etc.
Epigraphs
All epigraphs include this CSS:
Epigraphs are typically set in italics. Exceptions are allowed according to rules for italics.
Epigraphs in section headers
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.In addition to the CSS used for all epigraphs, this additional CSS is included for epigraphs in section headers:
Full-page epigraphs
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.
Full-page epigraphs that contain multiple quotations are represented by multiple
<blockquote>
elements.In addition to the CSS used for all epigraphs, this additional CSS is included for full-page epigraphs:
Example HTML:
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.
A stanza is represented by a
<p>
element styled with this CSS:Each stanza contains
<span>
elements, each one representing a line in the stanza, styled with this CSS:Each
<span>
line is followed by a<br/>
element, except for the last line in a stanza, styled with this CSS:Indented
<span>
lines have thei1
class. Do not usenbsp
for indentation. Indenting to different levels is done by incrementing the class toi2
,i3
, and so on, and including the appropriate CSS.Poems, songs, and verse that are shorter part of a longer work, like a novel, are wrapped in a
<blockquote>
element.The parent element of poetry, verse, or song, has the semantic inflection of
z3998:poem
,z3998:verse
,z3998:song
, orz3998:hymn
.The z3998 vocabulary does not explicitly define their terms for each of the above; these are the standards for our productions.
z3998:poem
is used when an entire poem is quoted, even a short one.z3998:verse
is used for poem or verse fragments.z3998:song
is used when song lyrics are quoted, in whole or in part.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, usez3998:song
.
If a poem is quoted and has one or more lines removed, the removed lines are represented with a vertical ellipses (
⋮
or U+22EE) in a<span class="elision">
element styled with this CSS:
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.
Plays and drama
Dialog in plays is structured using
<table>
elements.Each
<tr>
is either a block of dialog or a standalone stage direction.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.
Works that are plays or that contain sections of dramatic dialog have this core CSS:
Dialog rows
The first child of a row of dialog is a
<td>
element with the semantic inflection ofz3998:persona
.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>
).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 thez3998:verse
semantic.
When several personas speak at once, or a group of personas (“The Actors”) speaks at once, the containing
<tr>
element has thetogether
class, and the first<td>
child has arowspan
attribute corresponding to the number of lines spoken together.
Stage direction
Stage direction is wrapped in an
<i epub:type="z3998:stage-direction">
element.Stage directions that are included from a different edition additionally have the
class="editorial"
attribute, with this additional CSS:
Personas mentioned in stage direction are wrapped in a
<b epub:type="z3998:persona">
element.Possessive
’s
or’
are included within the associated<b>
element.
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:
Stage direction rows
The first child of a row containing only stage direction is an empty
<td>
element.The second child of a row containing only stage direction is a
<td>
element containing the stage direction.
Examples
Inline stage direction
Inline stage direction that is not an interjection within a containing clause begins with a capital letter and ends in punctuation, usually a period.
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
Works that are complete plays
The top-level element (usually
<body>
) has thez3998:drama
semantic inflection.Acts are
<section>
elements containing at least one<table>
for dialog, and optionally containing an act title and other top-level stage direction.Introductory or high-level stage direction is presented using
<p>
elements outside of the dialog table.Dramatis personae are presented as a
<ul>
element listing the characters.
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.
Letters are wrapped in a
<blockquote>
element with the appropriate semantic inflection, usuallyz3998:letter
.
Letter headers
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.If there is only a salutation and no other header content, the
<header>
element is omitted.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.The salutation (for example, “Dear Sir” or “My dearest Jane”) has the semantic inflection of
z3998:salutation
.The first line of a letter after the salutation is not indented.
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).The name of the recipient of the letter, when set out other than within a saluation (for example a letter headed “To: John Smith Esquire”), is given the semantic inflection of
z3998:recipient
. Sometimes this may occur at the end of a letter, particularly for more formal communications, in which case it is placed within a<footer>
element.
Letter footers
Parts of a letter after the body of the letter, for example the signature or postscript, are wrapped in a
<footer>
element.The
<footer>
element has the following CSS:The valediction (for example, “Yours Truly” or “With best regards”) has the semantic inflection of
z3998:valediction
.The sender’s name has semantic inflection of
z3998:sender
. If the name appears to be a signature to the letter, it has thez3998:signature
semantic inflection and corresponding CSS.Postscripts have the semantic inflection of
z3998:postscript
and the following CSS:Postscripts that contain multiple paragraphs are grouped by having their contents wrapped in
<div epub:type="z3998:postscript">
.
Examples
Images
Each image has a unique
id
attribute.That attribute's name is
illustration-
followed by-N
, whereN
is the sequence number of the element starting at1
.If the image is inline with the text, the
id
attribute is on the<img>
element.When contained in a
<figure>
element, the<img>
element does not have anid
attribute; instead the<figure>
element has theid
attribute.
<img>
elements have analt
attribute that uses prose to describe the image in detail; this is what screen reading software will read aloud.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.The
alt
attribute does not contain no-break spaces or word joiners.
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.The
alt
attribute is not necessarily the same as text in the image’s sibling<figcaption>
element, if one is present.
<img>
elements have semantic inflection denoting the type of image. Common values arez3998:illustration
orz3998:photograph
.<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 these:image.color-depth.black-on-transparent
semantic inflection.<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.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’salt
attribute.All figure elements, regardless of positioning, have this CSS:
<figure>
elements that are meant to be displayed as full-page images have thefull-page
class and this additional CSS:<figure>
elements that are meant to be aligned block-level with the text have this additional CSS:
Examples
List of Illustrations (the LoI)
If an ebook has any illustrations that are major structural components of the work (even just one!), then the ebook includes an loi.xhtml
file at the end of the ebook. This file lists the illustrations in the ebook, along with a short caption or description.
The LoI is an XHTML file named
./src/epub/text/loi.xhtml
.The LoI file has the
backmatter
semantic inflection.The LoI only contains links to images that are major structural components of the work.
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.
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.
The LoI file contains a single
<section id="loi" epub:type="loi">
element, which in turn contains a<nav 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.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’salt
attribute is used. If the<figcaption>
element is too long for a concise LoI entry, thealt
attribute is used instead.Links to the images go directly to the image’s corresponding
id
hashes, not just the top of the containing file.
Examples
Endnotes
Ebooks do not have footnotes, only endnotes. Footnotes are instead converted to endnotes.
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; otherwiseIbid.
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.
Endnotes are referenced in the text by an
<a>
element with the semantic inflectionnoteref
.Noterefs point directly to the corresponding endnote
<li>
element in the endnotes file.Noterefs have an
id
attribute likenoteref-n
, wheren
is identical to the endnote number.The text of the noteref is the endnote number.
If located at the end of a sentence, noterefs are placed after ending punctuation.
If the endnote references an entire sentence in quotation marks, or the last word in a sentence in quotation marks, then the noteref is placed outside the quotation marks.
The endnotes file
Endnotes are in an XHTML file named
./src/epub/text/endnotes.xhtml
.The endnotes file has the
backmatter
semantic inflection.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.Each endnote’s
id
attribute is in sequential ascending order.
Individual endnotes
An endnote is an
<li id="note-n" epub:type="endnote">
element containing one or more block-level text elements and one backlink element.Each endnote’s contains a backlink, which has the semantic inflection
backlink
, contains the text↩
, and has thehref
attribute pointing to the corresponding noteref hash.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.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.
Endnotes with ending citations have those citations are wrapped in a
<cite>
element, including any em-dashes. A space follows the<cite>
element, before the backlink.
Examples
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.
The search key map file is named
./src/epub/glossary-search-key-map.xml
.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.If a
<match>
element only has one<value>
element, the<value>
element is removed in favor of<match value="...">
.
The glossary file
Glossaries are in an XHTML file named
./src/epub/text/glossary.xhtml
.The glossary file has the
backmatter
semantic inflection.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 theglossary
epub:type
attribute be placed on the<dl>
element, in a Standard Ebook it is placed on the<dl>
element’s parent<section>
element.All glossaries include the following CSS:
Glossary entries
The
<dl>
element contains sets of<dt>
and<dd>
elements.The
<dt>
element hasepub:type="glossterm"
.The
<dt>
element contains a single<dfn>
element, which in turn contains the term to be defined.The
<dd>
element hasepub:type="glossdef"
.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>
may appear more than once for a single glossary entry, if different variations of a term have the same definition.