High Level Structural Patterns

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.

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> <p epub:type="title">The Letter Signed “Bella”</p> </hgroup>

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

   <hgroup> <h2 epub:type="title">Between the Scenes</h2> <p epub:type="subtitle">Progress of the Story Through the Post</p> </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> <p epub:type="title">Who Stole the Tarts?</p> </hgroup>

4. Sections titles and subtitles but no ordinals:

   <hgroup> <h2 epub:type="title">An Adventure</h2> <p epub:type="subtitle">(A Driver’s Story)</p> </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> <p epub:type="title">The Man in the Street</p> </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> <p hidden="hidden" epub:type="subtitle">Happy Is England!</p> </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> <p epub:type="subtitle">Some Reminiscences of Sherlock Holmes</p> </hgroup>

12. Headers for sections in which the book’s main author shares a byline:

    <header> <h2 epub:type="title">Happy Ending</h2> <p epub:type="contributors">By Mack Reynolds and Frederic Brown</p> </header>

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:hymn"] [epub|type~="bridgehead"], [epub|type~="z3998:poem"] [epub|type~="bridgehead"], [epub|type~="z3998:song"] [epub|type~="bridgehead"], [epub|type~="z3998:verse"] [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>

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>

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.

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: ''; }

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>

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

Examples

Examples

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

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:

   dl{ margin: 1em 0; } dd{ margin-left: 40px; } 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>