EPUB Dictionaries and Glossaries 1.0

Proposed Specification 26 September 2014

This version

http://www.idpf.org/epub/dict/epub-dict-20140926.html

Latest version

http://www.idpf.org/epub/dict/epub-dict.html

Previous version

http://www.idpf.org/epub/dict/epub-dict-20140204.html

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

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

› 1.3 Typographic Conventions

The following typographic conventions are used in this specification:

Informative markup examples are in white boxes.

›  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

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.

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

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

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.

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

• writing a Condensed Entry specifically for this use,
• using the corresponding entry from a smaller dictionary
• selecting key senses from the Detailed Entry
• removing certain elements of the Detailed Entry that are not critical for a quick scan of key meanings during lookup, such as examples, idioms, phonetic transcriptions, and etymologies.

› 2.2.2.2.2 The Condensed Entry

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.

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

<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

•  If the article element does not have a child aside element carrying an epub:type condensed-entry property, then the article represents both the Condensed Entry and Detailed Entry.
• Otherwise:
  • The condensed-entry aside element represents the Condensed Entry.
  • The article, excluding the condensed-entry aside, represents the Detailed Entry.

› 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 

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

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

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

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

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

› 2.2.4 Phonetic Transcriptions

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.

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

<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

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.

<article>
  <dfn>zebra</dfn>
  <span epub:type="part-of-speech">noun</span>
  <!--definitions for "zebra"--> 
</article>

› 2.2.5.2 Related Grammatical Information

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

<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

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.

<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

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.

<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

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

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.

<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

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

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.

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

<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

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.

<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

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

<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

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

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

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.

<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

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

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

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.

<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

A dl, body, section 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

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.

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

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

<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

• It must meet the conformance constraints on XML documents defined in XML Conformance.
• It must be valid to the Search Key Map Document schema, as defined in Appendix A.2, Search Key Map Document Schema, and conform to all content conformance constraints expressed in Search Key Map Document Definition.

File Properties

• The Search Key Map Document filename should use the file extension .xml.

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:

• When performing a lookup, if the user-provided word or phrase matches a search key contained in the Search Key Map, then the Reading System must render the matching content.
• The Reading System must process the Search Key Map Document in conformance with all Reading System conformance constraints expressed in Search Key Map Document Definition.

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

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.

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

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.

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.

href="xhtml/Dict_A-E.xhtml#dfn05"

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

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