by Matt Garrish

 

…

  The order in which you add semantics to the attribute does not infer importance or affect accessibility, so the above could have just as meaningfully been reversed.

  You should also be aware that this attribute is only available to augment structures; it is not intended for semantic enrichment of your content. Associating the personal information about an individual contained in a book so that a complete picture of their life can be built by metadata querying, for example, is not yet possible. The metadata landscape was considered too unstable to pick a method for enriching data, but look for a future revision to include this ability, whether via RDFa, microdata, or another method.

  And in case it needs repeating, semantics are not just an exercise in labeling elements. As I discussed in the introduction to this section, these semantics are what enable intelligent reading experiences. If you had 25 definition lists in an ebook each with a particular use, how would a reading system determine which one represents the glossary if you didn’t have a semantic applied as in the first example? If you know which is the glossary, you could provide fast term lookups. The easier you make it for machines to analyze and process your data, the more valuable it becomes.

  Language

  Although the global language for the publication is set in the EPUB package file metadata, it’s still a good practice to specify the language in each of your content documents. In an age of cloud readers, assistive technologies might not have access to the default language if you don’t (unless they rewrite your content file to include the information in the package document, which is a bad assumption to make). Without the default language, you can impact on the ability of the assistive technology to properly render text-to-speech playback and on how refreshable braille displays render characters.

  An xml:lang attribute on the root html element is all it takes to globally specify the language in XHTML content documents. For compatibility purposes, however, you should also include the HTML lang attribute. Both attributes must specify the same value when they’re used.

  We could indicate that a document is in German as follows:

 

  Similarly, for SVG documents, we add the xml:lang attribute to indicate that the title, description, and other text elements are in French:

 

  You should also clearly identify any prose within your book that is in a different language from the publication:

 

She had an infectious joie de vivre mixed with a certain je ne sais quoi.

  The xml:lang attribute can be attached to any element in your XHTML content documents (and the lang attribute is again included for compatibility). Properly indicating when language of words, phrases, and passages changes allows text-to-speech engines to voice the words in the correct language and apply the proper lexicon files, as we’ll return to in more detail in the text-to-speech section.

  Logical Reading Order

  Although you’ll hear that all EPUB 3s have a default reading order, it’s not necessarily the same thing as the logical reading order, or primary narrative. The EPUB 3 spine element in the publication manifest defines the order in which a reading system should render content files as you move through the publication. This default order enables a seamless reading experience, even though the publication may be made up of many individual content files (e.g., one per chapter).

  But although the main purpose of the spine is to identify the sequence in which documents are rendered, you can use it to distinguish primary from auxiliary content files. The linear attribute can be attached to the child itemref elements to indicate whether the referenced content file contains primary reading content or not. If a content file contains auxiliary material that would normally appear at the point of reference, but is not considered part of the main narrative, it should be indicated as such so that readers can choose whether to skip it.

  For example, if you group all your chapter end notes in a separate content document, you could indicate their auxiliary status as follows:

  … …

  A reader could now ignore these sections and continue following the primary narrative uninterrupted. But this capability is only a simple measure for distinguishing content that is primary at the macro level; it’s not effective in terms of distinguishing the primary narrative flow of the content within any document. (Although in the case of simple works of fiction that contain only a single unbroken narrative, it might be.)

  Sighted readers don’t typically think about the logical reading order within the chapters and sections of a book, but that’s because they can visually identify the secondary content and read around it as desired. A reading system, however, doesn’t have this information to use for the same effect unless you add it (those semantics, again).

  As I touched on in keeping style separate from content, you can, for example, give a sidebar a nice colorful border and offset it from the narrative visually using a div and CSS, but you’ve limited the information you’re providing to only a select group when all you use is style. Using a div instead of an aside element means a reading system will not know by default that it can skip the sidebar if the reader has chosen to only follow the primary narrative.

  For someone listening to the book using a text-to-speech engine, the narrative will be interrupted and playback of the sidebar div will be initiated when you mis-tag content in this way. The only solution at the reader’s disposal might be to slowly move forward until they find the next paragraph that sounds like a continuation of what they were just listening to (div elements aren’t always escapable). Picture trying to read and keep a thought with the constant interruptions that can result from sidebars, notes, warnings and all the various other peripheral text material a book might contain.

  For this reason, you need to make sure to properly identify content that is not part of the primary narrative as such. The aside element is particularly useful when it comes to marking text that is not of primary importance, but even seemingly small steps like putting all images and figures in figure tags allows the reader to decide what additional information they want presented. I’ll be returning to how to tag many of these as we go, too.

  The EPUB 3 Structural Semantics Vocabulary is also a useful reference when it comes to which semantics and elements to apply to a given structure. Each of the semantics defined in this vocabulary indicates what HTML element(s) it is intended to be used in conjunction with.

  Sections and Headings

  As I touched on in the introduction to this section, always group related content that is structurally significant in section elements to facilitate navigation, and always indicate why you’ve created the grouping using the epub:type attribute:

 

…

  The entries in the table of contents in your navigation document are all going to be structurally significant, which can be a helpful guide when it comes to thinking about how to properly apply the section element. Some additional ideas on structural significance can be gleaned from the terms in the EPUB 3 Structural Semantics Vocabulary. For example, a non-exhaustive list of semantics for sectioning content includes:

  foreword

  prologue

  preface

  part

  chapter

  epilogue

  bibliography

  glossary

  index

  Semantics are especially helpful when a section does not have a heading. Sighted readers are used to the visual conventions that distinguish dedications, epigraphs, and other front matter that may be only of slight interest, for example, and can skip past them. Someone who can’t see your content has to listen to it if you don’t provide any additional information to assis
t them.

  Headingless, unidentified content also means the person will have to listen to it long enough to figure out why it’s even there. Have you just added an epigraph to the start of your book, and skipping the containing section will take them to the first chapter, or are they listening to an epigraph that starts the first chapter and skipping the section will take them to chapter two? These are the impediments you shift onto your reader when you don’t take care of your data.

  When the section does contain a heading, there are two options for tagging: numbered headings that reflect the current level or h1 headings for every section. At this point in time, using numbered headings is recommended, as support for navigation via the structure of the document is still developing:

 

Part I

Chapter 1

…

  Numbered headings will also work better for forward-compatibility with older EPUB reading systems.

  Using an h1 heading regardless of the nesting level of the section will undoubtedly gain traction moving forward, though. In this case, the h1 becomes more of a generic heading, as traversal of the document will occur via the document outline and not by heading tags (the construction of this outline is defined in HTML5). There is only limited support for this method of navigation at this time, however.

  Note

  It’s also worth briefly noting that the hgroup element should probably only be used judiciously, if at all, for title and subtitle grouping at this time. The element is not yet widely supported, and there are a number of proposals to change it under review as of writing.

  And remember that titles are an integral unit of information. If you want to break a title across multiple lines, change font sizes, or do other stylistic trickery, use spans and CSS and keep the display in the style layer. Never add multiple heading elements for each segment. Use span elements if you need to visually change the look and appearance of headings.

  To break a heading across lines, we could use this markup:

 

Chapter One Loomings.

  and then add the following CSS class to change the font size of the span and treat it as a block element (i.e., place the text on a separate line):

  span.chapNum { display: block; margin: 0.5em 0em; font-size: 80% }

  If you fragment your data, you fragment the reading experience and cause confusion for someone trying to piece back together what heading(s) they’ve actually run into.

  Context Changes

  A nasty side-effect of current print-based export processes is that changes in context are visually styled either using CSS and/or with images. When you use the CSS margin-top property to add spacing, you’re taking away from anyone who can’t see the display that a change in context has occurred. Graphics to add whitespace are no better, since they don’t typically specify an alt value and are ignored by accessible technologies. Graphics that include asterisms or similar as the alt text are slightly better, but are still a suboptimal approach in that they don’t convey any meaning except through the reading of the alt value.

  There are people who would argue that context breaks represent the borders between untitled subsections within sections, but from a structural and navigational perspective it’s typically not true or wanted, so don’t be too tempted to add section elements.

  HTML5 has, in fact, addressed this need for a transitioning element by changing the semantics of the hr element for this purpose:

 

… the world swam and disappeared into darkness.

---

When next we met …

  By default this tag would include a horizontal rule, but you can use CSS to turn off the effect and leave a more traditional space for visual viewing:

  hr.transition { width: 0em; margin: 0.5em 0em; }

  or you could add a fleuron or other ornament:

  hr.transition { background: url('img/fleuron.gif') no-repeat 50% 50%; height: 1em; margin: 0.5em 0em; }

  Styling the hr element ensures that the context change isn’t lost in the rush to be visually appealing.

  Lists

  You’d typically not expect to have to hear the advice that you should use lists for sets of related items, but rely too heavily on print tools to create your content and the result will be paragraphs made to look like list items, or single paragraphs that merge all the items together using only br tags to separate them.

  If you don’t use proper list structures, readers can get stuck having to traverse the entire set of items before they can continue with the narrative flow (in the case of one paragraph per item) or having to listen to every item in full to hear the list (when br tags are used).

  A list element, on the other hand, provides the ability both to move quickly from item to item and to escape the list entirely. It also allows a reading system to inform a reader how many items are in the list and which one they are at for referencing. Picture a list with tens or hundreds of items and you’ll get a sense for why this functionality is critical.

  Using paragraphs for lists also leads people to resort to visual trickery with margins to emulate the deeper indentation that a nested list would have. These kinds of illusions take away from all but sighted readers that there exists a hierarchical relationship. The correct tagging allows readers to navigate the various levels with ease.

  A final note is to always use the right kind of list:

  the ol element is used when the order of the items is important.

  the ul element is used when there is no significance or weak significance to the items (e.g., just because you arrange items alphabetically does not impart meaning to the order).

  the dl element is used to define terms, mark up glossaries, etc.

  Lists have these semantics for good purpose, so don’t use CSS to play visual games with them.

  Tables

  The reflowable, paginated nature of ebook reading has fortunately kept tables from being used for presentational purposes in ebooks. In theory, this should have been a good thing. The complex nature of tables relative to limited rendering area of typical reading systems has led to the worse practice of excluding the data in favor of images of the table, however. How helpful is a picture of data to someone who cannot see it?

  The motivating hope behind this practice seems to be that images will take away rendering issues on small screens, but don’t fall into this trap. Not only are you taking the content away from readers who can’t see the table, but even if you can see the images they often get scaled down to illegibility and/or burst out the side of the reading area on the devices that this technique is presumably meant to enhance the tables on (notably eInk readers that have no zooming functionality).

  Consider also what you’re doing when you add a picture: you’re trying to address a situational disability (the inability to view an entire table at once) by creating another disability (only limited visual access to the content). If you properly mark up your data, readers can find ways to navigate it, whether via synthetic speech or other accessible navigation mechanisms. Obsessing about appearance is natural, but ask yourself how realistic a concern it should be when people read on cellphone screens? Give your readers credit to understand the limitations their devices impose, and give them the flexibility to find other ways to read.

  When it comes to marking up tables, the fundamental advice for making them accessible from web iterations past remains true:

  Always use th elements for header cells.

  Wrap your header in a thead, in particular when including multi-row headings.

  Use the th scope attribute to give the applicability of the heading (e.g., whether to the row or column). This attribute is not necessary for simple tables where the first row of th elements, or a th cell at the start of each row, defines the header(s), however.

  If the header for a cell cannot be easily determined by its context, and especially when multiple cells in a multi-row header apply, add the headers attribute
and point to the appropriate th element(s).

  These heading requirements allow a person navigating your table to quickly determine what they’re reading at any given point in it, which is the biggest challenge that tables pose outside of perhaps escaping from them. It’s easy to get lost in a sea of numbers, otherwise.

  The following example shows how these practices could be applied to a table of baseball statistics:

 

1927 New York Yankees

Player	Regular Season			Post Season
	At Bats	Hits	Average	At Bats	Hits	Average
Lou Gehrig	584	218	.373	13	4	.308

  The headers attribute on the td cells identifies both whether the cell contains a “Regular Season” or “Post Season” statistic as well as the particular kind of stat from the second header row. The value of this tagging is that a reading system or assistive technology can now announce to the reader that they are looking at “regular season hits” when presented the data for the third column, for example.