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 <articles> elements that are semantic children of <section> or <articles> elements in other files, are wrapped in stubs of all parent <section> or <articles> elements, up to the root.

2. Each such included parent element has the identical id and epub:type attributes of its real counterpart.

Header patterns

1. Sections without titles:

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

2. Sections with titles but no ordinal (i.e. chapter) numbers:

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

3. Sections with titles and ordinal (i.e. chapter) numbers:

   span[epub|type~="subtitle"]{ display: block; font-weight: normal; }

   <h2 epub:type="title"> <span epub:type="z3998:roman">XI</span> <span epub:type="subtitle">Who Stole the Tarts?</span> </h2>

4. Sections titles and subtitles but no ordinal (i.e. chapter) numbers:

   span[epub|type~="subtitle"]{ display: block; font-weight: normal; }

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

5. Sections that have a non-unique title, but that are required to be identifed in the ToC with a unique title (e.g., multiple poems identified as “Sonnet” in the body matter, which require their ToC entry to contain the poem’s first line to differentiate them):

   span[epub|type~="subtitle"]{ display: block; font-weight: normal; }

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

6. Sections that require titles, but that are not in the table of contents:

   header{ font-variant: small-caps; margin: 1em; text-align: center; }

   <header> <p>The Title of a Short Poem</p> </header>

7. Half title pages without subtitles:

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

8. Half title pages with subtitles:

   section[epub|type~="halftitlepage"] span[epub|type~="subtitle"]{ display: block; font-size: .75em; font-weight: normal; }

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

Bridgeheads

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

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

2. Bridgeheads have the following CSS and HTML structure:

   [epub|type~="bridgehead"]{ display: inline-block; font-style: italic; max-width: 60%; text-align: justify; text-indent: 0; } [epub|type~="bridgehead"] i{ font-style: normal; }

   <header> <h2 epub:type="title z3998:roman">I</h2> <p epub:type="bridgehead">Which treats of the character and pursuits of the famous gentleman Don Quixote of La Mancha.</p> </header>

   <header> <h2 epub:type="title z3998:roman">X</h2> <p epub:type="bridgehead">Our first night⁠wj—Under canvas⁠wj—An appeal for help⁠wj—Contrariness of teakettles, how to overcome⁠wj—Supper⁠wj—How to feel virtuous⁠wj—Wanted! a comfortably-appointed, well-drained desert island, neighbourhood of South Pacific Ocean preferred⁠wj—Funny thing that happened to George’s father⁠wj—A restless night.</p> </header>

Epigraphs in section headers

1. Epigraphs in section headers have the quote source in a <cite> element set in small caps, without a leading em-dash and without a trailing period.

   <header> <h2 epub:type="title z3998:roman">II</h2> <blockquote epub:type="epigraph"> <p>“Desire no more than to thy lot may fall. …”</p> <cite>—Chaucer.</cite> </blockquote> </header>

   header [epub|type~="epigraph"] cite{ font-variant: small-caps; }

   <header> <h2 epub:type="title z3998:roman">II</h2> <blockquote epub:type="epigraph"> <p>“Desire no more than to thy lot may fall. …”</p> <cite>Chaucer</cite> </blockquote> </header>

2. In addition to the CSS used for all epigraphs, this additional CSS is included for epigraphs in section headers:

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

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: left; } @supports(display: flex){ section[epub|type~="epigraph"]{ align-items: center; box-sizing: border-box; display: flex; flex-direction: column; justify-content: center; min-height: calc(98vh - 3em); padding-top: 3em; } section[epub|type~="epigraph"] > *{ margin: 0; } section[epub|type~="epigraph"] > * + *{ margin-top: 3em; } } /* End full-page epigraphs */

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

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

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

3. 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: "]"; }

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

5. 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 epub:type="title">Act <span epub:type="z3998:roman">I</span></h2> <p>Scene: Morning-room in Algernon’s flat in Half-Moon Street. The room is luxuriously and artistically furnished. The sound of a piano is heard in the adjoining room.</p> <table> ... </table> <p epub:type="z3998:stage-direction">Act Drop</p> </section> </body>

4. Dramatis personae are presented as a <ul> element listing the characters.

   [epub|type~="z3998:dramatis-personae"]{ text-align: center; } [epub|type~="z3998:dramatis-personae"] ul{ list-style: none; margin: 0; padding: 0; } [epub|type~="z3998:dramatis-personae"] ul li{ margin: 1em; font-style: italic; }

   <section id="dramatis-personae" epub:type="z3998:dramatis-personae"> <h2 epub:type="title">Dramatis Personae</h2> <ul> <li> <p>King Henry <span epub:type="z3998:roman">V</span></p> </li> <li> <p>Duke of Clarence, brother to the King</p> </li> ... </ul> </section>

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

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 signature class and the corresponding .signature CSS.

   .signature{ font-variant: small-caps; }

   <footer> <p epub:type="z3998:sender" class="signature"><abbr class="name">R. A.</abbr> Johnson</p> </footer>

   <footer> <p epub:type="z3998:sender"><span class="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: left; }

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 are 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:

   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>