EPUB Dictionaries and Glossaries 1.0

Recommended Specification 26 August 2015

This version
http://www.idpf.org/epub/dict/epub-dict-20150826.html
Latest version
http://www.idpf.org/epub/dict/epub-dict.html
Previous version
http://www.idpf.org/epub/dict/epub-dict-20140926.html

Please refer to the errata for this document, which may include some normative corrections.

A history of changes to this document is available for review.

Editors

Jeffrey Alexander, Intangible Press

Romain Deltour, DAISY Consortium

Authors

Robert Bolick, Invited Expert

Karen Broome, Sony Electronics

Matt Garrish, Invited Expert

Markus Gylling, International Digital Publishing Forum

Ori Idan, Helicon Books

Yasuo Kida, Apple Inc.

David K. Ream, Leverage Technologies

Wolfgang Schindler, PONS

Emmanuelle Seca, Editis

Tzviya Siegman, Wiley

Status of this Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document.

This document has been reviewed by the IDPF membership and is endorsed by the IDPF Board as a Recommended Specification. This document is considered stable and may be referenced from other specifications and documents.

Feedback on this document can be provided to the EPUB Working Group's mailing list or issue tracker.

This document is governed by the IDPF Policies and Procedures.

Table of Contents

  1. 1. Overview
    1. 1.1 Purpose and Scope
    2. 1.2 Terminology
    3. 1.3 Typographic Conventions
    4. 1.4 Conformance Statements
  2. 2. EPUB Dictionaries and Glossaries Definition
    1. 2.1 Introduction
    2. 2.2 Content Documents - Dictionaries
      1. 2.2.1 The Dictionary Container
      2. 2.2.2 The Dictionary Entry
        1. 2.2.2.1 article Element As Entry Container
        2. 2.2.2.2 Condensed and Detailed Entries
          1. 2.2.2.2.1 Introduction
          2. 2.2.2.2.2 The Condensed Entry
          3. 2.2.2.2.3 Interpreting Condensed Entry and Detailed Entry Markup
          4. 2.2.2.2.4 Rendering in Viewports
      3. 2.2.3 Headwords
        1. 2.2.3.1 Use of dfn Element
        2. 2.2.3.2 Canonical Forms of Headwords
          1. 2.2.3.2.1 Introduction
          2. 2.2.3.2.2 Representing the Canonical Form of a Headword
          3. 2.2.3.2.3 Examples
      4. 2.2.4 Phonetic Transcriptions
      5. 2.2.5 Parts of Speech and Related Grammatical Information
        1. 2.2.5.1 Parts of Speech
        2. 2.2.5.2 Related Grammatical Information
      6. 2.2.6 Etymologies
      7. 2.2.7 Meanings and Their Organization in the Entry
        1. 2.2.7.1 Introduction
        2. 2.2.7.2 Part of Speech Lists
        3. 2.2.7.3 Part of Speech Groups
        4. 2.2.7.4 Sense Lists
        5. 2.2.7.5 Sense Groups
        6. 2.2.7.6 Definitions
        7. 2.2.7.7 Translations
        8. 2.2.7.8 Translation-Related Information
      8. 2.2.8 Phrases
        1. 2.2.8.1 Introduction
        2. 2.2.8.2 Idioms
        3. 2.2.8.3 Examples
        4. 2.2.8.4 Phrase Lists
        5. 2.2.8.5 Phrase Groups
      9. 2.2.9 Synonyms and Antonyms
        1. 2.2.9.1 Synonym Groups
        2. 2.2.9.2 Antonym Groups
    3. 2.3 Content Documents - Glossaries
      1. 2.3.1 The Glossary Container
      2. 2.3.2 Glossary Terms and Definitions
      3. 2.3.3 Phonetic Transcriptions in Glossaries
    4. 2.4 Search Key Map Documents
      1. 2.4.1 Introduction
      2. 2.4.2 Content Conformance
      3. 2.4.3 Reading System Conformance
      4. 2.4.4 Search Key Map Document Definition
        1. 2.4.4.1 The search-key-map Element
        2. 2.4.4.2 The search-key-group Element
        3. 2.4.4.3 The match Element
        4. 2.4.4.4 Examples
    5. 2.5 Identification of the Dictionary or Glossary in the Package Document
      1. 2.5.1 Dictionary Identification
        1. 2.5.1.1 Identification with dc:type
        2. 2.5.1.2 Publication Consisting of a Single EPUB Dictionary
        3. 2.5.1.3 Publication Consisting of Multiple EPUB Dictionaries
        4. 2.5.1.4 Additional Dictionary Metadata
          1. 2.5.1.4.1 Identifying the Dictionary Type
          2. 2.5.1.4.2 Identifying the Audience
          3. 2.5.1.4.3 Identifying Source and Target Languages
      2. 2.5.2 Glossary Identification
      3. 2.5.3 Manifest item Properties
      4. 2.5.4 Package Document Examples
        1. 2.5.4.1 Glossary Example
        2. 2.5.4.2 Monolingual Dictionary Example
        3. 2.5.4.3 Unidirectional Bilingual Dictionary Example
        4. 2.5.4.4 Bidirectional Bilingual Dictionary Example
        5. 2.5.4.5 Multilingual Dictionary Example
  3. 3. Conformance Criteria
    1. 3.1 Content Conformance
    2. 3.2 Reading System Conformance
  4. Appendix A. Schema for Dictionaries in EPUB Content Documents
  5. Appendix B. Examples
    1. B.1 English Monolingual Dictionary Example
    2. B.2 French-English Bilingual Dictionary Example
    3. B.3 Glossary Example
  6. Appendix C. Contributors and Acknowledgments
  7. References

 1. Overview

 1.1 Purpose and Scope

This section is informative

The primary purpose of a dictionary or glossary is to let a user look up an unfamiliar word and retrieve an explanation of its meaning and usage or its translations into another language. This specification provides a means for Authors to represent dictionary and glossary semantics in EPUB Publications [Publications301]. This in turn allows Reading Systems to develop search features that interact with these Publications, notably, lookup search for a word a user selects while reading or inputs into a search field.  Search implementation is aided by a new Core Media Type called the Search Key Map Document, an XML document that gathers all search terms in a central location for fast Reading System access.

Dictionaries vary in terms of style, size, reading level of intended audience, language inclusion, and coverage of general or specialized terminology. The same user may need a specialized dictionary when reading a medical text, a bilingual dictionary when reading a novel in a foreign language, a crossword dictionary when doing crosswords, a thesaurus when writing an essay, and an encyclopedia when reading a history. This specification enables Authors to give users such choice in dictionaries and related reference works,  remedying a situation where users typically only have access to bundled dictionaries.

This specification provides a framework for a rich user experience of dictionary Publications, with a particular focus on word lookup in a cross-publication context. It is designed to enable efficient dictionary search and content retrieval during user access of other EPUB Publications. Moreover, in consideration of the length of many dictionary entries as well as variation in the size of the user’s lookup viewport, dictionary markup allows Authors to tailor an entry specifically for rendering in constrained viewports. Furthermore, optional semantic inflections are designed to encourage Reading System innovation in meeting accessibility needs and making entries easier to read and navigate. The semantic markup defined herein is not, however, intended to serve as an authoring or repository format for dictionaries, and so does not allow for the type of fine-grain distinctions typically required by lexicographers.

Glossaries define a Publication’s key terms in language appropriate to the audience and subject matter. Users need to be able to look up unfamiliar terms and retrieve the valuable, context-specific definitions that glossaries provide, a need that becomes especially acute in educational settings. This specification provides a framework to make such user interaction with glossary content possible. 

 1.2 Terminology

Please refer to the EPUB Specifications for definitions of EPUB-specific terminology used in this document.

ancestor context

A property [Publications301] carried by an ancestor element being semantically inflected [ContentDocs301], either implicitly or explicitly via the epub:type attribute. 

bilingual dictionary

A dictionary in which the meanings of words in a source language are translated into a different target language.  Translation may either be unidirectional (English to Japanese) or bidirectional (both English to Japanese and Japanese to English).

canonical form

The correct spelling of a dictionary headword, unadorned by extra characters or styles conveying additional information about that headword (such as pronunciation symbols, hyphenation points, and the like).

entry

The organizational unit of EPUB Dictionary content, consisting of at least one headword and further information on it. An entry in an EPUB Dictionary is independently distributable, meaning it can be rendered to users outside of its EPUB Dictionary Publication context.

Semantic markup of the entry and its microstructure is detailed in Content Documents - Dictionaries.  

 EPUB Dictionary

Dictionary content within a Rendition of an EPUB Dictionary Publication, consisting of entries whose headwords are in a common language, and accompanied by a Search Key Map Document that links search keys to those entries. An EPUB Dictionary represents a dictionary, encyclopedia, or similarly organized reference work. It can be directly consulted by the user or used by the Reading System to look up terms within any Publication.

Note that an EPUB Dictionary is not a Rendition of the Publication: Renditions are different renderings of the same content, whereas EPUB Dictionaries contain distinct content within a given Rendition.

EPUB Dictionary Publication

An EPUB Publication whose content consists primarily of one or more EPUB Dictionaries. An EPUB Dictionary Publication is identified as such in Package Metadata, as described in section 2.5 Dictionary Identification.

A monolingual EPUB Dictionary Publication will contain only one EPUB Dictionary, whereas a bilingual or multilingual dictionary Publication can contain multiple EPUB Dictionaries. For example: in a French-English bidirectional bilingual dictionary publication, the French-to-English dictionary constitutes one EPUB Dictionary, and the English-to-French dictionary constitutes another EPUB Dictionary. Note that an EPUB Dictionary is not a Rendition of the Publication: Renditions are different renderings of the same content, whereas EPUB Dictionaries contain distinct content within a given Rendition.

EPUB Glossary

All the glossary content within a Rendition of an EPUB Publication and at least one accompanying Search Key Map Document linking search keys to Content Document locations. An EPUB Glossary in a Publication can be directly consulted by the user or used by the Reading System to look up terms within that Publication.

Whether glossary content is organized into one or more sections or distributed throughout the Publication, the entire collection of such content forms the EPUB Glossary.

While the word “glossary” can occur in a Publication’s title, if such a Publication consists primarily of terms and definitions that would be useful outside this Publication, then that Publication is an EPUB Dictionary rather than an EPUB Glossary for purposes of this specification. An EPUB Glossary is always a component of a larger EPUB Publication.

headword

A word or phrase defined, translated, or otherwise treated in an entry.

idiom

The defining instance of a phrase.

lookup

A search in a dictionary or glossary for a user-provided word or phrase. The word or phrase can be provided by either selecting text while reading or inputting text into a search field.

The context of a lookup typically differs between dictionaries and glossaries, especially when the word or phrase is provided by selecting text while reading. A glossary can only be used within its Publication, while a dictionary can be used while reading any Publication. In both cases, the dictionary entry or glossary term matching the lookup is retrieved by the Reading System and rendered to the user, typically in a separate viewport.

monolingual dictionary

A dictionary whose headwords, definitions, and other entry content are in the same language.

multilingual dictionary

A dictionary in which the meanings of words in a source language are translated into two or more target languages, and which may cover either one translation direction (English to Japanese and Chinese, for example) or two or more translation directions (English to Japanese and Chinese, Japanese to Chinese and English, and Chinese to Japanese and English).

parent context

A property [Publications301] carried by the nearest ancestor element being semantically inflected [ContentDocs301], either implicitly or explicitly via the epub:type attribute. 

result form

The form of a search key that is displayed in a result list following a user lookup.

search key

A word or phrase to be matched during a lookup in an EPUB Dictionary or EPUB Glossary. A search key can be mapped to a glossary term, dictionary entry, or location within a dictionary entry using the Search Key Map Document.

Search Key Map Document

An XML document that links search keys to entries in an EPUB Dictionary or to defined terms in an EPUB Glossary.  

source language

The language of entry headwords and phrases.

target language

The language of entry content that translates, defines, or otherwise explains the meanings of headwords and phrases. 

 1.3 Typographic Conventions

The following typographic conventions are used in this specification:

markup

All markup (elements, attributes, properties), code (JavaScript, pseudo-code), machine processable values (string, characters, media types) and file names are in red-orange monospace font.

markup

Links to markup and code definitions are underlined and in red-orange monospace font. Only the first instance in each section is linked.

http://www.idpf.org/

URIs are in navy blue monospace font.

hyperlink

Hyperlinks are underlined and in blue.

[reference]

Normative and informative references are enclosed in square brackets.

Term

Terms defined in the Terminology are in capital case.

Term

Links to term definitions have a dotted blue underline. Only the first instance in each section is linked.

Normative element, attribute and property definitions are in blue boxes.

Informative markup examples are in white boxes.

note

Informative notes are in yellow boxes with a "Note" header.

caution

Informative cautionary note are in red boxes with a "Caution" header.

  1.4 Conformance Statements

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].

All sections of this specification are normative except where identified by the informative status label "This section is informative". The application of informative status to sections and appendices applies to all child content and subsections they may contain.

All examples in this specification are informative.

 2. EPUB Dictionaries and Glossaries Definition

 2.1 Introduction

This section is informative

EPUB Publications conforming to this specification share three key features: semantically marked-up dictionary or glossary content, one or more Search Key Map Documents enabling Reading System search of that content, and metadata identifying dictionary and glossary components. Dictionaries and glossaries differ in how they relate to the EPUB Publication as a whole, however: an EPUB Glossary is always a component of an EPUB Publication, whereas a conforming dictionary is termed an EPUB Dictionary Publication, each Rendition of which consists of one or more EPUB Dictionary components.

Dictionary Content Documents have to conform to a small set of requirements. A collection of entries is marked up with the epub:type dictionary property, the dictionary entry is marked up with article (the HTML element designed for self-contained “independently distributable or reusable” content [HTML5]), and the headword is marked up with dfn. This reflects the importance of word lookup during reading as a use case, as a flat, predictable entry structure aids in the retrieval and rendering of dictionary content across Publications. Furthermore, this specification allows Authors to define a condensed entry designed specifically for ease of reading in a lookup viewport [ContentDocs301]; refer to Condensed and Detailed Entries for details.

In addition, optional  epub:type properties can be used to further describe dictionary entries. This allows Reading Systems to enable features such as visual cues and contrast for vision-impaired users, audio cues and announcements for blind users, and entry navigation and readability aids (for example, the ability to skip from the noun to the verb section of an entry, or dynamically collapse or expand a lengthy series of example sentences). Brief markup examples are provided in Content Documents - Dictionaries, but Authors are encouraged to refer to Appendix B for more detailed examples.

Glossary content markup is designed to be both simple and flexible. Authors may organize glossary content into one or more cohesive sections or distribute terms and definitions throughout the Publication (for example, interspersed throughout a textbook or index). This specification maintains backwards-compatibility with the glossary semantics already included in the EPUB3 Structural Semantics Vocabulary [StructureVocab], while refining and expanding on them.

This specification introduces the Search Key Map Document, a new Core Media Type with an XML vocabulary. The Search Key Map Document must be included in an EPUB Dictionary or EPUB Glossary. It gathers together all information required for robust Reading System search: glossary terms or dictionary headwords, inflected forms, idioms, alternate script forms used in search input (e.g. Chinese pinyin), and disambiguation aids shown in search results (e.g. Japanese yomi).

Lastly, metadata is defined for identifying an EPUB Dictionary Publication, describing the components of an EPUB Dictionary or EPUB Glossary, and providing other information such as a dictionary’s source and target languages. When multiple EPUB Dictionaries are present, the collection element is used to group together their components and distinguish them from one another.

 2.2 Content Documents - Dictionaries

 2.2.1 The Dictionary Container

Structural Semantics Vocabulary

dictionary

Definition

A collection of dictionary entries.

HTML Usage Context

body or section element for EPUB Dictionaries.

Must contain one or more article children.

A body or section element carrying an epub:type dictionary property represents a collection of dictionary entries in an EPUB Dictionary. Every Dictionary Content Document must contain such an element. This element must contain at least one article child element.

A Reading System conforming to this specification must process a dictionary body or section element in accordance with the constraints defined in Content Documents - Dictionaries.

The mechanism for identifying the entire Publication as an EPUB Dictionary Publication is described in Dictionary Identification.

Example 1: a <body> element with epub:type="dictionary", which makes the entire Content Document part of the EPUB Dictionary.

<?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/1999/xhtml"
 xmlns:epub="http://www.idpf.org/2007/ops" lang="en">
  <body epub:type="dictionary">
   <!—a collection of dictionary entries --> 
  </body>
</html>

Example 2: a <section> element with epub:type="dictionary". In this case the Author has chosen to include front matter and dictionary entries within the same Content Document.

<?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/1999/xhtml" 
 xmlns:epub="http://www.idpf.org/2007/ops" lang="en">
  <body>
   <section epub:type="titlepage">
         <h1 epub:type="title">A Dictionary of the English Language</h1>
         <p>by Dr. Samuel Johnson</p>
   </section>
   <section epub:type="dictionary">
     <h2>A</h2>
     <!—a collection of dictionary entries --> 
   </section>
  </body>
</html>

 2.2.2 The Dictionary Entry

 2.2.2.1 article Element As Entry Container
Structural Semantics Vocabulary

dictentry

Definition

A dictionary entry.

Required Parent Context

dictionary

HTML Usage Context

Use on article  element children of an element carrying the epub:type dictionary property; always implied on such elements.

Must contain at least one dfn descendant.

An article child of a dictionary section or body element represents a dictionary entry. Dictionary entries are self-contained so that they can be independently rendered in dedicated viewports. It contains at least one headword marked up with dfn along with related information.

Example 3: article elements in an EPUB Dictionary. Note the epub:type dictentry property of article is implied.

<body epub:type="dictionary">
 <article>
   <dfn>aardvark</dfn>
     <!--definitions for "aardvark"--> 
 </article>
 <article>
   <dfn>zebra</dfn>
     <!--definitions for "zebra"--> 
 </article>
</body>
 2.2.2.2 Condensed and Detailed Entries
 2.2.2.2.1 Introduction

This section is informative

To enhance the user’s experience of word lookup during uninterrupted reading, this specification allows dictionary Authors to include Condensed Entries in their EPUB Dictionaries. A Condensed Entry consists of content specially designed for reading in a lookup viewport.  While precise characteristics of the lookup viewport will depend on the Reading System and user preferences, Authors may assume that the lookup viewport is functionally or physically limited when compared to the reading viewport.

A Detailed Entry consists of the full content of the entry, excluding any specially-designed Condensed Entry. In other words, the Detailed Entry is the content rendered when the User browses the Publication. A Condensed Entry is a short entry summary that may be appropriate when viewport size is constrained. 

How each concept corresponds to actual article markup will vary between entries, and at times the Condensed Entry and Detailed Entry will be identical. Guidelines for determining what content to render are supplied in Interpreting Condensed Entry and Detailed Entry Markup and Rendering in Viewports.

The Condensed Entry allows Authors to provide Users a concise set of key meanings during lookup, ones which are more likely to provide the desired meaning without interrupting the reading experience. That said, dictionary Authors also have flexibility in selecting the content to use, and in where and how often to include Condensed Entries. Some dictionaries have entries that could be considered “condensed" generally, while even comprehensive dictionaries contain many short entries. In such cases, there is no need to include a condensed-entry.

However, Authors are encouraged to use this markup whenever condensing the entry for the lookup viewport can provide Users with an improved lookup and reading experience.

There are several editorial approaches that could be taken to creating a Condensed Entry:

 2.2.2.2.2 The Condensed Entry
Structural Semantics Vocabulary

condensed-entry

Definition

A condensed dictionary entry designed for constrained lookup viewports.

Required Parent Context

dictentry

HTML Usage Context

Use on aside element child of article.

The aside element must have the hidden attribute set.

An aside element carrying the epub:type condensed-entry property represents a condensed dictionary entry designed for constrained lookup viewports.  Such an element must have a hidden attribute. This element must be a child of article.

A Reading System conforming to this specification should support rendering of condensed-entry  during lookup as described in Interpreting Condensed Entry and Detailed Entry Markup and Rendering in Viewports.

Authors are strongly encouraged to include Condensed Entries in their EPUB Dictionaries.

Example 4: an extended entry containing a condensed-entry designed for use in a lookup viewport..

<article>
  <aside epub:type="condensed-entry" hidden="hidden">
    <dfn>length</dfn>
    <span epub:type="part-of-speech">n</span>
    <ol epub:type="sense-list">
      <li>longest dimension</li>
      <li>duration in time</li>
      <li>piece to be joined to others</li>
    </ol>
  </aside>
  <dfn>length</dfn>
  <span epub:type="part-of-speech">noun</span>
  <span epub:type="etymology">Middle English <em>lengthe</em>, from Old 
   English <em>lengthu</em>, from <em>lang</em> long</span>
  <ol epub:type="sense-list">
    <li><span epub:type="def">the longer or longest dimension of an object</span></li>
    <li><span epub:type="def">a measured distance or dimension</span> &lt;<span epub:type="example">10
     feet in <em>length</em></span>&gt;</li>
    <li><span epub:type="def">the quality or state of being long</span></li>
    <li><span epub:type="def">duration or extent in time</span></li>
    <li><span epub:type="def">relative duration or stress of a 
     sound</span></li>
    <li><span epub:type="def">distance or extent in space</span></li>
    <li><span epub:type="def">the length of something taken as a unit of 
     measure</span> &lt;<span epub:type="example">his horse led by a
     <em>length</em></span>&gt;</li>
    <li><span epub:type="def">the degree to which something (as a course of
     action or a line of thought) is carried —often used in plural</span>
     &lt;<span epub:type="example">went to great <em>lengths</em> to learn
     the truth</span>&gt;</li>
    <li><span epub:type="def">a long expanse or stretch</span></li>
    <li><span epub:type="def">a piece constituting or usable as part of a
     whole or of a connected series : <a href="s.html#section">SECTION</a></span> &lt;<span epub:type="example">a
     <em>length</em> of pipe</span>&gt;</li>
    <li><span epub:type="def">the longer or vertical dimension of a piece of
     clothing</span> 
     —often used in combination &lt;<span 
     epub:type="example">elbow-<em>length</em> sleeves</span>&gt;</li>
  </ol>
</article>

Example 5: a short entry that does not need a specially-designed condensed-entry.

<article>
  <dfn>dustpan</dfn>
  <span epub:type="part-of-speech">noun</span>
  <span epub:type="def">a shovel-shaped pan for sweepings</span>
</article>
 2.2.2.2.3 Interpreting Condensed Entry and Detailed Entry Markup
 2.2.2.2.4 Rendering in Viewports

When there is an explicit aside element carrying the epub:type condensed-entry property, the Reading System must not render both the Detailed and Condensed Entry in the same viewport.

 2.2.3 Headwords 

 2.2.3.1 Use of dfn Element 

headword is a word or compound word defined, translated, or otherwise treated in a dictionary entry. In an EPUB Dictionary a dfn descendant of a dictentry article represents a headword, unless it has a phrase-group parent context. If the dfn has a phrase-group parent context, it represents the defining instance of a phrase; see details in Idioms.

An article must contain at least one dfn descendant outside of any condensed-entry aside. If there is a condensed-entry aside, this aside should have at least one dfn element. The dfn is typically associated with additional information.

Each headword in a dictionary entry must be marked up with the dfn element. This applies to all types of headwords typically distinguished by dictionary Authors, such as alternate, variant, run-on, and run-in headwords.

Example 6: an English dictionary entry with the headword “colour” and the alternate headword “color”, both of which are marked up with dfn.

<article>
  <dfn>colour</dfn>, <em>(US)</em> <dfn>color</dfn>
  <!-- definitions for “colour” -->
</article>

note

HTML requires that the "paragraph, description list group, or section that is the nearest ancestor of the dfn element must also contain the definition(s) for the term given by the dfn element" [HTML5].

 2.2.3.2 Canonical Forms of Headwords
 2.2.3.2.1 Introduction

This section is informative

A headword’s canonical form  is its correct spelling as defined by the dictionary.

The dfn element’s contents are not always equivalent to the headword’s canonical form. For instance, the Author may include typographic elements such as homograph numbers and syllable markers in dfn to convey additional information to the User.  

This section details how Authors should use the title attribute so that Reading Systems can reliably identify canonical forms for aural rendering and other desired uses.

 2.2.3.2.2 Representing the Canonical Form of a Headword

When a dfn element representing a headword has a title attribute, the value of that attribute represents the canonical form of the headword. When no such title attribute is present, the canonical form of the headword is represented by the text content of the dfn element with leading and trailing whitespace trimmed.

The Author must make sure that the canonical form of a headword is represented, either with a title attribute or as the text content of the dfn element.

Reading Systems should identify and use the canonical form when pronouncing or spelling out headwords in an aural rendering.

 2.2.3.2.3 Examples

In  Example 6, each dfn element contains the canonical form of the headword and no other content, so use of the title attribute is not necessary.

In the following example, the Author has used the middle dot character (U+00B7) to mark a headword's syllable divisions and a superscript number to indicate that the headword is the first in a series of homographs. As neither mark is actually part of the headwords’ spellings, the Author used the title attribute to supply the canonical forms.

Example 7.

<article>
  <dfn title="color">col·or<sup>1</sup></dfn>
  <dfn title="colour">col·our</dfn>, <em>(British)</em>
  <!-- definitions for “color” -->
</article>

In the following German example of a separable verb, the publisher uses underlining to indicate that a syllable is pronounced with a long vowel, and the “|” character to indicate the part of the word that is put at the end of the sentence. As in the preceding example, the canonical form of the headword must be provided in the title attribute.

Example 8.

<article>
  <dfn title="ausgehen">
        <span style="text-decoration:underline">au</span>s|gehen
  </dfn>
  <!-- definitions for “ausgehen” -->
</article>

 2.2.4 Phonetic Transcriptions

Structural Semantics Vocabulary

phonetic-transcription

Definition

A phonetic transcription of the pronunciation of a headword or other component of a dictionary entry.

Required Ancestor Context

dictentry or glossary

HTML Usage Context

Use on any [HTML5] flow content element.

A phonetic-transcription represents a phonetic transcription of the pronunciation of a glossary term, dictionary headword, or other component of a dictionary entry. Though a phonetic-transcription of the headword is most typical, it may also relate to a translation, example, or other semantic element.

If phonetic-transcription has one or more preceding dfn siblings, then it relates to the nearest such sibling. Otherwise, it relates to its parent context.

note

As a written form of the pronunciation of a preceding element, a phonetic-transcription is primarily useful to sighted users in a visual rendering of the content. The recommended handling in an aural rendering of the content is either to skip a phonetic-transcription element or to read each character aloud.

The phonetic-transcription element is not intended for use by text-to-speech systems. Use of SSML [SSMLAttributes] is encouraged to specify the correct pronunciation of headwords or other content whose pronunciation would be ambiguous to text-to-speech systems.

Example 9: English entries with phonetic-transcription written in the International Phonetic Alphabet (IPA). Note that in the “wind” examples, the dfn has an ssml:ph attribute specifying the IPA pronunciation appropriate to the context.

<article>
  <dfn>unambiguous</dfn>
  <span epub:type="phonetic-transcription" lang="en-fonipa">
    /ˌʌnæmˈbɪgjuəs/
  </span>
</article>
<article>
  <dfn ssml:ph="ˈwɪnd" title="wind">wind<sup>1</sup></dfn>
  <span epub:type="phonetic-transcription" lang="en-fonipa">
    /ˈwɪnd/
  </span>
  <span epub:type="def">a movement of the air of any velocity</span>
</article>
<article>
  <dfn ssml:ph="ˈwaɪnd" title="wind">wind<sup>2</sup></dfn>
  <span epub:type="phonetic-transcription" lang="en-fonipa">
    /ˈwaɪnd/
  </span>
  <span epub:type="def">to turn completely or repeatedly about an
    object</span>
</article>

Example 10: a Chinese headword’s phonetic-transcription written in Pinyin. (English translation = “father”.)

<dfn>父亲</dfn>
<span epub:type="phonetic-transcription" lang="zh-pinyin">
  fùqīn
</span>

 2.2.5 Parts of Speech and Related Grammatical Information

 2.2.5.1 Parts of Speech
Structural Semantics Vocabulary

part-of-speech

Definition

The grammatical function of a headword.

Required Ancestor Context

dictentry

HTML Usage Context

Use on any [HTML5] flow content element.

A part-of-speech represents the grammatical function (noun, verb, adjective, etc.) of a headword, either in relation to the entire entry or to a particular set of meanings (such as those contained within a part-of-speech-group ).

Grammatical terminology varies across languages. An Author should use the terminology most appropriate for the dictionary’s audience in part-of-speech, but may use any text content. There is not an enumerated list of acceptable values for part-of-speech.

Example 11: an entry with a single part-of-speech value. (Refer to part-of-speech-list  for a more complex example.)

<article>
  <dfn>zebra</dfn>
  <span epub:type="part-of-speech">noun</span>
  <!--definitions for "zebra"--> 
</article>
 2.2.5.2 Related Grammatical Information
Structural Semantics Vocabulary

gram-info

Definition

Supplemental grammatical information related to the headword and modifying a part of speech or a particular meaning.

Required Ancestor Context

dictentry

HTML Usage Context

Use on any [HTML5] flow content element.

A gram-info represents grammatical information related to the headword but distinct from part-of-speech . This could be grammatical information constraining the part of speech generally (such as a note following a noun part-of-speech indicating the headword is always used in the plural) or a particular meaning (such as a note in a  sense-group  indicating the headword is always plural when expressing that meaning).

Example 12: gram-info following a part-of-speech.

<article>
  <dfn>milk</dfn>
  <span epub:type="part-of-speech">noun</span>,
  <span epub:type="gram-info">no plural</span>
  <!-- definitions for ”milk” -->
</article>

 2.2.6 Etymologies

Structural Semantics Vocabulary

etymology

Definition

An explanation of the historical origin of a headword.

Required Ancestor Context

dictentry

HTML Usage Context

Use on any [HTML5] flow content element.

An etymology represents an explanation of the historical origin of a headword.

In aural rendering of a dictionary, Reading Systems may use an audio cue to provide context before reading an etymology.

Example 13: an etymology.

<article>
  <dfn>algebra</dfn>
  <span epub:type="part-of-speech">noun</span>
  <span epub:type="etymology">
        Medieval Latin, from Arabic <i lang="ar">al-jabr</i>,
        literally, the reduction
  </span>
  <!-- definitions for ”algebra” -->
</article>

 2.2.7 Meanings and Their Organization in the Entry

 2.2.7.1 Introduction

This section is informative

Meanings may be organized in complex ways in dictionary entries.  One common approach is to organize the entry hierarchically, where the top level consists of parts of speech (noun, adjective, etc.), each of which can contain a list of senses. Furthermore, each sense may contain a list of phrases pertaining to it. Other approaches are possible as well, such as creating separate entries for different parts of speech, then organizing the entry primarily at the sense level. Whatever an Author’s typical approach may be, entry organization within a given dictionary varies considerably depending on the breadth and depth of information provided on a headword.

Regardless of their organization, entries typically contain definitions, translations, examples, and related information. In contrast to the higher-level organizational units, these semantic elements contain discrete information explaining or illustrating a particular meaning. This specification provides Authors a flexible means of identifying the building blocks of dictionary entries according to the needs of their content, as well as representing the most important types of information contained within structural units.

 2.2.7.2 Part of Speech Lists
Structural Semantics Vocabulary

part-of-speech-list

Definition

A list of part of speech groups in a dictionary entry.

Required Ancestor Context

dictentry

HTML Usage Context

Use on ol element

Implies the value part-of-speech-group on its li children.

A part-of-speech-list represents a list of part-of-speech-groups in a dictionary entry.

Use of part-of-speech-list is restricted to the ol element. Each li child of a part-of-speech-list ol has an implied part-of-speech-group epub:type property.

Example 14: a part-of-speech-list with nested sense-lists in a French-English bilingual dictionary. The type attribute of ol specifies that the list will be ordered by uppercase Roman numeral markers. Refer to Appendix B for more detailed examples.

<body epub:type="dictionary" lang="fr">
  <article>
    <dfn>abandonner</dfn>
    <span epub:type="phonetic-transcription">abɑ&#x0303;dɔne</span>
    <ol epub:type="part-of-speech-list" type="I">
      <li>
        <span epub:type="part-of-speech">vt</span>
        <ol epub:type="sense-list">
          <li>
            <span epub:type="def">déserter, quitter</span>
            <span epub:type="tran" lang="en">to abandon</span>
          </li>
          <li>
            <span epub:type="def">laisser derrière soi: déchets</span>
            <span epub:type="tran" lang="en">to leave behind</span>
          </li>
          <li>
            <span epub:type="def">renoncer à: pouvoir, fonction</span>
            <span epub:type="tran" lang="en">to relinquish</span>
          </li>
        </ol>
      </li>
      <li>
        <span epub:type="part-of-speech">vi</span>
        <span epub:type="tran" lang="en">to give up</span>
      </li>
      <li>
        <span epub:type="part-of-speech">vr</span>
        <ol epub:type="sense-list">
          <li>
            <span epub:type="def">se détendre</span>
            <span epub:type="tran" lang="en">to let oneself go</span>
          </li>
          <li>
            <span epub:type="def">se relâcher</span>
            <span epub:type="phrase-group">
              <span epub:type="example">elle s'abandonna dans les bras de 
                sa mère</span>
              <span epub:type="tran" lang="en">she fell into her mother's
              arms</span>
            </span>
          </li>
        </ol>
      </li>
    </ol>
  </article>
</body>
 2.2.7.3 Part of Speech Groups
Structural Semantics Vocabulary

part-of-speech-group

Definition

A unit that associates a part of speech with its related sense and phrase groups.

Required Ancestor Context

dictentry

HTML Usage Context

Use on any [HTML5] flow content element.

Implied on li children of an ol element carrying the  epub:type  part-of-speech-list property.

Must contain an element carrying the epub:type  part-of-speech property.

A part-of-speech-group represents a unit that associates a part-of-speech with its related sense-groups and phrase-groups.

The recommended markup for a sequence of part of speech groups is a part-of-speech-list  ol. It is preferred for accessibility reasons, and also avoids repetition by implying the part-of-speech-group epub:type property on all its li descendants.

 2.2.7.4 Sense Lists
Structural Semantics Vocabulary

sense-list

Definition

A list of sense groups in a dictionary entry.

Required Ancestor Context

dictentry

HTML Usage Context

Use on ol element.

Implies the value sense-group on its li descendants.

A sense-list represents a list of sense-groups in a dictionary entry.

Use of sense-list is restricted to the ol element. Each li descendant of a sense-list ol has an implied sense-group epub:type property.

Example 15: a sense-list in a French-English bilingual dictionary. As no type attribute is specified on ol,  the list will have the default ordering by decimal numbers. Note that def can be used to provide several types of short sense descriptors, e.g., a definition, a synonym ("lassitude"), a subject label (“FINANCE”), etc.  Refer to Appendix B for more detailed examples.

<body epub:type="dictionary" lang="fr">
  <article>
    <dfn>abattement</dfn>
    <span epub:type="phonetic-transcription">[abatmɑ&#x0303;]</span>
    <span epub:type="part-of-speech" lang="en">noun</span>
    <span epub:type="gram-info">m</span>
    <ol epub:type="sense-list">
      <li>
        <span epub:type="def">lassitude</span>
        <span epub:type="tran" lang="en">exhaustion</span>
      </li>
      <li>
        <span epub:type="def">découragement</span>
        <span epub:type="tran" lang="en">despondency</span>
      </li>
      <li>
        <span epub:type="def">rabais</span>
        <span epub:type="tran" lang="en">reduction</span>
      </li>
      <li>
        <span epub:type="def">FINANCE</span>
        <span epub:type="tran" lang="en">allowance</span>
      </li>
    </ol>
  </article>
</body>
 2.2.7.5 Sense Groups
Structural Semantics Vocabulary

sense-group

Definition

A unit for organizing information pertaining to a particular meaning of a headword or idiom.

Required Ancestor Context

dictentry

HTML Usage Context

Use on any [HTML5] flow content element.

Implied on li children of an ol element of type  sense-list.

A sense-group represents a unit for organizing information pertaining to a particular meaning of a headword or idiom.

The recommended markup for a sequence of senses is a sense-list ol. It is preferred for accessibility reasons, and also avoids repetition by implying the sense-group epub:type property on all its li descendants.

 2.2.7.6 Definitions
Structural Semantics Vocabulary

def

Definition

The definition of a particular meaning of a headword or idiom.

Required Ancestor Context

dictentry

HTML Usage Context

Use on any [HTML5] flow content element.

A def represents either the definition of a particular meaning of a headword or idiom, or in a bilingual or multilingual dictionary, a short meaning descriptor accompanying particular translations of a headword or idiom. Note that an element carrying the def epub:type property represents only the definition’s content rather than the entire set of associated information (like numeric identifiers, grammatical labels, examples, etc).

When an entry contains multiple meanings, def is usually a descendant of an element carrying the epub:type property sense-group or phrase-group.

Example 16: an English monolingual dictionary where the meaning of the headword  is described in a definition (epub:type="def").

<article>
  <dfn title="linguistics">lin·guis·tics</dfn>
  <span epub:type="phonetic-transcription">[lɪŋˈgwɪstɪks]</span>
  <span epub:type="part-of-speech">noun</span>
  <span epub:type="gram-info">(with singular verb)</span>  
  <span epub:type="def">the scientific study of language</span>      
</article>

Example 17: an English-German bilingual dictionary where synonyms are used as short sense descriptions (epub:type="def") to disambiguate  the headword so that the user may find out the correct translation.

<article>
  <dfn title="economical">eco·nomi·cal</dfn>
  <span epub:type="phonetic-transcription">
    ˌiːkəˈnɒmɪk<sup>ə</sup>l, 
    <span>AE</span> -ˈnɑːm-
  </span>
  <span epub:type="part-of-speech">adj</span>
  <ol epub:type="sense-list">
    <li>
      <span epub:type="def">cost-effective</span>
      <span epub:type="tran">wirtschaftlich</span>
      <span epub:type="tran">ökonomisch</span>
    </li>
    <li>
      <span epub:type="def">thrifty</span>
      <span epub:type="tran">sparsam</span>
      <span>pej</span>
      <span epub:type="tran">knaus[e]rig</span>
      <span epub:type="tran-info">pej fam</span>
    </li>
  </ol>
</article>
 2.2.7.7 Translations
Structural Semantics Vocabulary

tran

Definition

The translation of a particular meaning of a source language headword, idiom, or example into a target language.

Required Ancestor Context

dictentry

HTML Usage Context

Use on any [HTML5] flow content element.

A tran represents the translation of a particular meaning of a source language headword, idiom, or example into a target language.

When an entry contains multiple senses or phrases, tran is usually a descendant of an element carrying the epub:type property sense-group or phrase-group.

Example 18: an English-German bilingual dictionary which shows that translations (epub:type="tran") may occur on different levels of an entry.

<article>
  <dfn title="abbreviate">ab·bre·vi·ate</dfn>
  <span epub:type="phonetic-transcription">əˈbriːvieɪt</span>
  <span epub:type="part-of-speech">transitive verb</span>
  <span epub:type="tran">abkürzen</span>
  <span epub:type="phrase-group">
    <span epub:type="example">Susan is often <span 
     ssml:ph="əˈbriːvieɪtəd">∼d</span> to Sue</span>
    <span epub:type="tran">Susan wird oft mit Sue abgekürzt</span>
  </span>
</article>
 2.2.7.8 Translation-Related Information
Structural Semantics Vocabulary

tran-info

Definition

Grammatical or usage information related to a translation.

Required Ancestor Context

dictentry

HTML Usage Context

Use on any [HTML5] flow content element that has a sibling element carrying the tran epub:type property.

A tran-info represents grammatical or usage information related to a translation. It must have a sibling element carrying the  tran epub:type property.

Example 19: an English-German bilingual dictionary which demonstrates grammatical  (gender) and usage information (“fam” stands for the register “familiar”) on the translation using epub:type="tran-info".

<article>
  <dfn title="corner shop">'cor·ner shop</dfn>
  <span epub:type="part-of-speech">noun</span>
  <span epub:type="def">brit</span>
  <span epub:type="tran">Tante-Emma-Laden</span>
  <span epub:type="tran-info">m fam</span>
</article>

 2.2.8 Phrases

 2.2.8.1 Introduction

This section is informative

Phrases represent a fundamental type of information contained in dictionary entries. There are two basic types of phrases distinguished in this specification: the idiom, which is a phrase whose meaning is defined in an entry, and the example, which is a phrase that illustrates the meaning and usage of a headword or idiom. Since idioms represent defined phrases, Authors may choose to treat them as search keys, allowing users to find them via lookup (see Example 28 under Search Key Map Documents for details).

Phrases typically are associated with other semantic elements of a descriptive nature (such as definitions and translations) or an organizational one (such as a sense list). As with parts of speech and senses, all of the information related to a phrase can be grouped together and a series of such groups can be organized as a list.

 2.2.8.2 Idioms
Structural Semantics Vocabulary

idiom

Definition

A defining instance of a phrase.

Required Parent Context

phrase-group or dictentry

HTML Usage Context

Use on dfn element.

An idiom represents a defining instance of a phrase. This property must be used on the dfn element, and carries the same restrictions on nearest ancestors and use of the title attribute as dfn generally.

An idiom is typically contained in a phrase-group containing related definitions, translations, and examples. In a dictionary of idioms where the headword itself is a phrase, idiom can be carried by dfn  elements with dictentry as their parent context

 2.2.8.3 Examples
Structural Semantics Vocabulary

example

Definition

An illustration of the usage of a defined term or phrase.

Required Ancestor Context

dictentry

HTML Usage Context

Use on any [HTML5] flow content element.

An example represents a sentence demonstrating the usage of a headword or idiom.

When an entry contains multiple senses or phrases, an example should be marked up as part of the sense-group or phrase-group for which it demonstrates usage.

 2.2.8.4 Phrase Lists
Structural Semantics Vocabulary

phrase-list

Definition

A list of phrase groups in a dictionary entry.

Required Ancestor Context

dictentry

HTML Usage Context

Use on ol or ul element

Implies the value phrase-group on its li children.

A phrase-list represents a list of phrase-groups in a dictionary entry.

Use of phrase-list is restricted to the ol or ul element. Each li child of a phrase-list ol or ul has an implied phrase-group epub:type property.

Example 20: a phrase-list in an English-German bilingual dictionary. Note that the list contains both an idiom and an example .

<article>
  <dfn title="concrete">con·crete</dfn>
  <span epub:type="phonetic-transcription">
    <span lang="en-fonipa">ˈkɒŋkri:t</span> or AE:
    <span lang="en-fonipa">ˈkɑ:n-</span>
  </span>
  <span epub:type="part-of-speech">noun</span>
  <span epub:type="gram-info">no pl</span>
  <ol epub:type="sense-list">
    <li>
      <span epub:type="def">building material</span>
      <span epub:type="tran" lang="de">Beton</span>
      <span epub:type="tran-info">m</span>
      <ul epub:type="phrase-list">
        <li>
          <dfn epub:type="idiom">reinforced concrete</dfn>
          <span epub:type="trans" lang="de">Stahlbeton</span>
          <span epub:type="tran-info">m</span>;
          <span epub:type="trans" lang="de">Eisenbeton</span>
          <span epub:type="tran-info">m</span>
        </li>
      </ul>
    </li>
    <li>
      <span epub:type="def">Phrases:</span>
      <ul epub:type="phrase-list">
        <li>
          <dfn epub:type="idiom">to be cast [or set] in 
            concrete</dfn>
          <span epub:type="trans" lang="de">fest ausgemacht sein</span>
        </li>
        <li>
          <span epub:type="example">these regulations are set in 
            concrete</span>
          <span epub:type="trans" lang="de">an diesen Bestimmungen gibt es 
            nichts zu rütteln</span>
        </li>
      </ul>
    </li>
  </ol>
</article>
 2.2.8.5 Phrase Groups
Structural Semantics Vocabulary

phrase-group

Definition

A unit for organizing information pertaining to an idiom or example.

Required Ancestor Context

dictentry

HTML Usage Context

Use on any [HTML5] flow content element.

Implied on li children of an ol or ul element carrying the  phrase-list epub:type property.

Must contain at least one idiom or example descendant.

A phrase-group represents a unit for organizing information pertaining to an idiom or example. It must contain at least one example element or idiom dfn element as a descendant.

The recommended markup for a sequence of phrase groups is a phrase-list ol. It is preferred for accessibility reasons, and also avoids repetition by implying the phrase-group epub:type property on all its li descendants.

 2.2.9  Synonyms and Antonyms

 2.2.9.1 Synonym Groups
Structural Semantics Vocabulary

synonym-group

Definition

A group of terms, each having identical or similar meaning to a headword or idiom.

Required Ancestor Context

 dictentry

HTML Usage Context

Use on any [HTML5] flow content element.

A synonym-group represents a group of terms, each having identical or similar meaning to the headword.

If a synonym-group occurs in a phrase-group, it contains synonyms or near synonyms of any preceding idiom dfn in the phrase-group. Otherwise, it contains synonyms of all preceding dfn elements in the article.

Refer to antonym-group below for an example.

 2.2.9.2 Antonym Groups
Structural Semantics Vocabulary

antonym-group

Definition

A group of terms, each having an opposite or nearly opposite meaning from a headword or idiom.

Required Ancestor Context

dictentry

HTML Usage Context

Use on any [HTML5] flow content element.

An  antonym-group represents a group of terms, each having an opposite or nearly opposite meaning from a headword or idiom.

If an antonym-group occurs in a phrase-group, it contains antonyms or near antonyms of any preceding idiom dfn in the phrase-group. Otherwise, it contains antonyms or near antonyms of all preceding dfn elements in the article.

Example 21: synonym-group and antonym-group in a thesaurus entry.

<article>
  <dfn>center</dfn>
  <span epub:type="part-of-speech">noun</span>
  <ol epub:type="sense-list">
    <li>
      <span epub:type="def">the point that is equally distant from all
        points on the circumference of a circle or surface of a
        sphere</span>
          <div epub:type="synonym-group">Synonyms: core, middle,
              midpoint, midst; <em>also</em> inside, interior</div>
      <div epub:type="antonym-group">Antonyms: perimeter,
        periphery</div>
    </li>
  </ol>
</article>

 2.3 Content Documents - Glossaries

 2.3.1 The Glossary Container

Structural Semantics Vocabulary

glossary

Definition

An alphabetical list of terms in a particular domain of knowledge, with the definitions for those terms.

HTML Usage Context

dl, body, sectioning content

A dl, bodysection or other sectioning content element carrying an epub:type glossary property represents a collection of glossary terms and definitions in an EPUB Glossary. As shown in example 22 below, if the epub:type glossary property is carried by a dl element, the glossterm and glossdef epub:type properties are implied on its dt and dd children (respectively), allowing for less verbose markup.

An EPUB Glossary consists of all elements carrying an epub:type glossary property in a given Rendition of the Publication and at least one Search Key Map Document that links search keys to the Content Document locations where terms are defined. A Search Key Map Document provides a central resource for Reading System glossary search, thereby providing Authors the choice of organizing glossary content into (a) cohesive, alphabetized section(s) of a Publication or distributing glossary terms and definitions throughout the Publication.

The mechanism for identifying an EPUB Glossary in the package document is described in Glossary Identification.

 2.3.2 Glossary Terms and Definitions

Structural Semantics Vocabulary

glossterm

Definition

A glossary term.

Required Ancestor Context

glossary

HTML Usage Context

Use on any [HTML5] flow content element.

Implied on dt  element children of a dl  element carrying the epub:type  glossary  property.

Structural Semantics Vocabulary

glossdef

Definition

The definition of a term in a glossary.

Required Ancestor Context

glossary

HTML Usage Context

Use on any [HTML5] flow content element.

Implied on dd  element children of a dl  element carrying the epub:type  glossary  property.

A glossterm represents a glossary term, and a glossdef represents the definition of a term in a glossary.

Authors are encouraged to use dfn in glossary markup to identify the exact term being defined, typically within a dt element.

When the glossary epub:type property is carried by a dl element, the logical association of glossary terms and definitions follows the name-value groups described in [HTML5]. In other words, a group of adjacent dd elements are definitions for the terms represented by nearest preceding group of adjacent dt siblings.

Example 22: an alphabetically ordered dl with the glossary property. The glossterm property is implied on the dt elements, while the glossdef property is implied on the dd elements. Note the use of dfn to indicate the exact terms defined in the dt elements.

<dl epub:type="glossary">
  <dt id="active_solar">
    <dfn>Active solar</dfn>
  </dt>
  <dd>As an energy source, energy from the sun collected and stored using
    mechanical pumps or fans to circulate heat-laden fluids or air between
    solar collectors and a building.</dd>
  <dt id="alternating_current">
    <dfn>Alternating current</dfn>
    (<dfn><abbr title="alternating current">AC</abbr></dfn>)
  </dt>
  <dd>An electric current that reverses its direction at regularly recurring
    intervals.</dd>
  <dt id="ampere">
    <dfn>Ampere</dfn>
  </dt>
  <dd>The unit of measurement of electrical current produced in a circuit by
    1 volt acting through a resistance of 1 Ohm.</dd>
  <dt id="automatic_set-back_thermostat">
    <dfn title="automatic set-back thermostat">Automatic set-back</dfn> or
    <dfn>clock thermostat</dfn>
  </dt>
  <dd>A thermostat that can be set to turn the heating/cooling system off
    and on at certain predetermined times.</dd>
  <dt id="bundled_utility_service">
    <dfn>Bundled utility service</dfn> (electric)
  </dt>
  <dd>A means of operation whereby energy, transmission, and distribution
    services, as well as ancillary and retail services, are provided by one
    entity.</dd>
</dl>

Example 23: glossary terms/definitions that are distributed throughout a Publication . As in the previous example, the glossary  dl causes the glossterm property to be implied on the dfn elements and the glossdef property  to be implied on the dd elements.

<h1>My Science Textbook: Chapter 5</h1>
<p>This is the part of the book where the author introduces the concept of
  the <a href="#ampere">ampere</a> and discusses it in detail.</p>
<aside>
  <dl epub:type="glossary">
    <dt id="ampere"><dfn>Ampere</dfn></dt>
    <dd>The unit of measurement of electrical current produced in a
      circuit by 1 volt acting through a resistance of 1 Ohm.</dd>
  </dl>
</aside>

<h1>My Science Textbook: Chapter 6</h1>
<p>This is the part of the book where the author introduces the concept of
  <a href="#alternating_current">alternating current</a> and discusses it in
  detail.</p>
<aside>
  <dl epub:type="glossary">
    <dt id="alternating_current">
      <dfn>Alternating current</dfn>
      (<dfn><abbr title="alternating current">AC</abbr></dfn>)
    </dt>
    <dd>An electric current that reverses its direction at regularly
      recurring intervals.</dd>
  </dl>
</aside>

Example 24: glossary terms/definitions that are distributed throughout an index. Note that such a combined index/glossary needs to conform to both EPUB Indexes [Indexes] and glossary markup standards.

<body epub:type="index glossary">
  <ul epub:type="index-entry-list">
    <li>
      <span epub:type="index-term glossterm">alternating current</span>, 
        <a epub:type="index-locator" href="...">155</a><br/>
      <span epub:type="glossdef">An electric current that reverses its
        direction at regularly recurring intervals.</span>
    </li>
    <li>
      <span epub:type="index-term glossterm">ampere</span>,
        <a epub:type="index-locator" href="...">98</a><br/>
      <span epub:type="glossdef">The unit of measurement of electrical 
        current produced in a circuit by 1 volt acting through a resistance
        of 1 Ohm.</span>
    </li>  
  </ul>
</body>

 2.3.3 Phonetic Transcriptions in Glossaries

The phonetic-transcription epub:type property is permitted in glossaries. See Phonetic Transcriptions under Content Documents - Dictionaries for detailed usage information.

 2.4 Search Key Map Documents

 2.4.1 Introduction

This section is informative

Search Key Map Documents contain information intended to assist Reading Systems in implementing powerful search functionality. A Search Key Map Document maps search keys  to corresponding entries (or part thereof) in an EPUB Dictionary or EPUB Glossary. No distinction is made as to the linguistic nature of the mapped search keys; they can contain not only direct terms or headwords but also inflected forms, idioms, and alternate script forms (e.g. Chinese pinyin). The Search Key Map Document also allows the definition of a default   result form  that may be rendered by the Reading System in a list of matches. The result form may differ from the search key, and is meant to enable the display of disambiguation aids (for example, Japanese yomi) to the user.

No conformance criteria are defined on how a Reading System is supposed to leverage a Search Key Map Document. The search functionality can be directly based on the XML machine-readable data, but Reading Systems would more commonly construct a more efficient binary search index from it.

Each EPUB Dictionary features exactly one Search Key Map Document and each EPUB Glossary features at least one Search Key Map Document, as specified in the section Manifest item Properties.

 2.4.2 Content Conformance

A Search Key Map Document must meet all of the following criteria:

Document Properties

File Properties

Search Key Map Documents have the MIME media type application/vnd.epub.search-key-map+xml. This specification adds this media type to the list of EPUB 3 Core Media types [Publications301], meaning that Search Key Map Documents can be included in EPUB Publications without the provision of fallbacks.

 2.4.3 Reading System Conformance

A Reading System that supports EPUB Dictionaries and Glossaries must meet the following criteria:

 2.4.4 Search Key Map Document Definition

All elements [XML] defined in this section are in the http://www.idpf.org/2007/ops namespace [XMLNS] unless otherwise specified.

 2.4.4.1 The search-key-map Element

The search-key-map element is the root container of the Search Key Map Document.  

Element Name

search-key-map

Usage

The search-key-map element is the root element of the Search Key Map Document.

Attributes
xml:lang [required]

Specifies the language used in the contents and attribute values of the carrying element and its descendants, as defined in section 2.12 Language Identification of [XML].

dir [optional]

Specifies the base text direction of the content and attribute values of the carrying element and its descendants. Inherent directionality specified using [Unicode] takes precedence over this attribute.

Allowed values are ltr (left-to-right) or rtl (right-to-left).

id [optional]

The ID [XML] of this element, which must be unique within the document scope.

Content Model

One or more search-key-group elements [required].

The root element of the Search Key Map Document must have an xml:lang attribute identifying the language used for the search and result forms within the Search Key Map Document..

All of the contents of an EPUB Dictionary or EPUB Glossary should be covered by its constituent Search Key Map Document.

note

When the content of the Search Key Map Document is known not to be in any language (for instance, when the related EPUB Dictionary is a dictionary of programming language terms or a dictionary of illustrations), the xml:lang attribute should have the value "zxx[RFC5646].

note

In an EPUB Dictionary, the value of the xml:lang attribute will typically be the same as the source language defined in the package metadata.

 2.4.4.2 The search-key-group Element

A search-key-group element in the search-key-map encapsulates all the mapping information related to a single entry in the related EPUB Dictionary or term in the related EPUB Glossary.

Element Name

search-key-group

Usage

As a child of the search-key-map element. Repeatable.

Attributes
href [required]

An IRI [RFC3987] specifying the location of the dictionary entry or glossary term indexed by this search-key-group. The IRI must be relative to the base IRI of the Search Key Map Document.

id [optional]

The ID [XML] of this element, which must be unique within the document scope.

Content Model

match [1 or more].

If the Search Key Map Document is part of an EPUB Dictionary, the IRI provided in the href attribute must identify the element – carrying an implied or explicit dictentry   epub:type property – that represents the related entry in the Content Document.

If the Search Key Map Document is part of an EPUB Glossary, the IRI provided in the href attribute must identify the element – carrying an implied or explicit glossterm   epub:type property – that represents the related glossary term in the Content Document.

The IRI value of the href attribute must be relative. Reading Systems must use the IRI of the Search Key Map Document as the base IRI when resolving it to an absolute IRI.

 2.4.4.3 The match Element

The match element represents the mapping from one or more search keys  to a single EPUB Dictionary entry (or part thereof) or to an EPUB Glossary term.

Element Name

match

Usage

As a child of search-key-group. Repeatable.

Attributes
href [optional]

An IRI [RFC3987] specifying the location indexed by this match within the dictionary entry or glossary term referenced by the parent search-key-group. The IRI must be relative to the base IRI of the Search Key Map Document.

value [optional]

Specifies the primary search key string value of this match.

title [optional]

Specifies the default result form associated with this match.

phonogram [optional]

Specifies a disambiguation aid for identical result forms.

id [optional]

The ID [XML] of this element, which must be unique within the document scope.

xml:lang [optional]

Specifies the language used in the contents and attribute values of the carrying element and its descendants, as defined in section 2.12 Language Identification of [XML].

Content Model

value [0 or more].

Element Name

value

Usage

Optional child of match. Repeatable.

Attributes
value [required]

Specifies a search key string value of the match parent.

Content Model

Empty.

The match element groups computer-readable search keys that should produce matches upon a lookup.

The value attribute – both on the match element or on its value children – represents a single search key. At least one search key must be associated with a match element. When only one search key is defined, it should be represented using a value attribute on the match element rather than using a single value child.

When the match element has a search key defined in its value attribute, this search key also represents the  canonical form  (i.e. lemma) of the headword indexed by the match element. If present, all of the value children may be considered specific forms (e.g. inflected forms) of that canonical form.  This information can be used by Reading Systems to improve storage or performance (e.g. by leveraging lemmatization rules).

The title attribute represents the default result form of the headword, i.e. the form that may be rendered to the user in a result list. The title attribute may be omitted if the match element has a value attribute, in which case the content of the value attribute also represents the default result form. Otherwise, if the match element has no value attribute, the title attribute is required.

The phonogram attribute may be used to specify the pronunciation of a word in Chinese, Japanese, or other ideographic writing systems. The phonogram attribute provides a reading of a value attribute and would typically contain Japanese yomi or Chinese Pinyin. It does not define a new search key for the match element.

A match element may represent search keys for only a local part of a dictionary entry (for example a specific sense, an idiom, or a derived word). In this case, the matching content may be identified by an IRI provided in the href attribute. The IRI must be relative. Reading Systems must use the IRI of the Search Key Map Document as the base IRI when resolving it to an absolute IRI. When no href attribute is present, the match element represents search keys matching the entire dictionary entry or glossary term referenced by its search-key-group parent.

note

This specification does not mandate the use of any Unicode normalization form [TR15] to represent search keys. Reading Systems should however always at least compare canonical-equivalent Unicode strings as equal by applying NFC or NFD normalization.

note

When rendering a match in a result list, a Reading System may choose to display the default result form of the headword  provided by the title or value attribute of the match element, or it may choose to display instead the specific search key that was matched. The content of phonogram attributes may also be rendered, e.g. to disambiguate multiple matches.

note

Within search-key-group or match elements, the IRI value of an href attribute is a relative IRI identifying a location within an EPUB Content Document, and is resolved against the base IRI of the Search Key Map Document.

href="xhtml/Dict_A-E.xhtml#dfn05"
href="pub.opf#epubcfi(/6/4[dict_a-e]!/4[body01]/10[dfn05]"

When using [EPUB CFI], the targeted location can be specified as a range.

 2.4.4.4 Examples
 Example 25: A simple search key map for the headword "get"

Note how the title attribute is used to specify a default result form different from the search key, and how value child elements are used to declare search keys for the inflected forms of the verb.

<search-key-map xml:lang="en">
  <search-key-group href="pub.opf#epubcfi(/6/4[entry-e-to-h]!/563[get0001]">
    <match title="get (verb)" value="get">
      <value value="gets"/>
      <value value="getting"/>
      <value value="got"/>
      <value value="gotten"/>
    </match>
  </search-key-group>
</search-key-map>
 Example 26: A search key map for a Japanese dictionary

In this example, the match elements do not specify a value attribute, i.e. no search key is considered the canonical form of its related headword. Note also the presence of the phonogram attribute to specify the hiragana reading(s) of the search keys.

<search-key-map xml:lang="ja">
  <search-key-group  href="dict.xhtml#akai">
    <match title="赤い・紅い" phonogram="あかい"><!--one hiragana reading of two kanji forms-->
      <value value="あかい"/><!--hiragana-->
      <value value="赤い"/><!--kanji for “akai”-->
      <value value="赤く" phonogram="あかく"/><!--kanji for inflected “akaku”-->
      <value value="紅い"/><!--kanji for “akai”-->
      <value value="紅く" phonogram="あかく"/><!--kanji for inflected “akaku”-->
    </match>
    <match title="素性" phonogram="すじょう・そせい"><!--two hiragana readings of one kanji form-->
      <value value="すじょう"/><!--hiragana-->
      <value value="そせい"/><!--hiragana-->
      <value value="素性"/><!--kanji-->
    </match>
  </search-key-group>
</search-key-map>
 Example 27: A search key map for a dictionary in simplified Chinese

In this example, the value attribute of each match element specifies a Chinese word. The Pinyin spelling of that word is defined in both the phonogram attribute and as a search key in a value child element. An alternate Pinyin search key using tone numbers is also supplied in a value child element.

<search-key-map xml:lang="zh-hans">
    <search-key-group  href="dict.xhtml#chang">
        <match value="徜" phonogram="cháng">
            <value value="cháng"/>
            <value value="chang2"/>
        </match>
        <match value="徜徉" phonogram="chángyáng" href="dict.xhtml#changyang">
            <value value="chángyáng"/>
            <value value="chang2yang2"/>
        </match>
    </search-key-group>
</search-key-map>
 Example 28: A search key map for the headword "colour"

In this example, different match elements are used to specify search keys with the respective American and British spellings of the words. Note also the use of separate match elements to map parts of the dictionary entry like expressions and idioms.

<search-key-map xml:lang="en_GB">
   <search-key-group  href="pub.opf#epubcfi(/6/2[c-to-d]!/564[colour0001]">
       <!- Search keys for the entry itself ->
       <match value="colour">
           <value value="colours"/>
       </match>
       <match value="color" xml:lang="en_US">
           <value value="colors"/>
       </match>
       <match value="school colours"/>
       <match value="school colors" xml:lang="en_US"/>
       <!-- Idiom search keys. 
            The href must point to a location within the entry. -->
       <match title="lend/give colour to"
         href="pub.opf#epubcfi(/6/2[c-to-d]!/564[colour0001]/6[colour_1_0]">
           <value value="give colour to"/>
           <value value="lend colour to"/>
       </match>
       <match title="lend/give color to" xml:lang="en_US"
         href="pub.opf#epubcfi(/6/2[c-to-d]!/564[colour0001]/6[colour_1_0]">
           <value value="give color to"/>
           <value value="lend color to"/>
       </match>
       <match value="sail under false colours"
        href="pub.opf#epubcfi(/6/2[c-to-d]!/564[colour0001]/6[colour_1_1]"/>
       <match value="show one's true colours"
        href="pub.opf#epubcfi(/6/2[c-to-d]!/564[colour0001]/8[colour_1_2]"/>
       <match value="under colour of"
       href="pub.opf#epubcfi(/6/2[c-to-d]!/564[colour0001]/10[colour_1_3]"/>
       <match value="with flying colours"
       href="pub.opf#epubcfi(/6/2[c-to-d]!/564[colour0001]/12[colour_1_4]"/>
   </search-key-group>
</search-key-map>
 Example 29: Search key map for a fully inflected French verb

The inflected forms are declared as value child elements of the match element for the verb headword. Note that a Reading System may choose to only store the canonical form "regarder" in a compiled binary search index, and use a built-in lemmatization algorithm to map a search key to its canonical form.

<search-key-map xml:lang="fr">
  <search-key-group href="dictionary.xhtml#regarder">
    <match value="regarder">
      <value value="regarda"/>
      <value value="regardai"/>
      <value value="regardaient"/>
      <value value="regardais"/>
      <value value="regardait"/>
      <value value="regardant"/>
      <value value="regardas"/>
      <value value="regardasse"/>
      <value value="regardassent"/>
      <value value="regardasses"/>
      <value value="regardassiez"/>
      <value value="regardassions"/>
      <value value="regarde"/>
      <value value="regardent"/>
      <value value="regardera"/>
      <value value="regarderai"/>
      <value value="regarderaient"/>
      <value value="regarderais"/>
      <value value="regarderait"/>
      <value value="regarderas"/>
      <value value="regarderez"/>
      <value value="regarderiez"/>
      <value value="regarderions"/>
      <value value="regarderons"/>
      <value value="regarderont"/>
      <value value="regardes"/>
      <value value="regardez"/>
      <value value="regardiez"/>
      <value value="regardions"/>
      <value value="regardons"/>
      <value value="regardâmes"/>
      <value value="regardât"/>
      <value value="regardâtes"/>
      <value value="regardèrent"/>
      <value value="regardé"/>
      <value value="regardée"/>
      <value value="regardées"/>
      <value value="regardés"/>
    </match>
  </search-key-group>
</search-key-map>
 Example 30: Search key map showing that a search key can be mapped to several headwords

In this example, the search key "regardant" returns a match for both the headword "regarder" (verb) and "regardant" (adjective). Note how the title attribute is used to disambiguate the result form of the adjective.

<search-key-map xml:lang="fr">
  <search-key-group href="dictionary.xhtml#regardant">
    <match value="regardant" title="regardant (adjectif)"/>
  </search-key-group>
  <search-key-group href="dictionary.xhtml#regarder">
    <match value="regarder">
      ...
      <value value="regardant"/>
      ...
    </match>
  </search-key-group>
</search-key-map>

 2.5 Identification of the Dictionary or Glossary in the Package Document

A dictionary or glossary must be identified in the package document:

 2.5.1 Dictionary Identification

 2.5.1.1 Identification with dc:type

An EPUB Dictionary Publication must be identified as such in the package metadata of each of its Renditions by including a dc:type element with the value dictionary.

<metadata>
  ...
  <dc:type>dictionary</dc:type>
  ...
</metadata>
 2.5.1.2 Publication Consisting of a Single EPUB Dictionary

If an EPUB Dictionary Publication consists of a single EPUB Dictionary, it must contain exactly one Search Key Map Document for this Dictionary.

Exactly one Manifest item must be declared as this Search Key Map Document using the search-key-map and dictionary properties, as defined in Manifest item Properties.

Further identification of individual Content Documents is not necessary.

 2.5.1.3 Publication Consisting of Multiple EPUB Dictionaries

When a given Rendition of an EPUB Dictionary Publication consists of multiple EPUB Dictionaries, as is typically the case in bilingual and multilingual dictionaries, the set of files constituting each EPUB Dictionary must be identified using the collection  element of the package document with the role attribute set to dictionary.

The dictionary role restricts the collection element as follows:

note

The sequence of link elements in the collection does not affect rendering of elements in the spine [Publications301].

Every EPUB Dictionary must contain a dedicated Search Key Map Document; in other words, two different collection elements with the role dictionary must not contain link elements referencing the same Search Key Map Document.

Search Key Map Documents must be identified in the Manifest using the search-key-map and dictionary properties as defined in Manifest item Properties.

 2.5.1.4 Additional Dictionary Metadata

EPUB Dictionary metadata must be defined in the following manner:

Unless otherwise specified,  properties defined in the following sections for use in metadata are extending the default EPUB Package Metadata Vocabulary. They are referenceable using the base IRI http://idpf.org/epub/vocab/package/# .

 2.5.1.4.1 Identifying the Dictionary Type

The dictionary-type property may be used to refine the precise type of an EPUB Dictionary. The dictionary-type property accepts the values listed in the following table.  If none of these terms are explicitly specified, Reading Systems should treat "monolingual" as the assumed value.

Subtypes

Description

monolingual

dictionary with headwords and entry content in a single language

bilingual 

dictionary with headwords in source language, other entry content in target language

multilingual

dictionary with headwords in source language, other entry content in two or more target languages

thesaurus

synonym dictionary or thesaurus

encyclopedia

encyclopedia

spelling

special-purpose spelling dictionary

pronouncing

special-purpose dictionary of pronunciations

etymological

special-purpose dictionary of etymologies (word origins)

Example 31.

<dc:type id="tp">dictionary</dc:type>
<meta property="dictionary-type">thesaurus</meta>

note

The dictionary-type property provides Reading Systems with information that may be used to distinguish between major types of reference works and tailor the user experience accordingly (for instance, by using a less restrictive matching algorithm in an encyclopedia and a more restrictive one in a dictionary).

  2.5.1.4.2 Identifying the Audience

The audience property from  DCMI Metadata Terms [DCTERMS] may be used to indicate the target audience of the EPUB Dictionary Publication. When its value is drawn from a code list or other formal enumeration, the scheme attribute should be attached to identify its source.

Example 32.

<!-- For college/higher education -->
<meta property="dcterms:audience" scheme="onix:codelist28">05</meta>

This specification does not require or endorse the use of any specific scheme for the [DCTERMS] audience property.

 2.5.1.4.3 Identifying Source and Target Languages

In addition to the publication’s language(s) –as declared in [DCMES] language elements as per section 3.4.5 of EPUB Publications [Publications301]–  the source and target languages for each EPUB Dictionary must be defined in metadata using the source-language and target-language properties with values conforming to  [RFC5646].

In each of its Renditions,  a monolingual EPUB Dictionary Publication contains a single EPUB Dictionary with headwords and other entry content in the same language; hence, its source and target language values are considered identical. In contrast, an EPUB Dictionary in a bilingual EPUB Dictionary Publication always has distinct source and target language values, whether the EPUB Dictionary Publication is unidirectional (e.g. Latin-to-English) or bidirectional (e.g. both English-to-French and French-to-English).

Each EPUB Dictionary in the Publication must have exactly one source language and one or more target languages. Typically, a monolingual or bilingual EPUB Dictionary will have only one target language, whereas each EPUB Dictionary in a multilingual EPUB Dictionary Publication will have two or more target languages.

Please refer to the examples of monolingual, unidirectional bilingual, bidirectional bilingual, and multilingual dictionary  metadata.

 2.5.2 Glossary Identification

A Publication containing an EPUB Glossary must contain one or more Content Documents in which glossary content resides. Such Content Documents must be identified by adding the value glossary to the properties attribute in their manifest entries.

Example 33.

<manifest>
  ...
  <item href="glossary.xhtml" properties="glossary" ... />
  ...
</manifest>

A Publication containing an EPUB Glossary must contain at least one Search Key Map Document linking to terms defined in the glossaries. When the EPUB Glossary contains glossary terms in multiple languages, a dedicated Search Key Map Document may be used for each of these languages. All glossary terms for a common language should be covered by a single Search Key Map Document.

A Search Key Map Document for an EPUB Glossary must be identified in the Manifest using both the search-key-map and glossary properties as defined in Manifest item Properties.

note

 2.5.3 Manifest item Properties

The following tables define properties for use in the manifest item element’s properties attribute.

The Applies to field indicates which Publication Resource type(s) the given property may be specified on, the Cardinality field indicates the number of times the property must appear within the Package Document scope, and the Usage field indicates usage conditions.

Property Name

search-key-map

Description:

The search-key-map property indicates that the described Publication Resource constitutes a Search Key Map Document for the given Rendition of the EPUB Publication.

Applies to:

A Search Key Map Document.

Cardinality:

One or more.
Exactly one for each EPUB Dictionary in an EPUB Dictionary Publication.
At least one for an EPUB Glossary in an EPUB Publication.

Usage:

Required.

Property Name

dictionary

Description:

On Search Key Map Documents, the dictionary property indicates the document links to entries within an EPUB Dictionary.

Applies to:

Search Key Map Documents.

Cardinality:

One or more.

Usage:

Must be set if and only if the criterion specified in Description above is met.

Property Name

glossary

Description:

On XHTML Content Documents, the glossary property indicates that the document contains EPUB Glossary content (i.e. an element with the epub:type attribute containing the value glossary).

On Search Key Map Documents, the glossary property indicates the document links to terms within an EPUB Glossary.

Applies to:

XHTML Content Documents or Search Key Map Documents.

Cardinality:

One or more.

Usage:

Must be set if and only if the criterion specified in Description above is met.

 2.5.4 Package Document Examples

 2.5.4.1 Glossary Example

The following example shows a textbook Publication containing an EPUB Glossary.

Example 34.

<metadata>
  <dc:title>My Science Textbook</dc:title>
  ...
</metadata>
<manifest>
  <item id="textbook" href="textbook.xhtml" ... />
  <item id="searchkm" properties="search-key-map glossary" href="searchkeymap.xml"
    media-type="application/vnd.epub.search-key-map+xml" .../>
  <item id="glossary" properties="glossary" href="glossary.xhtml" ... />
</manifest>
 2.5.4.2 Monolingual Dictionary Example

The following example represents a Spanish monolingual EPUB Dictionary Publication. Note that no subtype is specified, which means the value monolingual should be assumed. As the Publication consists of only one EPUB Dictionary, the source-language and target-language metadata are added as package-level metadata.

Example 35.

<metadata>
  <dc:language>es</dc:language>
  <dc:type>dictionary</dc:type>
  <meta property="source-language">es</meta>
  <meta property="target-language">es</meta>
  …
</metadata>
<manifest>
  <item id="skmap" properties="search-key-map dictionary" href="searchkeymap.xml"
    media-type="application/vnd.epub.search-key-map+xml" .../>
  <item id="A-M" href="diccionario_A-M.xhtml" ... />
  <item id="N-Z" href="diccionario_N-Z.xhtml" ... />
</manifest>
 2.5.4.3 Unidirectional Bilingual Dictionary Example

The following example represents an English-to-Spanish bilingual EPUB Dictionary Publication; it is unidirectional and does not contain Spanish-to-English translations. The subtype is set to the value bilingual. As the Publication consists of only one EPUB Dictionary, the source-language and target-language metadata are added as package-level metadata.

Example 36.

<metadata>
  <dc:language>es</dc:language>
  <dc:language>en</dc:language>
  <dc:type id="tp">dictionary</dc:type>
  <meta property="dcterms:type" refines="#tp">bilingual</meta>
  <meta property="source-language">en</meta>
  <meta property="target-language">es</meta>
  …
</metadata>
<manifest>
  <item id="skmap" properties="search-key-map dictionary" href="searchkeymap.xml"
    media-type="application/vnd.epub.search-key-map+xml" .../>
  <item id="A-M" href="diccionario_A-M.xhtml" ... />
  <item id="N-Z" href="diccionario_N-Z.xhtml" ... />
</manifest>
 2.5.4.4 Bidirectional Bilingual Dictionary Example

The following example represents a bilingual EPUB Dictionary Publication containing distinct English-to-German and German-to-English EPUB Dictionaries.  Each EPUB Dictionary is identified by a collection element, with its own source-language and target-language properties, and including its own Search Key Map Document. In addition, there is an EPUB Glossary with its own Search Key Map Document. In an EPUB Dictionary Publication, a glossary might define abbreviations whose use is specific to the dictionary (as opposed to abbreviations in general use in a language).

Example 37.

<metadata>
  <dc:language>en</dc:language>
  <dc:language>de</dc:language>
  <dc:type id="tp">dictionary</dc:type>
  <meta property="dcterms:type" refines="#tp">bilingual</meta>
</metadata>
<manifest>
  <item id="en-skm" properties="search-key-map dictionary"
    href="searchkeymap_english.xml"
    media-type="application/vnd.epub.search-key-map+xml" ... />
  <item id="enA-M" href="english1.xhtml" ... />
  <item id="enN-Z" href="english2.xhtml" ... />
  <item id="de-skm" properties="search-key-map dictionary"
    href="searchkeymap_german.xml"
    media-type="application/vnd.epub.search-key-map+xml" ... />
  <item id="deA-M" href="german1.xhtml" ... />
  <item id="deN-Z" href="german2.xhtml" ... />
  <item id="gloss-skm" properties="search-key-map glossary" 
    href="searchkeymap_gloss.xml"
    media-type="application/vnd.epub.search-key-map+xml" ... />
  <item id="gloss" properties="glossary" 
    href="glossary_of_abbreviations_used_in_dictionary.xhtml" ... />
</manifest>
<collection role="dictionary">
  <metadata>
    <meta property="source-language">en</meta>
    <meta property="target-language">de</meta>
  </metadata>
  <link href="searchkeymap_english.xml"/>
  <link href="english1.xhtml"/>
  <link href="english2.xhtml"/>
</collection>
<collection role="dictionary">
  <metadata>
    <meta property="source-language">de</meta>
    <meta property="target-language">en</meta>
  </metadata>
  <link href="searchkeymap_german.xml"/>
  <link href="german1.xhtml"/>
  <link href="german2.xhtml"/>
</collection>
 2.5.4.5 Multilingual Dictionary Example

The following example shows metadata and manifest elements for a multilingual English-French-Arabic EPUB Dictionary Publication consisting of three distinct EPUB Dictionaries (one for each translation direction). Each dictionary is contained in a single file ordered according to its source language (the language of the words being looked up) with translation information provided in the two target languages.

Example 38.

<metadata>
  …
  <dc:language>en</dc:language>
  <dc:language>fr</dc:language>
  <dc:language>ar</dc:language>
  <dc:type id="tp">dictionary</dc:type>
  <meta property="dcterms:type" refines="#tp">multilingual</meta>
</metadata>
<manifest>
  <item id="english-to-french-arabic" href="english_searchkeymap.xml" 
    properties="search-key-map dictionary".../>
  <item id="english_dictionary" href="english_dictionary.xhtml" ... />
  <item id="french-to-english-arabic" href="french_searchkeymap.xml"
    properties="search-key-map dictionary".../>
  <item id="french_dictionary" href="french_dictionary.xhtml" ... />
  <item id="arabic-to-english-french" href="arabic_searchkeymap.xml" 
    properties="search-key-map dictionary".../>
  <item id="arabic_dictionary" href="arabic_dictionary.xhtml" ... />
</manifest>
<collection role="dictionary">
  <metadata>
    <meta property="source-language">en</meta>
    <meta property="target-language">fr</meta>
    <meta property="target-language">ar</meta>
  </metadata>
  <link href="english_searchkeymap.xml"[av][aw][ax]/>
  <link href="english_dictionary.xhtml"/>
</collection>
<collection role="dictionary">
  <metadata>
    <meta property="source-language">fr</meta>
    <meta property="target-language">ar</meta>
    <meta property="target-language">en</meta>
  </metadata>
  <link href="french_searchkeymap.xml"/>
  <link href="french_dictionary.xhtml"/>
</collection>
<collection role="dictionary">
  <metadata>
    <meta property="source-language">ar</meta>
    <meta property="target-language">en</meta>
    <meta property="target-language">fr</meta>
  </metadata>
  <link href="arabic_searchkeymap.xml"/>
  <link href="arabic_dictionary.xhtml"/>
</collection>

 3. Conformance Criteria

 3.1 Content Conformance

An EPUB Publication [Publications301] that complies with this specification must contain one or more EPUB Dictionaries and/or EPUB Glossaries. A Publication containing one or more EPUB Dictionaries is referred to as an EPUB Dictionary Publication.

An EPUB Dictionary Publication must meet all of the following criteria:

An EPUB Publication containing an EPUB Glossary must meet all of the following criteria:

 3.2 Reading System Conformance

A Reading System that complies with this specification must meet all of the following criteria:

A Reading System that complies with this specification should meet all of the following criteria:

 Appendix A. Schemas for Dictionaries in EPUB

A.1 Schema for Dictionary Content Documents

The schema for EPUB Dictionary Content Documents is available at http://www.idpf.org/epub/dict/schema/epub-dict-10.sch.

A.2 Schema for Search Key Map Documents

The schema for Search Key Map Documents is available at http://www.idpf.org/epub/dict/schema/search-key-map-10.rnc.

 Appendix B. Examples

 B.1 English Monolingual Dictionary Example

This section illustrates the structure of an EPUB Dictionary Publication containing a monolingual English EPUB Dictionary.  

Examples 39 and 40 below show abbreviated examples of a Content Document and Search Key Map Document. More extensive Content Document and Search Key Map Document examples are also available. Example 41 consists of a complete Package Document (note: the nav document referenced in the OPF is omitted from this example set).  

Though idioms are treated as search keys in the sample Search Key Map Document, note that this is at the Author’s discretion and not required by the specification.

Example 39: monolingual_dictionary.xhtml

<?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:epub="http://www.idpf.org/2007/ops"
      profile="http://www.idpf.org/epub/30/profile/content/">
<head>
<title>English Monolingual EPUB Dictionary Example</title>
<link rel="stylesheet" type="text/css" href="monolingual_dictionary.css"/>
</head>
<body epub:type="dictionary">

<h2>English Monolingual EPUB Dictionary Example</h2>

<article id="dock_1">
  <aside epub:type="condensed-entry" hidden="hidden">
    <dfn title="dock"><sup>1</sup>dock</dfn> 
    <span epub:type="part-of-speech">noun</span>,
    <em>pl</em> <strong>docks</strong>
    <ol epub:type="sense-list">
      <li><span epub:type="def"> : an area of water in a port where ships 
        are loaded, unloaded, or repaired</span></li>
      <li>US <span epub:type="def"> : a long
        structure that is built out into water and used as a place to get
        on, get off, or tie up a boat</span></li>
      <li>US <span epub:type="def"> : a place for loading materials onto
        ships, trucks, trains, etc.</span></li>
      <li><span epub:type="def"> : the place in a court of law where a 
        person who is accused of a crime stands or sits during a
        trial</span></li>
    </ol>
  </aside>
  <dfn title="dock"><sup>1</sup>dock</dfn> 
  <span epub:type="phonetic-transcription" lang="en-fonipa">/ˈdɑ:k/</span> 
  <span epub:type="part-of-speech">noun</span>,
  <em>pl</em> <strong>docks</strong>
  <ol epub:type="sense-list">
    <li>a. <span epub:type="def"> : an area of
      water in a port where ships are loaded, unloaded, or repaired</span> 
      <span epub:type="gram-info">[count]</span>
      <ul epub:type="phrase-list">
        <li><span epub:type="example">A crowd was waiting at the
          <em>dock</em> to greet them.</span> 
          <span epub:type="gram-info">[noncount]</span></li>
        <li><span epub:type="example">The ship is <strong>in dock</strong>
          for repairs.</span> &#8212;see also <a href="#dry_dock">DRY
          DOCK</a></li>
      </ul>
      b. <dfn>the docks</dfn> <span epub:type="def"> : the area in a town or
        city that has rows of docks, offices, and other buildings</span>
        <ul epub:type="phrase-list"> 
          <li><span epub:type="example">We went down to <em>the docks</em> 
            to watch the ships come in.</span></li>
        </ul>
    </li>
    <li><span epub:type="gram-info">[count]</span> 
      US <span epub:type="def"> : a long structure that is built out into
      water and used as a place to get on, get off, or tie up a boat</span>
      <!--a single phrase may be marked up as a phrase-list or as a 
          stand-alone phrase-group-->
      <ul epub:type="phrase-list">
        <li><span epub:type="example">Tie the boat to the
         <em>dock</em>.</span></li>
      </ul>
    </li>
    <li><span epub:type="gram-info">[count]</span> 
      US <span epub:type="def"> : a place for loading materials onto ships,
      trucks, trains, etc.</span> 
      <ul epub:type="phrase-list">
        <li epub:type="example">a <strong>loading dock</strong></li>
      </ul>
    </li>
    <li><span epub:type="gram-info">[count]</span> <span epub:type="def"> :
      the place in a court of law where a person who is accused of a crime
      stands or sits during a trial</span>
    </li>
    <li id="dock_1.in_the_dock">
      <dfn epub:type="idiom">in the dock</dfn> 
      <span epub:type="def"> : on trial for committing a crime</span>
      <ul epub:type="phrase-list">
        <li epub:type="example">He was arrested and is <em>in the dock</em>
          on charges of assault and battery.</li>
      </ul>
    </li>
  </ol>
</article>

<article id="dragon">
  <dfn title="dragon">drag·on</dfn>
  <span epub:type="phonetic-transcription" lang="en-fonipa">/ˈdrægən/</span>
  <span epub:type="part-of-speech">noun</span>,
  <em>pl</em> <strong>-ons</strong>
  <span epub:type="gram-info">[count]</span> <span epub:type="def"> : an
    imaginary animal that can breathe out fire and looks like a very large 
    lizard with wings, a long tail, and large claws</span>
</article>

Example 40: monolingual_dictionary_searchkeymap.xml

<?xml version="1.0" encoding="UTF-8"?>
<search-key-map xml:lang="en">
  <search-key-group href="monolingual_dictionary.xhtml#dock_1">
    <match value="dock">
      <value value="docks"/>
    </match>
    <match value="in the dock" 
      href="monolingual_dictionary.xhtml#dock_1.in_the_dock"/>
  </search-key-group>
  <search-key-group href="monolingual_dictionary.xhtml#dragon">
    <match value="dragon">
      <value value="dragons"/>
    </match>
  </search-key-group>
</search-key-map>

Example 41: monolingual_dictionary.opf

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<package xmlns="http://www.idpf.org/2007/opf" 
  xmlns:dc="http://purl.org/dc/elements/1.1/"
  xmlns:dcterms="http://purl.org/dc/terms/" version="3.0" xml:lang="en"
  unique-identifier="pub-id">
  <metadata>
    <dc:identifier id="pub-id">123456789</dc:identifier>
    <dc:title>Sample EPUB English Monolingual Dictionary</dc:title>
    <dc:language>en</dc:language>
    <dc:type>dictionary</dc:type>
    <meta property="dictionary-type">monolingual</meta>
    <meta property="source-language">en</meta>
    <meta property="target-language">en</meta>
    <meta property="dcterms:modified">2014-01-05T16:00:00Z</meta>
    <meta property="dcterms:audience" scheme="onix:codelist28">07</meta>
  </metadata>
  <manifest>
    <item id="skmap" properties="search-key-map dictionary" 
      href="monolingual_dictionary_searchkeymap.xml"
      media-type="application/vnd.epub.search-key-map+xml"/>
    <item id="dict" href="monolingual_dictionary.xhtml"
      media-type="application/xhtml+xml"/>
    <item id="nav" href="nav.xhtml" properties="nav"
      media-type="application/xhtml+xml"/>
    <item id="css" href="monolingual_dictionary.css" media-type="text/css"/>
  </manifest>
  <spine>
    <itemref idref="dict"/>
  </spine>
</package>

 B.2 French-English Bilingual Dictionary Example

This section illustrates parts of a bidirectional, bilingual French-English EPUB Dictionary Publication.

Example 42 consists of a complete Package Document (note: the nav document referenced in the OPF is omitted from this example set).  An extensive Content Document example is also available, consisting of entries from the French-to-English EPUB Dictionary of that publication.

Example 42: bilingual_dictionary.opf

<?xml version="1.0" encoding="UTF-8"?>
<package xmlns="http://www.idpf.org/2007/opf" 
    version="3.0" unique-identifier="uid">
  <metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
    <dc:identifier id="uid">urn:uuid:E0F57ECF-C130-47FE-B788-C32E2F2C9398</dc:identifier>
    <dc:title>Bilingual French-English Dictionary Sample</dc:title>        
    <dc:date>2011-09-01</dc:date>
    <meta property="dcterms:modified">2014-01-31T17:39:00Z</meta>
    <dc:language>en</dc:language>
    <dc:language>fr</dc:language>
    <dc:type id="tp">dictionary</dc:type>
    <meta property="dcterms:type" refines="#tp">bilingual</meta>
  </metadata>
  <manifest>
    <item id="fr-en_a-m" href="bilingual_dictionary_fr-en_a-m.xhtml"
          media-type="application/xhtml+xml" />
    <item id="fr-en_n-z" href="bilingual_dictionary_fr-en_n-z.xhtml"
          media-type="application/xhtml+xml" />
    <item id="fr-en-skm" href="bilingual_dictionary_fr-en_skm.xml"
          properties="search-key-map dictionary"          
          media-type="application/vnd.epub.search-key-map+xml" />
    <item id="en-fr_a-m" href="bilingual_dictionary_en-fr_a-m.xhtml"
          media-type="application/xhtml+xml" />
    <item id="en-fr_n-z" href="bilingual_dictionary_en-fr_n-z.xhtml"
          media-type="application/xhtml+xml" />
    <item id="en-fr-skm" href="bilingual_dictionary_en-fr_skm.xml"
          properties="search-key-map dictionary"
          media-type="application/vnd.epub.search-key-map+xml" />
    <item id="nav" href="nav.xhtml"
          media-type="application/xhtml+xml" properties="nav"/>
    <item id="css" href="bilingual_dictionary.css"
          media-type="text/css" />
  </manifest>
  <spine>
    <itemref idref="fr-en_a-m" />
    <itemref idref="fr-en_n-z" />
    <itemref idref="en-fr_a-m" />
    <itemref idref="en-fr_n-z" />
  </spine>
  <collection role="dictionary">
    <metadata>
      <meta property="source-language">en</meta>
      <meta property="target-language">fr</meta>
    </metadata>
    <link href="bilingual_dictionary_en-fr_skm.xml"/>
    <link href="bilingual_dictionary_en-fr_a-m.xhtml"/>
    <link href="bilingual_dictionary_en-fr_n-z.xhtml"/>
  </collection>
  <collection role="dictionary">
    <metadata>
      <meta property="source-language">fr</meta>
      <meta property="target-language">en</meta>
    </metadata>
    <link href="bilingual_dictionary_fr-en_skm.xml"/>
    <link href="bilingual_dictionary_fr-en_a-m.xhtml"/>
    <link href="bilingual_dictionary_fr-en_n-z.xhtml"/>
  </collection>
</package>

 B.3 Glossary Example

The Terminology section of this specification is available as an example of an EPUB Glossary. The example consists of a glossary content document, Search Key Map Document, and relevant package document structures.

 Appendix C. Contributors and Acknowledgments

This appendix is informative

EPUB has been developed by the International Digital Publishing Forum in a cooperative effort, bringing together publishers, vendors, software developers, and experts in the relevant standards.

The EPUB 3 Dictionaries and Glossaries Specification 1.0 was prepared by the International Digital Publishing Forum's Dictionaries Working Group, operating under a charter approved by the membership in January, 2012 under the leadership of:

The editors thank Apple, Merriam-Webster, and PONS for contributing examples to this specification.

Active members of the working group included:

 IDPF Members

 Invited Experts/Observers 

 References

 Normative References

[ContentDocs301] EPUB Content Documents 3.0 .

[DCMES] Dublin Core Metadata Element Set, Version 1.1 .

[DCTERMS] DCMI Metadata Terms .

[EPUB-Core-Media] EPUB 3 Core Media Types .

[EPUBCFI] EPUB Canonical Fragment Identifier (epubcfi) Specification  .

[HTML5] HTML5: A vocabulary and associated APIs for HTML and XHTML .

[Publications301] EPUB Publications 3.0.1 .

[RFC2119] Key words for use in RFCs to Indicate Requirement Levels  (RFC 2119). March 1997.

[RFC3987] Internationalized Resource Identifiers (IRIs) (RFC 3987). M Duerst, et al. January 2005.

[RFC5646] Tags for Identifying Languages  (RFC 5646). A. Phillips, M. Davis. September 2009.

[SSMLAttributes] SSML Attributes in EPUB Content Documents 3.0 .

[StructureVocab] EPUB 3 Structural Semantics Vocabulary .

[TR15] Unicode Normalization Forms .

[Unicode] The Unicode Consortium. The Unicode Standard.

[XML] Extensible Markup Language (XML) 1.0 (Fifth Edition) . T. Bray, et al. 26 November 2008.

[XMLNS] Namespaces in XML (Third Edition) . T. Bray, D. Hollander, A. Layman, R. Tobin. W3C. 8 December 2009.

 Informative References

[Indexes] EPUB Indexes 1.0