Fulcrum EPUB Specification

Revision History

Rev Num	Release Date	Changes	Author
1.0	May. 12, 2018	Beta Release to UM Full Spec Internal	Arthic Leo A E
1.0b1	July 16, 2018	Beta release version 2.0	Arthic Leo A E
1.0b2	July 24, 2018	Beta release version 3.0	Arthic Leo A E
1.0b3	July 24, 2018	Beta release version 3.0	G Suprock
1.0b4	Aug. 21, 2018	Beta release version 4.0	G Suprock
1.1rc1	Sept 20, 2018	Release candidate 1.0	J McGlone
2.0	Dec 20, 2018	Release to web	J McGlone
2.1	Feb 7, 2018	Removed non-spec material, added code block spec (1.16)	J McGlone
2.2	May 14, 2019	HELIO-2661	[email protected]
2.3	Jan. 15, 2020	HELIO-3146	[email protected]
2.4	April 15, 2020	HELIO-2651	[email protected]
2.5	June 9, 2021	Clarify use of page numbering and paragraph numbering	J McGlone
2.6	November 10, 2021	FULCRUMOPS-33	[email protected]

1.0 Target Specification -- EPUB3

1.1 EPUB Version

EPUB version 3.0.1 is the recommended technical specification for EPUB created for submission to Fulcrum. Please note this document does not repeat conformance requirements contained in the official specification. However, recommended features regarding file and directory structure, naming conventions, treatments for images, treatments for metadata, and other such file preparation details are included.

The full EPUB 3.0.1 specification is located here: [http://idpf.org/epub/301.

International Digital Publishing Form (IDPF) guidelines for reflowable digital books and publications.
ePub validated against ePubCheck version 4.0.2 (http://code.google.com/p/epubcheck/)
XHTML files compliant with XHTML 1.1 DTD
XHTML files validated with CSE HTML validator version 10.0

1.2 Element Specification

The following matrix details recommendations how to convert different elements. The treatments are optional for third-party partners to University of Michigan.

1.2.1 Standard Functionality Levels (ePub 3) for PDF source

Element	Conversion
Parts/Chapters	All Heading Levels
Graphics + Captions	Image + Text
Tables + Captions	Text
Sidebars	Text
Display Math	MathML
In-line Math	Text (if keyable) / MathML (non-keyable)
Lists	Text
Footnotes/Endnotes	Bi-directional text
Poems	Text
Plays/Dialog	Text
Non-keyboard Characters	Unicode
Drop cap	Text
Cover	Image
Title Page	Text
About the Author	Text
Acknowledgements	Text
Copyright Page	Text
Table of Contents	Bi-directional
Lists of Tables/Figs, etc.	Text with bi-directional links
Dedications/Epigraphs	Text
Foreword/Introduction/Preface	Text
References/Bibliography	Text
Glossary/Appendix	Text
Index	Text with links

Note: If the input is ePub, then output should be in the same format.

1.3 File Name

The EPUB3 output file name will be the 13-digit ISBN number of the same input file name for Apex Production.

The use of the 13-digit ISBN number of the source file is optional for third-party partners to University of Michigan. However, file naming conventions must be consistent across titles submitted to the university.

1.4 Folder Structure

The following folder structure is required for Apex deliverables to the University of Michigan. The folder structure below is optional for third-party partners to University of Michigan. However, folder structure conventions must be consistent across titles submitted to the university.

The EPUB should conform to the following directory structure and naming convention.

/META-INF
    container.xml
/OEBPS
    /xhtml/xxy_Filename.xhtml
    content.opf
    /fonts
        Fontname.fontextension
    /images
        cover.imgextension
        figname.imgextension
    /styles
        page-template.xpgt
        stylesheet.css
    toc.ncx
mimetype

Where,

xx = A sequential numeric book part identifier beginning with 00 and incrementing by 1 (e.g., 00, 01, 02, 03, and so on)
y = An optional alphabetic section identifier used when book parts contain large numbers of image files (e.g., 01a, 01b, 01c, and so on)
Filename = A human readable book part name (e.g., Nav, Cover, Title, Contents, Chapter01
Fontname = A font file name (e.g., MinionPro-Regular)
fontextension = A font file extension (e.g., ttf)
figname = Figure name. Please do not modify this name, as it may be an identifier for accessing associated metadata.
imgextension = An image file extension (e.g., jpg, png)
stylesheet = A human readable CSS stylesheet name.

1.4.1 Optional File Inclusions

Additional inclusions supporting alternative EPUB Reader systems, such as ibooks and the com.apple.ibooks.display-options.xml file, is permissible and will not interfere with the Fulcrum viewer.

If such files are in source, they will be in the deliverable EPUB3.

1.5 EPUB Package

The EPUB3 output contains the following folders and files.

XHTML files
Image files
toc.ncx
mimetype
container.xml
content.opf
Stylesheet (CSS)
Embedded Fonts (Only if approved by customer)

1.6 Metadata

1.6.1 Dublin Core

Dublin Core metadata is required for the following items:

Title
Creator
Language
Rights
Publisher
Identifier
Source (Required when the EPUB is a derivative of a print source.)

Example code:

<dc:title>A Mid-Republican House from Gabii</dc:title>
<dc:creator>Rachel Opitz</dc:creator>
<dc:creator>Marcello Mogetta</dc:creator>
<dc:creator>Nicola Terrenato</dc:creator>
<dc:language>en-US</dc:language>
<dc:rights>© University of Michigan Press</dc:rights>
<dc:publisher>University of Michigan Press</dc:publisher>
<dc:identifier id="BookID">9780472999002</dc:identifier>
<dc:sourceid="src-id">urn:isbn:9780472999999</dc:source>
<meta refines="#src-id" property="dcterms:issued">2000-01-01</meta>
<dc:date>2018-03-03</dc:date>

1.7 Accessibility Metadata

Include the two types of accessibility metadata structure defined in the current EPUB environment as listed below.

ONIX: http://kb.daisy.org/publishing/docs/metadata/onix.html

Use ONIX only when creating a separate ONIX metadata XML to place in the /meta folder of the EPUB.

Schema: http://kb.daisy.org/publishing/docs/metadata/schema-org.html

1.8 HTML Meta Header

For Apex created EPUBs, the follow meta tags will be placed inside the <head> tag in all the XHTML files. The meta tags are optional for third-party partners to University of Michigan.

<meta name="viewport" content="initial-scale=1.0,maximum-scale=5.0"/>
<meta content=" " name=" " role="section"/>

The chapter id should be provided as value for content attribute and the type of the section should be provided under name attribute. For example:

<meta content="dedication" name="dedication" role="section"/>
<meta content="chapter04" name="chapter04" role="section"/>

1.9 Bookmark

Bookmark each ePUB as follows:

Cover
Title
- Note: If there are multiple title pages, label the bookmarks "Title Page" and "Original Title Page".
Half Title
Copyright
- Note: If there are multiple copyright pages (e.g., the Routledge Revivals imprint which contains the original copyright page usually from the 1800s), the bookmarks are to be labeled "Copyright Page" and "Original Copyright Page".
Dedication
Table of Contents
- Note to Production: If the Table of Contents is missing for a title, raise a JIRA ticket to see if the client can resupply the file. If not, construct the bookmarks from the Chapter Titles.
All book sections listed in the Table of Contents
All Lists of Tables, Figures, Illustrations, Maps, etc.
Appendices
Indexes

1.10 Html Title

HTML titles are a best practice recommendation, and, required for Apex EPUB deliveries. However, HTML titles are optional for third-party partners to University of Michigan.

Assigning meaningful titles is a recommended best practice for <title> elements in the EPUB. Such titles help all users to find and navigate through the documents, and, are essential for screen reader users.

Example 1 --- One chapter/part per HTML

<html ...>
<title>Chapter 1 --- Hobo's Guide to the Universe</title>

Example 2 --- Multiple HTML files for one chapter/part

If a document is split into multiple HTML files, the following method should be followed.

<html ...>
<title>Chapter 1 - Continued (2 of 3) --- Hobo's Guide to the Universe</title>

1.11 Headings

Apply heading tags as per the HTML element for the headings. Based on the heading levels, apply heading tags ranging from h1 to h6 as needed.

1.11.1 Numbered headings

<section role="doc-part">
<h1>Book One: 1805</h1>
<section role="doc-part">
<h2>Part 1</h2>
<section role="doc-chapter">
<h3>Chapter 1</h3>

1.11.2 Separate heading and subtitle

The title and subtitle are contained in separate elements, but grouped in a header element to better associate them. Use the role doc-subtitle to identify the subtitle.

<section role="doc-chapter">
<header>
<h1>ORIGIN OF THE WORLD.---FIRST DYNASTY.</h1>
<p role="doc-subtitle">URANUS AND GÆA. (Cœlus and Terra.)</p>
</header>

1.11.3 Merged heading and subtitle

When the subtitle is contained within the same heading element as the title, identify it in a span with the role of doc-subtitle.

<section role="doc-chapter">
<h1>ORIGIN OF THE WORLD.---FIRST DYNASTY.
<span role="doc-subtitle">URANUS AND GÆA. (Cœlus and Terra.)</span>
</h1>

1.12 Tables

Tag tables as per the table structure. If any of the tables exceeding more than 5 columns are captured as image to accommodate the device restriction [Insert Cross-reference for Image treatment of tables], then the table should be coded with proper table tagging and referred to the particular table image through aria-label attribute. This will help the screen reader users to perceive the full table information as an alternative to the image.

Tables that have a title should use the caption element. Headers should be contained within a thead element and footers within a tfoot element. The rows that represent the body of the table should be contained within a tbody element.

1.12.1 Irregular header

The following table has headers that span columns and rows:

Shipping.		Stock.	Wages.		Weights.		Name of Colony.
Book, page.	Appx, page.	Stock.	Book, page.	Appx, page.	Book, page.	Appx, page.	Name of Colony.

To make these headings accessible, use colgroup elements with the scope attribute:

<table border="1">
<colgroup span="2"/>
<colgroup span="1"/>
<colgroup span="2"/>
<colgroup span="2"/>
<colgroup span="1"/>
<thead>
<tr>
<th id="ship" colspan="2" scope="colgroup">Shipping.</th>
<th id="stock" rowspan="2" scope="colgroup">Stock.</th>
<th id="wages" colspan="2" scope="colgroup">Wages.</th>
<th id="wt" colspan="2" scope="colgroup">Weights.</th>
<th id="name" rowspan="2" scope="colgroup">Name of Colony.</th>
</tr>
<tr>
<th scope="col">Book, page.</th>
<th scope="col">Appx, page.</th>
<th scope="col">Book, page.</th>
<th scope="col">Appx, page.</th>
<th scope="col">Book, page.</th>
<th scope="col">Appx, page.</th>
</tr>
</thead>
<tbody>
...
</tbody>
</table>

1.12.2 Complex headings

The following table shows a distance chart with the start destinations defined in the first row and at the end destination at the end of each subsequent row:

Vancouver	Calgary	Saskaton	Winnipeg	Toronto	Montreal	St. John's
7323	6334	5838	5010	3141	2602		St. John's
4271	3743	3232	2408	539		2602	Montreal

Use scope="col" to make the start destinations the column headers and scope="row" to make the end destinations the row headers:

<table border="1">
<thead>
<tr>
<th scope="col">Vancouver</th>
<th scope="col">Calgary</th>
<th scope="col">Saskaton</th>
<th scope="col">Winnipeg</th>
<th scope="col">Toronto</th>
<th scope="col">Montreal</th>
<th scope="col">St. John's</th>
<td></td>
</tr>
</thead>
<tbody>
<tr>
<td class="center">7323</td>
<td class="center">6334</td>
<td class="center">5838</td>
<td class="center">5010</td>
<td class="center">3141</td>
<td class="center">2602</td>
<td class="center"></td>
<th scope="row">St. John's</th>
</tr>
<tr>
<td class="center">4271</td>
<td class="center">3743</td>
<td class="center">3232</td>
<td class="center">2408</td>
<td class="center">539</td>
<td class="center"></td>
<td class="center">2602</td>
<th scope="row">Montreal</th>
</tr>
</tbody>
</table>

1.12.3 Layered headings

The following table combines headers from the top of each column and beginning of each row:

Table IX.4 Income Distribution Among Families 1929-1997

% Families	1929		1970		1997
Lowest 20%	3.5%	3.5%	5.5%	5.5%	4.2%	4.2%

The headers attribute is used to provide the IDs of the cells that contain the relevant heading text:

<table border="1">
<caption>Table IX.4 Income Distribution Among Families 1929-1997</caption>
<thead>
<tr>
<th id="t4-pct">% Families</th>
<th id="t4-1929" colspan="2">1929</th>
<th id="t4-1970" colspan="2">1970</th>
<th id="t4-1997" colspan="2">1997</th>
</tr>
</thead>
<tbody>
<tr>
<th id="t4-low20">Lowest 20%</th>
<td headers="t4-1929 t4-low20">3.5%</td>
<td headers="t4-1929 t4-low20">3.5%</td>
<td headers="t4-1970 t4-low20">5.5%</td>
<td headers="t4-1970 t4-low20">5.5%</td>
<td headers="t4-1997 t4-low20">4.2%</td>
<td headers="t4-1997 t4-low20">4.2%</td>
</tr>
</tbody>
</table>

1.13 Lists

Tag list items with proper list tags. Do not use other elements such as . By tagging the list items with proper list elements, the screen reader users can perceive meaningful information and will know that they are reading list items.

1.13.1 Unordered list

<ul>
<li>Credit, consumer, 164</li>
<li>Cross-functional contact, 10-11</li>
<li>Culture
<ul>
<li>buyer behavior and, 85</li>
<li>defined, 85, 98, 118</li>
...
</ul>
</li>
...
</ul>

Excerpt from: Core Concepts of Marketing --- John Burnett

1.13.2 Definition list

Definition list tagging is required for Apex EPUB deliveries, but considered optional for third-party partners to University of Michigan.

<dl>
<dt><def>Exchange function</def></dt>
<dd>
Sales of the product to the various members
of the channel of distribution.
</dd>
<dt><def>Physical distribution function</def></dt>
<dd>
Moves the product through the exchange
channel, along with title and ownership.
</dd>
<dt><def>Marketing channel</def></dt>
<dd>
Sets of independent organizations involved
in the process of making a product or
service available for use or consumption
as well as providing a payment mechanism
for the provider.
</dd>
...
</dl>

Excerpt from: Core Concepts of Marketing --- John Burnett

1.14 Links

The recommended best practice is to include links as meaningful text if the surrounding text is inadequate to define the purpose of the link. By providing meaningful text interpretation, the screen reader user can understand the purpose of the link and decide if they need to navigate to that particular link.

1.14.1 Links spec

All the cross-references such as table of contents, notes and footnotes are two-way linked. Other references such as page, section, figure, etc., are one-way linked. The web address and email address links are active.

1.14.2 Link with full context of destination

The user can determine the destination of the link from the text of the <a> element alone.

<p>For more information, refer to <a href="#...">Section 1.1 of Web Publications</a></p>

1.14.3 Link with alternate text

Adding alternate text is an optional best practice if neither of the above conditions are met. Use the aria-label attribute to provide additional context.

<a href="#..." aria-label="The EPUB specifications">click here</a>

1.14.4 Link format for DOIs

When using DOIs in any section of the EPUB, the title of the publication should be included in an aria-label attribute. See the CrossRef Accessibility Guidelines for more details.

<a href="https://doi.org/10.5555/12345678" aria-label="DOI for Toward a Unified Theory of High-Energy Metaphysics: Silly String Theory">https://doi.org/10.5555/12345678</a>

1.14.5 Visual distinctive linking

Bold Text Option: By specifying bolder, either a medium font or a bold one will make links visually stand out from their surrounding text.

a {
    text-decoration: none;
    font-weight: bolder;
    color: rgb(51,102,204);
  }

Dotted Border Option: A dotted border is placed under all links to highlight them instead of a line.

a {
    text-decoration: none;
    padding-bottom: 0.3rem;
    border-bottom: 0.1rem dotted rgb(100,100,100);
  }

1.15 Images

The name assigned to an image file contained within the EPUB should not contain spaces. The underscore character may be used.

Images should have an alternate text (img/@alt attribute) for the screen reader users. By providing an alternate text for non-visual content, the screen reader users can perceive information about the image through the alternate text provided by us.

1.15.1 Significant simple image (no description required)

<img src="covers/9781449328030_lrg.jpg" alt="Accessible EPUB 3 - First Edition"/>

1.15.2 Decorative image

An empty alt attribute is complimented by the role presentation to indicate that the image contains no information for users.

<img src="graphics/gothic-border.png" role="presentation" alt=""/>

1.15.3 Figures

For a group that consists of an image and an associated caption, the figure and figcaption elements should be used. One or more img elements may exist within the figure element, but only one figcaption element should exist. The figcaption element should exist after its associated img element(s). Below is an example:

<figure role="group">
    <img src="chart1.png" 
         alt="Bar chart showing monthly and total visitors for 
            the first quarter 2014 for sites 1 to 3"/>
    <img src="chart2.png" 
        alt="Bar chart showing monthly and total visitors for 
            the first quarter 2014 for sites 4 to 6"/>
    <figcaption>
    Example.com Site visitors Jan to March 2014 text description of the bar chart
    </figcaption>
</figure>

Note: the img element should be a direct child of the figure element and not wrapped within another container such as a p or a div.

If multiple images and captions are to be grouped together, then nested figure elements are to be used. Below is an example:

<figure role="group" aria-labelledby="fig1">
    <figure role="group" aria-labelledby="fig11">
        <img src="castle-etching.jpg"
	        alt="The castle has one tower, and a tall wall around it.">
        <figcaption id="fig11">
        Charcoal on  wood. Anonymous, circa 1423.
        </figcaption>
    </figure>
    <figure role="group" aria-labelledby="fig12">
        <img src="castle-painting.jpg"
	        alt="The castle now has two towers and two walls.">
        <figcaption id="fig12">
        Oil-based paint on canvas. Eloisa Faulkner, 1756.
        </figcaption>
    </figure>
    <figure role="group" aria-labelledby="fig13">
        <img src="castle-fluro.jpg"
	        alt="The castle lies in ruins, the original tower all that remains in one piece.">
        <figcaption id="fig13">
        Film photograph. <span lang="fr">Séraphin Médéric Mieusement</span>, 1936.
        </figcaption>
    </figure>
    <figcaption id="fig1">
    The castle through the ages: 1423, 1756, and 1966 respectively.
    </figcaption>
</figure>

1.15.4 Extended description via hyperlink

Extended description inclusion and linking via a hyperlink are optional unless provided in the source.

The following example uses simple hyperlinks to link to a note at the end of the chapter.

The descriptions could also be located in a separate file, but this might have a performance impact for users (i.e., it will require the reading system to unload and reload each document each time the user follows a link).

An image could also be used to minimize the appearance of the link, but some reading systems have issues with such links.

<figure id="fig-01">
    <img src="graphics/water-cycle.jpg"
        alt="The hydrologic cycle, showing the
        circular nature of the process as water
        evaporates from a body of water and
        eventually returns to it"/>
    <figcaption>
    The hydrologic cycle. <a role="doc-noteref" href="#desc-01">Description</a>
    </figcaption>
</figure>
...
<h2>Image Descriptions</h2>
<aside role="doc-footnote" id="desc-01">
    <p>
        <a role="doc-backlink" href="#fig-01">Figure 1.</a>
        --- The diagram shows
        the processes of evaporation, condensation,
        evapotranspiration, water storage in ice and snow, and
        precipitation. A large body of water ...
    </p>
</aside>

1.15.5 Fulcrum Resource References

Once an EPUB is ingested in the Fulcrum platform, images referenced within EPUB content may be used to reference resources ingested in the platform. The img element may be replaced with markup that displays a resource such as a higher resolution image, audio, or video. The basename of the path (minus the extension) specified in the img/@src attribute should match the basename of the resource. For example:

<figure role="group">
    <img src="images/movie_trailer.jpg" 
         alt="Static image representing the movie trailer"/>
    <figcaption>
    Trailer for the movie.
    </figcaption>
</figure>

The path images/movie_trailer.jpg could match a video resource ingested in the Fulcrum platform that has the file name movie_trailer.mp4.

For the case where the img/@src value matches an ingested resource, but this instance should not be replaced, then the img/@data-fulcrum-embed attribute can be added to the img element:

<figure role="group">
    <img src="images/movie_trailer.jpg" 
         data-fulcrum-embed="false"
         alt="Static image representing the movie trailer"/>
    <figcaption>
    Trailer for the movie.
    </figcaption>
</figure>

To reference a Fulcrum resource within EPUB content at a location where no img element exists, the following markup may be used:

<figure style="display:none" data-fulcrum-embed-filename="Audio01.mp3">
    <figcaption>Additional Audio Resource</figcaption>
</figure>

The value of the figure/@data-fulcrum-embed-filename attribute contains the Fulcrum resource file name. Both the basename and the extension should match.

The figcaption element is optional, but can be used to provide a caption for the resource once it is displayed.

1.16 Code Blocks

Representations of computer code within the text, referred to here as code blocks should be encoded semantically when possible. Never use an image to represent lines of code, inline code, or code blocks.

1.16.1 Inline Code

Code to be displayed inline with paragraph text should be indicated with its equivalent semantic element.

<p>In table 2.2, the FizzBuzz algorithm ... is described as a
<i>loop</i> because it continues to compute results so long as the
proper conditions are met, in this case while the input amount
(<code>i</code>) is a number lower than or equal to 100.
Example 2.2.a, on the left, frames its computation in an initial
"catch-all" condition statement, that is, that <code>i</code>
is a multiple of three <i>or</i> of five. (The syntax
<code>i%3</code> checks whether "<code>i</code> divided by 3"
has a remainder of zero.) Then it checks each of those subconditions
independently of one another. This means that <code>i</code> ...
</p>

1.16.2 Code Blocks

Code that needs its formatting preserved and should display as a block of text, like a blockquote, should be identified a figure and be wrapped with elements to preserve formatting of the code. Note the application of the CSS class code on the figure element. Rules defined in the associate spec CSS file help ensure formatting is preserved and line breaks occur when lines of code are excessively long.

<figure class="code">
<pre>
<code>
if invariance &#x3e; the random of engineering
        and not categorical then
    put ideals + one into media
    if subversive then
        put false into subversive
    end if

    if media &#x3e; instantiation then
        put one into media
    end if
end if
</code>
</pre>
<figcaption>
<span id="p51" class="page" epub:type="pagebreak" role="doc-pagebreak" aria-label="51">Page 51 &#8594;</span>
<p class="bqt">(Cayley 2002)</p>
</figcaption>
</figure>

1.16.3 Code Blocks with Line Numbers

There may be instances where code blocks are long or an author refers to specific lines of code in the surrounding text. There also may be a desire to allow readers to copy and paste code blocks without line numbers included in the copied text. To do so one will need to divert from semantic encoding, and use CSS-only to include line numbers. Apply a CSS attribute which utilizes CSS line counting to provide line numbers automatically.

<figure class="code-linenumbers">
<figcaption>
<a data-locator="p157" class="page"></a>Practice Script 5.3: Revised simple statement combination
</figcaption>
<pre>
<span>myVariable = true;</span>
<span>if (myVariable == true) {</span>
<span> "The value of myVariable is TRUE";</span>
<span>} else {</span>
<span> "The value of myVariable is FALSE";</span>
<span>}</span>
</pre>
</figure>

1.16.4 Code Blocks with Line Numbers as Tables

In cases where code does not need to be copied and pasted but the display of line numbers is desirable, it is acceptable to encode the block of code as a table. For historical references to code this may be the most desirable, where excerpts of code are only needed to be displayed and line numbers start not a 1, but 3977, for example.

<table class="code">
<thead>
<tr>
<th class="th" colspan="2"><a data-locator="p10"
class="page"></a>Table 1.1. Excerpt from Heartbleed patch
(t1\_lib.c) by snhenson et al. (2015)</th>
</tr>
<tr>
<th class="tch">Line</th>
<th class="tch">Code</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<pre><code>3977</code></pre>
</td>
<td>
<pre>
<code>/* Read type and payload length first */</code>
</pre>
</td>
</tr>
<tr>
<td>
<pre><code>3978</code></pre>
</td>
<td>
<pre>
<code>if (1 + 2 + 16 &#x3e; s-&#x3e;s3-&#x3e;rrec.length)</code>
</pre>
</td>
</tr>
</tbody>
</table>

1.16.5 Comparing Code Blocks with Line Numbers

In other cases, two different blocks of code may need to be compared to one another side-by-side, along with the display of line numbers. In this case the code blocks should be encoded in a table, and follow the general pattern in 1.16.4. Note that in this case an additional CSS attribute is applied to the table element.

<table class="code compare">
<thead>
<tr>
<th class="th" colspan="3"><a data-locator="p59"
class="page"></a>Table 2.3. Two example FizzBuzz loops in
Ruby</th>
</tr>
<tr>
<th class="tch" style="width: 10%;">Line</th>
<th class="tch">Example 2.3.a</th>
<th class="tch">Example 2.3.b</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<pre><code>1</code></pre>
</td>
<td>
<pre>
<code>for i in 1..100</code>
</pre>
</td>
<td>
<pre>
<code>100.times do |i|</code>
</pre>
</td>
</tr>
<tr>
<td>
<pre><code>2</code></pre>
</td>
<td>
<pre>
<code> if i%3 == 0 then</code>
</pre>
</td>
<td>
<pre>
<code> i = i+1</code>
</pre>
</td>
</tr>
</tbody>
</table>

1.17 Footnotes and Endnotes

In general, the footnotes and endnotes are highly recommended to place at logical break of the book such as end of the chapter or end of the book, which will help the screen reader users to read the primary text. Also, the two-way link provided for the footnotes and endnotes reference numbers in between the primary text will help the screen reader users to navigate if they require.

Footnote and endnote tagging per the following examples is required for Apex EPUB deliveries, but considered optional for third-party partners to University of Michigan.

1.17.1 Footnotes in the body

<p>
In that year<a href="\#ft2f" epub:type="noteref">2</a>
there were 67 mills engaged in the manufacture of cotton goods ...
</p>
<aside id="ft2f" epub:type="footnote">
<p>
2 The manufacturing statistics for 1900 which
follow are not those given in the Twelfth
Census, but are taken from the
<em>Census of Manufactures</em> ...
</p>
</aside>
<p>...</p>

1.17.2 Endnote section

The HTML Model allows for lists to contain headings, paras, images, tables, etc. This means that applying list tagging can accommodate Endnote structures following <ol>.

If it is necessary to match the presentation of the text for editorial reasons, then it is suggested to use an unordered list tagging so that each endnote item is encapsulated as a list item.

A cluster of paras with tagging does not afford the same flexibility as list encoding, nor provide precision for isolating start and end of notes.

<section epub:type="endnotes">
<h2>End Notes</h2>
<ol>
<li id="en001" epub:type="endnote">
According to the usual nomenclature, the
branch flowing S.W. is called the Chattooga;
this unites with the Tallulah to form the
Tugaloo, which ...
</li>
...
</ol>
</section>

1.17.3 Back-linking notes

<li id="en001" epub:type="endnote">
<a href="\#en01-ref" title="note reference 1">1</a>
According to the usual nomenclature, the ...
</li>

1.18 Content Numbering

1.18.1 Page Break Numbering

Page numbers should follow the EPUB3 Accessibility Guidelines. https://idpf.github.io/a11y-guidelines/content/xhtml/pagenum.html

Example coding:

<span id="p1" class="page" epub:type="pagebreak"
      role="doc-pagebreak" aria-label="1">Page 1 &\#8594;</span>

Note: Page numbers should only be applied for titles that have a print equivalent. For titles that are digital-only and do not have a print equivalent, paragraph numbers should be applied.

1.18.2 Paragraph Numbering

Paragraph numbering requires adding a class identifier and id value to a . Paragraph numbers should only be applied to elements that are true paragraphs, not elements that use the paragraph element for styling.

Note: Paragraph numbering is optional, but required when present in the source document or when there is no print equivalent and the title is digital-only.

Example coding:

<p class="numberedpara" id="para11" title="Para11"/>

1.18.3 Line Numbering

Line numbering requires adding a class identifier and id value to a .

Example coding:

<p class="numberedline" id="line11" title="Line11"/>

1.19 Chapter Split

When chapters contain a large number of images and the total file size of the images exceeds 2 Mb, then consider splitting the chapter into a series of html files. This will create smaller files for faster download and rendering within the Fulcrum EPUB system. Inside each html file, please include the yellow highlighted metadata updated by section to represent relationships between all files for a chapter. The example snippet below is for file chapter2a. The reason for the metadata inclusion is to provide information so that UM is able to parse files to allow only chapters to display.

<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:epub="http://www.idpf.org/2007/ops" xml:lang="eng">
<head>
<title>More</title>
<link rel="stylesheet" href="../Styles/stylesheet.css" type="text/css"/>
<meta name="viewport" content="initial-scale=1.0;maximum-scale=5.0"/>
<meta content="chapter2" name="chapter2a" role="section"/>
</head>
<body>
<div>
<h3 class="subhead" id="sub4"><em>The Mid-Republican Period: The House</em></h3>

1.20 CSS Stylesheet

1.20.1 Standard CSS

If possible, use following standard CSS for EPUB3 conversion. Add unique styles per book as needed as additional styles at the bottom of the standard CSS.

1.20.2 CSS Units

Font-size should always be defined in %
Do not use fixed values (mm, cm, in, pt or pc) in CSS file.
Control the font style over the css (avoid inline styles)
Create external style sheet
- It is necessary to validate CSS (refer http://www.css-validator.org/).
- Do not capture (capture as )
- Do capture for bold text in XHTML files

1.20.3 Colors

The best practice is to avoid using color to differentiate the information of a text. For example, if the color of a text provides a meaning to the content, then there should be some alternate method to convey the information to screen reader user.

1.20.4 Background Images

Setting the contrast between the background colors and images will help readers who have difficulty in distinguishing contrasts. Color contrast of 4:5:1 is the best practice followed in the industry. Check contrast using the following link. https://webaim.org/resources/contrastchecker/.

1.20.5 Hidden Content

There should not be any hidden content available in the EPUB files.

Exception: Code long-descriptions as a separate instance in a file and it is permissible to have it remain hidden text.

1.20.6 CSS Property Reference

EPUB 3 user agents that visually render content may provide support for the CSS properties listed below, but inclusion is optional. Properties not listed may still be used (e.g., from evolving CSS 3 modules), but content authors should use due diligence and assess the impact on rendering and accessibility when using such properties.

1.20.7 CSS 2.1

Table 1. Acceptable Styles

Property	Considerations
background	The background property is a shorthand for defining one or more properties. Refer to each individual background-* property for potential issues. Note that background properties are largely unsupported at this time outside of fixed layouts.
background-attachment
background-color	Ensure sufficient contrast with text color.
background-image	Ensure sufficient contrast with content color (text and graphic). High mix of gradients and colors in images can make reading overlaid text difficult.
background-position
background-repeat
border border-top border-right border-bottom border-left	These border properties are shorthands for defining one or more properties. Refer to each individual border-* property for issues.
border-collapse
border-color border-top-color border-right-color border-bottom-color border-left-color	An element's border color must never be the sole means of conveying information about the nature of its content. See the Color info page.
border-spacing
border-style border-top-style border-right-style border-bottom-style border-left-style
border-width border-top-width border-right-width border-bottom-width border-left-width	When using color to convey meaning, ensure borders are thick enough that visual users can discern the color.
bottom left right top	User agent support for absolute and fixed positioning is not guaranteed. Content should not be positioned in a way that makes its discoverability problematic for users with low vision and/or using zooming software.
caption-side
clear
color	See the Color info page for the range of considerations when coloring text and graphical content.
counter-increment counter-reset
cursor	Avoid changing the cursor such that clickable elements are no longer distinguishable.
display	Setting the display property to the value none removes the element from rendering both visually and to assistive technologies. It is not a mechanism for hiding content from visual display that should be rendered by ATs.
empty-cells	Setting the empty-cells property is not required for HTML5 tables, as borders are rendered (do not insert placeholder text such as dashes or non-breaking spaces). For forwards compatibility with EPUB 2 user agents, the property should be set to the value show to ensure table borders are drawn around empty cells.
float	Elements should not be floated in a way that makes their discoverability problematic for users with low vision and/or using zooming software. Ensure sufficient margins exist around floated content so that it is clearly distinguishable from the content that flows around it. When floating primary content to the right, ensure that it is not positioned in the markup to accommodate the float (i.e., it occurs at the logical reading point so that it makes sense in non-visual playback contexts).
font	The font property is a shorthand for defining one or more properties. Refer to each individual font-* property for issues.
font-family	Avoid fonts that do not provide sufficient character differentiation, such as sans-serif fonts that represent capital I, lower-case L and the number 1 as identical (or near-identical) characters (e.g., Arial). Avoid cursive and highly ornamented fonts that can be difficult for users to decipher. Try to limit the number of fonts used in any given publication and use families consistently (e.g., one family for headings and one for body content). Give preference to fonts that provide sufficient kerning between characters.
font-size	Use relative sizes such as percentages and ems to facilitate scaling. Ensure default font size does not affect legibility of the prose (e.g., avoid specifying x-small, xx-small and equivalent font sizes).
font-style	Use CSS to apply italics only for decorative purposes (similar to using the i element). Use em tags if the words are to be stressed. Avoid lengthy use of decorative italics, as italicized words can be harder to read than roman face.
font-variant
font-weight	Use CSS to apply bolding only for decorative purposes (similar to using the b element). Use strong tags if the words are to be stressed. Avoid lengthy use of decorative bolding, as bolded words can be harder to read than roman face.
height	Assistive technologies typically ignore content that has 0 height and/or width set on its containing element, so do not use this property to hide content that is only intended for non-visual playback.
letter-spacing	The letter-spacing property can be used to increase the kerning between letters to improve the readability of tightly constructed fonts. Whitespace should never be added between the letters of a word that is not intended to be spelled out. Always use this property to visually expand the spacing between characters when such spacing is necessary.
line-height	Use caution when changing line heights. Slight increases in the line height can improve overall readability, but too much space between lines can have the opposite effect (e.g., it becomes harder to distinguish paragraphs). Avoid shrinking the line height to compress content.
list-style	The list-style property is a shorthand for defining one or more properties. Refer to each individual list-style-* property for issues.
list-style-image	Avoid using images to convey the meaning of a list. If the image is important to comprehension of the items, ensure that a semantic is attached to the list to convey that meaning. If the list represents a figure or aside, use the appropriate container element and include a caption.
list-style-position
list-style-type	Do not change the nature of a list using the list-style-type property (e.g., to not use the property to give an unordered list the appearance of ordering).
max-height max-width min-height min-width
orphans widows
outline outline-color outline-style outline-width	Outlines surround borders and serve a similar function. The issues with each are the same. See the corresponding border properties for more information. Ensure when using both borders and outlines that sufficient contrast is maintained between them if they both visually convey information.
overflow	Avoid using the hidden value, as content may not be visible, especially when zoomed.
padding padding-top padding-right padding-bottom padding-left
page-break-after page-break-before page-break-inside
position	Absolute positioning should not be used to re-order content differently than it is laid out in the markup. Elements should not be absolutely positioned in a way that makes their discoverability problematic for users with low vision and/or using zooming software. Note that the fixed value is not included in the EPUB 3 Style Sheets profile and its use is not recommended (see the oeb-page-head and oeb-page-foot custom properties for including static headers and footers).
quotes
table-layout
text-align	Avoid justifying text, as the uneven spacing that occurs between words can reduce the readability for some people.
text-decoration	Use the del element to semantically mark deleted text.
text-indent	A sometimes used trick to hide text for assistive technologies is to use a large negative value, but like negative margins this technique is not reliable in user agents and may cause issues depending on the user's preferred text direction.
text-transform	Avoid lengthy decorative use of capitalization as it can make words difficult to distinguish and read.
vertical-align
white-space
width	Assistive technologies typically ignore content that has 0 width and/or height set on its containing element, so do not use this property to hide content that is only intended for non-visual playback.
word-spacing	Increasing word spacing can help improve readability of tightly constructed fonts. Use this property in preference to adding non-breaking spaces to increase the space between words.
z-index

Table 2. Not Recommended Classes

Property	Considerations
clip	Although clipping content to 1 pixel is sometimes used on the Web to hide content, support for the property and its reliance on absolute positioning makes the practice not recommended in EPUBs.
content	Any content inserted using this property should be purely presentational, as it typically won't be available to assistive technologies.
direction	The direction property is not supported in EPUB 3. HTML5 markup, such as the bdi and bdo elements and dir attribute, should be used to express directionality.
margin margin-top margin-right margin-bottom margin-left	Note that user agents typically restrict the ability to modify body margins. Changing margins to move content off screen, common on the Web, is not guaranteed to work in user agents. This practice is also known to cause problems depending on the user's preferred reading direction and the placement of the content so is not recommended for that reason, as well.
visibility	Hidden content is not available to assistive technologies, so do not use this property to hide content from visual rendering that is intended to be read out.
azimuth cue cue-after cue-before elevation pause pause-after pause-before pitch pitch-range play-during richness speak speak-header speak-numeral speak-punctuation speech-rate stress voice-family volume	Properties from the CSS 2.1 Aural style sheets informative appendix should not be used in EPUB 3. The 'aural' media type was deprecated by the same appendix, and the CSS 3 Speech module defines the properties for the new 'speech' type.

1.20.8 CSS 2.1 Pseudo-Classes

Property	Considerations
:active
:first-child
:focus
:hover	The :hover pseudo-selector should never be used, as it is not device independent and may not be activatable by many users as ebook users typically do not have mice.
:lang
:link
:visited

1.20.9 CSS 2.1 Pseudo-Elements

Pseudo-Element

Considerations

:before

and

:after

Not all assistive technologies announce text injected using the :before and :after pseudo-elements.
Since the expected behavior is to announce the injected text, avoid the using the pseudo-elements for decorative purposes.
Users without CSS support will not have access to the injected text.

:first-letter

:first-line

1.21 Images

1.21.1 Image File Types

Acceptable file types include JPG, PNG and SVG (as per EPUB3 guidelines).

1.21.2 Recommended Criteria

Resolution	Minimum 72 dpi
Compression	JPG Medium
Color space	24-bit color (RGB) or Grayscale
Format	JPG for grayscale and color pictures and photographs.
Reading orientation	Position per reading order. Rotated landscape images in print versions are rotated for presentation in the EPUB.
Size	Reference Standard CSS
Presentation	Maximum File Size should not exceed 1 Mb. Reprocess images greater than 1Mb in size by applying higher compression (not to exceed JPG Medium) or resampling to reduce the DPI.
Exception note	If a file is less than 1Mb and jpg, use jpg as is. If a file is equal to or greater than 1Mb in size apply the following treatment in Photoshop CC Image Size > Adjust dpi to 96 dpi with Resample set to Bicubic Sharper (Reduction). Save As JPEG, Quality Setting to 8 (High), Optimized. The above can be batch processed.

Note: For EPUB source files, retain the images as per the source EPUB file with the aforementioned properties.

1.21.3 Cover Image

1.21.3.1	The cover must consist of an XHTML file containing nothing but an image. The image must be styled to take up the entire height of the screen. This can be achieved using the CSS below (just an example) or follow sample CSS if available: img.cover { height: 100%; }
1.21.3.2	Declare the cover in metadata (OPF) (mandatory).
1.21.3.3	Capture cover related metadata as follows in .opf file: <meta name="cover" content="cover-image" /> <item id="cover-image" href="images/cover.jpg" media-type="image/jpeg"/>
1.21.3.4	Minimum width of the cover should be more than 600 px and minimum height of the cover should be 800 px captured proportionately.
1.21.3.5	If the cover size of the source EPUB file is too small, then retain the cover per the source EPUB cover. Do not increase the size of the source EPUB cover.
1.21.3.6	The cover image needs to fit the page when viewed in Readium ereader to cover as much white space as possible.

1.21.4 Image/Graphic Placement

For any object rendered as an image/graphic that occurs in the midst of a paragraph and interrupts text, it shall be placed either at the end of the preceding paragraph or the beginning of the nearest following paragraph within the specific page. Final placement of the image is dependent on the closest paragraph's proximity. The image must stay within the page marker it occurs on in the source PDF. If an image interrupts text, and no paragraph tag that starts or ends on the same page, then keep the image in its original location.

1.22 Fonts

If the input EPUB file contains fonts, then retain them in the output EPUB3 files. For web-ready PDF input files, do not embed fonts, unless otherwise requested by customer.

1.23 Formatting

Retain as much as possible of the formatting of the source EPUB and PDF files in the output EPUB3 file.

1.24 Boxed Text

Treat as text + images in reading order.

1.25 Marginalia and Sidebars