HTMLBook/specification.asciidoc at master · milewska/HTMLBook

HTMLBook Specification: Working Draft (last updated 29 December 2013)

Requirements for HTML5 elements in the HTMLBook specification are below. Special semantic inflections for data-type attributes, unless otherwise noted, come from EPUB 3 Structural Semantics Vocabulary

Many content models refer to "Block elements" or "Inline elements"; please see Block Elements and Inline Elements for the corresponding list of HTML5 elements that belong to each of these categories.

If no content model or attribute requirements are explicitly specified, then HTMLBook adopts the corresponding requirements in the HTML5 Specification

Revision History and Notes

29 December 2013:

Minor revisions for clarity

13 August 2013:

Revised specification for footnote markup

3 July 2013:

Changed spec to use the attribute "data-type" for specifying book-specific semantics instead of "class". The "class" attribute is now free to be used for whatever user-defined semantics are desired, and there are no restrictions on "class" values. Users of the spec may want to replicate "data-type" values in the "class" attribute to facilitate CSS styling, but this is completely optional.

19 April 2013: First release of Working Draft

Book Component elements

Book

HTML element: <body>

Attribute requirements: data-type="book" ^[1]

Content model: First child must be <h1> that contains book title; then zero or more <h2> elements for subtitle content; then one or more Book Component elements as children (<div> for Part elements, <nav> for Table of Contents, and <section> elements for all other book divisions)

Example

<body data-type="book">
  <h1>jQuery Cookbook</h1>
  <section data-type="chapter">
    <!-- Chapter content here -->
  </section>
</body>

Note: Just as in standard HTML5, <body> is a child of the root <html> element.

Chapter

HTML element: <section>

Attribute requirements: data-type="chapter"

Content model: First child must be <h1> that contains chapter title; then zero or more <h2> elements for subtitle content; then zero or more Block Elements; then zero or more Sect1 children (<section data-type="sect1">)

Example

<section data-type="chapter">
  <!-- h1 used for all chapter titles -->
  <h1>Chapter Title</h1>
  <p>Chapter content</p>
  <section data-type="sect1">
    <!-- Section content here... -->
  </section>
</section>

Appendix

HTML element: <section>

Attribute requirements: data-type="appendix" or data-type="afterword", depending on content

Content model: First child must be <h1> that contains appendix title; then zero or more <h2> elements for subtitle content; then zero or more Block Elements; then zero or more Sect1 children (<section data-type="sect1">)

Example

<section data-type="appendix">
  <h1>Appendix Title</h1>
  <p>Appendix content</p>
  <section data-type="sect1">
    <!-- Section content here... -->
  </section>
</section>

Bibliography

HTML element: <section>

Attribute requirements: data-type="bibliography"

Content model: First child must be <h1> that contains bibliography title; then zero or more <h2> elements for subtitle content; then zero or more Block Elements; then zero or more Sect1 children (<section data-type="sect1">)

Example

<section data-type="bibliography">
  <h1>Bibliography Title</h1>
  <p>Bibliography content</p>
  <section data-type="sect1">
    <!-- Section content here... -->
  </section>
</section>

Glossary

HTML element: <section>

Attribute requirements: data-type="glossary"

Content model: First child must be <h1> that contains glossary title; then zero or more <h2> elements for subtitle content; then zero or more Block Elements; then zero or more Sect1 children (<section data-type="sect1">)

Best practices: List of glossary terms should be marked up using <dl> elements with a data-type of "glossary", with <dt> children with a data-type of "glossterm" and <dd> children with a data-type of "glossdef". Term text should be wrapped in a <dfn>. However, none of this is formally required by the spec.

Example

<section data-type="glossary">
  <h1>Glossary Title</h1>
  <dl data-type="glossary">
    <dt data-type="glossterm">
      <dfn>jQuery</dfn>
    </dt>
    <dd data-type="glossdef">
      Widely used JavaScript library
    </dd>
   </dl>
</section>

Preface

HTML element: <section>

Attribute requirements: data-type="preface", data-type="foreword", or data-type="introduction", depending on content

Content model: First child must be <h1> that contains preface title; then zero or more <h2> elements for subtitle content; then zero or more Block Elements; then zero or more Sect1 children (<section data-type="sect1">)

Example

<section data-type="preface">
  <h1>Preface Title</h1>
  <p>Preface content</p>
  <section data-type="sect1">
    <!-- Section content here... -->
  </section>
</section>

Frontmatter

HTML element: <section>

Attribute requirements: data-type="halftitlepage", data-type="titlepage", data-type="copyright-page", or data-type="dedication", depending on content

Content model: First child must be <h1> that contains frontmatter section title; then zero or more <h2> elements for subtitle content; then zero or more Block Elements; then zero or more Sect1 children (<section data-type="sect1">)

Example

<section data-type="titlepage">
  <h1>Python in a Nutshell</h1>
  <p>By Alex Martelli</p>
</section>

Backmatter

HTML element: <section>

Attribute requirements: data-type="colophon", data-type="acknowledgments", data-type="afterword", or data-type="conclusion", depending on content

Content model: First child must be <h1> that contains backmatter section title; then zero or more <h2> elements for subtitle content; then zero or more Block Elements; then zero or more Sect1 children (<section data-type="sect1">)

Example

<section data-type="colophon">
  <h1>Colophon Title</h1>
  <p>Colophon content</p>
  <section data-type="sect1">
    <!-- Section content here... -->
  </section>
</section>

Part

HTML element: <div>

Atttribute requirements: data-type="part"

Content model: First child must be <h1> that contains part title; then zero or more <h2> elements for subtitle content; then zero or more Block Elements that compose the optional Part introduction; then one or more <section> elements representing Book Component children other than a Part

Example

<div data-type="part">
  <h1>Part One: Introduction to Backbone.js</h1>
  <p>Part Introduction...</p>
  <section data-type="chapter">
    <!-- Chapter content here -->
  </section>
</div>

HTML element: <nav>

Attribute requirements: data-type="toc"

Content Model: The TOC must be conformant to the specs for the EPUB 3 Navigation document. First child is zero or more heading elements (<h1>-<h6>), followed by an <ol> (with <li> children that can contain only a <span> element or an <a> element plus an optional <ol> child)

Example

<nav data-type="toc">
  <h1>Table of Contents</h1>
   <ol>
     <li><a href="examples_page.html">A Note Regarding Supplemental Files</a></li>
     <li><a href="pr02.html">Foreword</a></li>
     <li><a href="pr03.html">Contributors</a>
       <ol>
         <li><a href="pr03.html#I_sect1_d1e154">Chapter Authors</a></li>
         <li><a href="pr03.html#I_sect1_d1e260">Tech Editors</a></li>
       </ol>
     </li>
  </ol>
</nav>

Index

HTML element: <section>

Attribute requirements: data-type="index"

Content model: First child must be <h1> that contains index title; then zero or more <h2> elements for subtitle content; then zero or more Block Elements; then zero or more Sect1 children (<section data-type="sect1">)

Best practices: HTMLBook recommends following the EPUB Indexes specification and using <ol>/<li> elements for marking up index entries, with data-type attributes used for semantic inflection as appropriate, but none of this is a formal spec requirement

Example

<section data-type="index">
  <h1>Index Title</h1>
  <div data-type="index:group">
    <h2>A</h2>
    <ol>
      <li data-type="index:term">AsciiDoc, <a href="ch01#asciidoc" data-type="index:locator">All about AsciiDoc</a>
	<ol>
           <li data-type="index:term">conversion to HTML, <a href="ch01#asctohtml" data-type="index:locator">AsciiDoc Output Formats</a></li>
         </ol>
      </li>
      <li data-type="index:term">azalea, <a href="ch01#azalea" data-type="index:locator">Shrubbery</a></li>
    </ol>
  </div>
</section>

Sections

HTML element: <section>

Attribute requirements: data-type="sect1", data-type="sect2", data-type="sect3", data-type="sect4", data-type="sect5" ^[2], depending on hierarchy level. sect1 is used for <section> elements nested directly in main Book components ("chapter", "appendix", etc.). sect2 is used for <section> elements nested in a sect1 <section>, sect3 is used for <section> elements nested in a sect2 <section>, and so on.

Content model: The first child must be a main heading element corresponding to the hierarchy level indicated by data-type value, as follows:

"sect1" -> h1
"sect2" -> h2
"sect3" -> h3
"sect4" -> h4
"sect5" -> h5

The heading is followed by zero or more subheading elements whose hierarchy level is one lower than the main heading (e.g., <h2> for a sect1), folloed by zero or more Block elements, followed by zero or more <section> elements with a data-type value one level lower in the hierarchy, as long as the parent section is a "sect4" or higher (e.g., <section data-type="sect4"> nested in <section data-type="sect3">)

Example:

<section data-type="sect1">
  <h1>A-Head</h1>
  <p>If you httpparty, you must party hard</p>
  <!-- Some more paragraphs -->
  <section data-type="sect2">
    <h2>B-Head</h2>
    <p>What's the frequency, Kenneth?</p>
    <!-- And so on... -->
  </section>
</section>

Block elements

Paragraph

HTML element: <p>

Example:

<p>This is a standard paragraph with some <em>emphasized text</em></p>

Sidebar

HTML element: <aside>

Attribute requirements: data-type="sidebar"

Content model: Zero or one <h5> element that contains the sidebar title); then zero or more Block elements

Example:

<aside data-type="sidebar">
  <h5>Amusing Digression</h5>
  <p>Did you know that in Boston, they call it "soda", and in Chicago, they call it "pop"?</p>
</aside>

Admonitions

HTML element: <div>

Attribute requirements: data-type="note", data-type="warning", data-type="tip", data-type="caution", or data-type="important", depending on the content within

Content model: Either of the following content models is acceptable:

text and/or zero or more Inline elements
Zero or more <h1>-<h6> elements (for title and subtitles), followed by zero or more Block elements

Examples:

<div data-type="note">
  <h1>Helpful Info</h1>
  <p>Please take note of this important information</p>
</div>

<div data-type="warning">Make sure to get your AsciiDoc markup right!</div>

Tables

HTML element: <table>

Content model: Zero or one <caption> elements (for titled/captioned tables); then zero or more <colgroup> elements; then zero or more <thead> elements; then a choice between either zero or more <tbody> elements, or zero or more <tr> elements; then zero or more <tfoot> elements

Content model for <caption>: Either of the following is acceptable:

Zero or more <p> and/or <div> elements
Text and/or zero or more Inline elements

Content model for <colgroup>: Mirrors HTML5 Specification

Content models for <thead>, <tbody>, and <tfoot>: Mirror HTML5 Specification

Content model for <tr>: Mirrors HTML5 Specification, but see content model below for rules for child <td> and <th> elements

Content model for <td> and <th> elements: Either of the following is acceptable:

text and/or zero or more Inline elements
Zero or more Block elements

Examples:

<table>
<caption>State capitals</caption>
<tr>
  <th>State</th>
  <th>Capital</th>
</tr>
<tr>
  <td>Massachusetts</td>
  <td>Boston</td>
</tr>
<!-- And so on -->
</table>

<table>
  <thead>
    <tr>
      <th>First</th>
      <th>Middle Initial</th>
      <th>Last</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Alfred</td>
      <td>E.</td>
      <td>Newman</td>
    </tr>
    <!-- And so on -->
  </tbody>
</table>

Figures

HTML element: <figure>

Content model: Either of the following is acceptable:

A <figcaption> element followed by zero or more Block elements and/or <img> elements
Zero or more Block elements and/or <img> elements, followed by a <figcaption> element

Example:

<figure>
<figcaption>Adorable cat</figcaption>
<img src="cute_kitty.gif" alt="Photo of an adorable cat"/>
</figure>

Examples

HTML element: <div>

Attribute requirements: data-type="example"

Content model: Either of the following content models is acceptable:

text and/or zero or more Inline elements
Zero or more <h1>-<h6> elements (for title and subtitles), followed by zero or more Block elements

Example:

<div data-type="example">
<h5>Hello World in Python</h5>
<pre data-type="programlisting">print "Hello World"</pre>
</div>

Code listings

HTML element: <pre>

Optional HTMLBook-specific attribute: data-code-language, used to indicate language of code listing (e.g., data-code-language="python")

Example:

<pre data-type="programlisting">print "<em>Hello World</em>"</pre>

Ordered lists

HTML element: <ol>

Content model: Zero or more <li> children for each list item

Content model for <li> children: Either of the following is acceptable:

text and/or zero or more Inline elements
Zero or more Block elements

Example:

<ol>
<li>Step 1</li>
<li>
  <p>Step 2</p>
  <p>Step 2 continued</p>
</li>
<!-- And so on -->
</ol>

Itemized lists

HTML element: <ul>

Content model: Zero or more <li> children for each list item

Content model for <li> children: Either of the following is acceptable:

text and/or zero or more Inline elements
Zero or more Block elements

Example:

<ul>
<li>Red</li>
<li>Orange</li>
<!-- And so on -->
</ul>

Definition lists

HTML element: <dl>

Content model: Mirrors HTML5 Specification

Content model for <dt> children: text and/or zero or more Inline elements

Content model for <dd> children: Either of the following is acceptable:

text and/or zero or more Inline elements
Zero or more Block elements

Example:

<dl>
  <dt>Constant Width Bold font</dt>
  <dd>Used to indicate user input</dd>
</dl>

Blockquote

HTML element: <blockquote>

Content model: Either of the following is acceptable:

text and/or zero or more Inline elements
Zero or more Block elements

Example:

<blockquote data-type="epigraph">
  <p>When in the course of human events...</p>
  <p data-type="attribution">U.S. Declaration of Independence</p>
</blockquote>

Headings

HTML elements: <h1>, <h2>, <h3>, <h4>, <h5>, or <h6>

Content Model: text and/or zero or more Inline elements

Notes: Many main book components (e.g., chapters, parts, appendixes) require headings. The appropriate element from <h1>-<h6> is outlined below, as well as in the corresponding documentation for these components:

book title -> h1
part title -> h1
chapter title -> h1
preface title -> h1
appendix title -> h1
colophon title -> h1
dedication title -> h1
glossary title -> h1
bibliography title -> h1
sect1 title -> h1
sect2 title -> h2
sect3 title -> h3
sect4 title -> h4
sect5 title -> h5
sidebar title -> h5

Equation

HTML element: <div>+

Attribute requirements: data-type="equation" ^[3]

*Note: HTMLBook supports embedded MathML in HTML content documents, which can be used here.

Example:

<div data-type="equation">
<h5>Pythagorean Theorem</h5>
<math xmlns="http://www.w3.org/1998/Math/MathML">
  <msup><mi>a</mi><mn>2</mn></msup>
  <mo>+</mo>
  <msup><mi>b</mi><mn>2</mn></msup>
  <mo>=</mo>
  <msup><mi>c</mi><mn>2</mn></msup>
</math>
</div>

Inline Elements

Emphasis (generally for italic)

HTML element: <em>

Example:

<p>I <em>love</em> HTML!</p>

Strong (generally for bold)

HTML element: <strong>

Example:

<p>I <strong>love</strong> HTML!</p>

Literal (for inline code elements: variables, functions, etc.)

HTML element: <code>

Example:

<p>Enter <code>echo "Hello World"</code> on the command line</p>

General-purpose phrase markup for other styling (underline, strikethrough, etc.)

HTML element: <span>

Example:

<p>Use your own +data-type+ or +class+ attributes for custom styling for formatting like <span data-type="strikethrough">strikethrough</span></p>

Footnote, endnote

HTML element: <span>

Attribute requirements: data-type="footnote"

*Content model for footnote: text and/or zero or more Inline elements

Example:

<p>Five out of every six people who try AsciiDoc prefer it to Markdown<span data-type="footnote">Totally made-up statistic</span></p>

Notes:

The <span> element does not accept block element children (and as of 2013-08-13, nor does any other HTML5 element that can be used in an inline context and is an acceptable semantic fit for footnotes)). If you need to include multiple blocks of content in a footnote, use <br/> elements to delimit them, e.g.:

<p>This is a really short paragraph.<span data-type="footnote">Largely because I like to put lots and lots of content in footnotes.<br/><br/>For example, let me tell you a story about my dog...</span></p>

Desired rendering of footnote content (i.e., floating/moving footnotes to the bottom of a page or end of a section, adding appropriate marker symbols/numeration) should be handled by XSL/CSS stylesheet processing.

Cross-references

HTML element: <a>

Attribute requirements: data-type="xref"+footnote:[From DocBook]; an +href attribute that should point to the id of a local HTMLBook resource referenced; data-xrefstyle (optional) for specifying the style of XREF

Example:

<section id="html5" data-type="chapter">
  <h1>Intro to HTML5<h1>
  <p>As I said at the beginning of <a data-type="xref" href="#html5">Chapter 1</a>, HTML5 is great...</p>
  <!-- Blah blah blah -->
</section>

Index Term

HTML element: <a>

Attribute requirements: data-type="indexterm"; for primary index entry value, use data-primary; for secondary index entry value, use data-secondary; for tertiary index entry value, use data-tertiary; for a "see" index reference, use data-see; for a "see also" index reference, use data-seealso; for a "sort" value to indicate alphabetization, use data-primary-sortas, data-secondary-sortas, or data-tertiary-sortas; for an "end-of-range" tag that marks the end of an index range, use +data-startref="id_of_opening_index_marker"+^[4]

Content model: Empty

Example:

<p>The Atlas build system<a data-type="indexterm" data-primary="Atlas" data-secondary="build system"/> lets you build EPUB, Mobi, PDF, and HTML content</p>

Superscripts

HTML element: <sup>

Example:

<p>The area of a circle is πr<sup>2</sup></p>

Subscripts

HTML element: <sub>

Example:

<p>The formula for water is H<sub>2</sub>O</p>

Interactive Elements

Video

HTML element: <video>

Example:

Note: Fallback content is strongly recommended for output formats that do not support HTML5 interactive content

<video id="asteroids_video" width="480" height="270" controls="controls" poster="images/fallback_image.png">
<source src="video/html5_asteroids.mp4" type="video/mp4"/>
<source src="video/html5_asteroids.ogg" type="video/ogg"/>
<em>Sorry, the &lt;video&gt; element not supported in your
  reading system. View the video online at http://example.com.</em>
</video>

Audio

HTML element: <audio>

Note: Fallback content is strongly recommended for output formats that do not support HTML5 interactive content

Example:

<audio id="new_slang">
<source src="audio/new_slang.wav" type="audio/wav"/>
<source src="audio/new_slang.mp3" type="audio/mp3"/>
<source src="audionew_slang.ogg" type="audio/ogg"/>
<em>Sorry, the &lt;audio&gt; element is not supported in your
  reading system. Hear the audio online at http://example.com.</em>
</audio>

Canvas

HTML element: <canvas>

Notes: Should include fallbacks for environments that don’t support HTML5 or JavaScript (e.g., link or image). You may include <script> elements in your HTMLBook document <head> elements to include/reference JS code for Canvas handling.

Examples:

<canvas id="canvas" width="400" height="400">
 Your browser does not support the HTML 5 Canvas. See the interactive example at http://example.com.
</canvas>

Metadata

Metadata points

HTML element: <meta>

Attribute requirements: name (for name of metadata point); content: (for value of metadata point)

Content model: Empty

Note: All <meta> elements must be children of the <head> element of the HTML file.

Example:

<head>
  <title>Title of the Book</title>
  <meta name="isbn-13" content="9781449344856"/>
</head>

Element Classification

Block elements

In HTMLBook, the majority of elements classified by the HTML5 specification as Flow content (minus elements also categorized as Heading Content, Phrasing Content, and Sectioning Content) are considered to be Block elements. Here is a complete list:

<address>
<aside>
<audio>
<blockquote>
<canvas>
<details>
<div>
<dl>
<embed>
<fieldset>
<figure>
<form>
<hr>
<iframe>
<map>
<math> (In MathML vocabulary; must be namespaced under http://www.w3.org/1998/Math/MathML)
<menu>
<object>
<ol>
<p>
<pre>
<svg> (In SVG vocabulary; must be namespaced under http://www.w3.org/2000/svg)
<table>
<ul>
<video>

Inline elements

In HTMLBook, the majority of elements classified by the HTML5 specification as Phrasing Content are considered to be Inline elements. Here is a complete list:

<a>
<abbr>
<b>
<bdi>
<bdo>
<br>
<button>
<command>
<cite>
<code>
<datalist>
<del>
<dfn>
<em>
<i>
<input>
<img>
<ins>
<kbd>
<keygen>
<label>
<mark>
<meter>
<output>
<progress>
<q>
<ruby>
<s>
<samp>
<select>
<small>
<span>
<strong>
<sub>
<sup>
<textarea>
<time>
<u>
<var>
<wbr>

1. Not in EPUB 3 Structural Semantics Vocabulary; from DocBook

2. From DocBook vocabulary

3. From DocBook; no close match in EPUB 3 Structural Semantics Vocabulary

4. Semantics from DocBook

FilesExpand file tree

specification.asciidoc

Latest commit

History

specification.asciidoc

File metadata and controls

HTMLBook Specification: Working Draft (last updated 29 December 2013)

Revision History and Notes

Book Component elements

Book

Chapter

Appendix

Bibliography

Glossary

Preface

Frontmatter

Backmatter

Part

Table of Contents

Index

Sections

Block elements

Paragraph

Sidebar

Admonitions

Tables

Figures

Examples

Code listings

Ordered lists

Itemized lists

Definition lists

Blockquote

Headings

Equation

Inline Elements

Emphasis (generally for italic)

Strong (generally for bold)

Literal (for inline code elements: variables, functions, etc.)

General-purpose phrase markup for other styling (underline, strikethrough, etc.)

Footnote, endnote

Cross-references

Index Term

Superscripts

Subscripts

Interactive Elements

Video

Audio

Canvas

Metadata

Metadata points

Element Classification

Block elements

Inline elements