Schema Documentation - Book Profile
version 1.0

The section variant of the glossary element

On this page:

The glossary element represents a glossary, pronunciation guide or other section that exclusively defines terms or phrases.

The Section variant is an adaptation for use including terms and definitions that have been grouped as a separate section in a work, and where the glossary contains structured groups of entries by topic, letter of the alphabet, etc.

The republishing of documents often requires the insertion of content that was not a part of the original source document. For example, in the case of indexes, bibliographies and other ordered sections, this requirement may take the form of placeholder sections to mark gaps in the alphabetic list of entries. To indicate that an element presents content that is a deviation from the source, the role attribute can be used with the value custom. No behaviors are defined for how a processing agent should handle sections so identified, however.

Usage details available in the Usage Details section.

Usage Example

<glossary>
    <section>
        <h>A</h>
        <entry>
            <term>Arroba</term>
            <definition>A weight equal to twenty-five pounds Spanish</definition>.
        </entry>
        …
    </section>
    …
</glossary>

Allowed parents

backmatter, frontmatter and section

Allowed children

This element must not contain text.

This element may contain the following children: aside, block, entry, h, hd, object, p, pagebreak, section and transition

Content model

optional attributes: @about, @by, @class, @content, @datatype, @desc, @its:dir, @its:translate, @property, @rel, @resource, @rev, @role, @sel:selid, @typeof, @xml:base, @xml:id, @xml:lang and @xml:space
a mix of
• an optional h
• zero or more of
any of the 7 elements: aside, block, hd, object, p, pagebreak and transition
end of mix
a choice of
either
first a mix of
• one or more of entry
• zero or more of
any of the 2 elements: hd and pagebreak
end of mix
followed by zero or more of section
or
first zero or more of entry
followed by one or more of section
end of choice

Variants

This element exists in 2 variants. The other variant is the block variant.

Namespace

http://www.daisy.org/ns/z3998/authoring/

Usage Details

The greatest advantage to using the dedicated glossary element over hand-rolled solutions is the automatic association it allows when an entry contains exactly one term and one definition (which covers most glossaries and definition lists). The element is also intended to provide flexibility to accommodate the various forms definition lists take in production. A numbered definition list, for example, can be created using the Content Rendition feature's prefix attribute: 

<glossary>
   <entry rend:prefix="1.">
      <term>evolution</term> — <definition>the process by which ...</definition>
   </entry>
   <entry rend:prefix="2.">
      <term>gene</term> — <definition>a segment of DNA...</definition>
   </entry>
</glossary>

The definitions could be turned into a variable list through use of CSS styles. Removing the em dashes and attaching a class attribute to the glossary element in the preceding example with a value of varlist, for example, would allow the creation of the following style definitions to re-flow the content: 



glossary.varList > entry > term {
   display: block;
   padding-bottom: .2em
   font-weight: bold;
}

glossary.varList > entry > definition {
   display: block;
   margin-left: 2em;
}

Although it is recommended that the glossary element be used whenever possible, there are no restrictions against creating definition lists using other combinations of elements. The list element can simplify aspects (auto numbering, specifically), but at the price of having to explicitly link the terms and definitions in each entry. The first example above could be reformulated as a list as follows: 

<list type="ordered">
   <item><term ref="def1">evolution</term> — <definition xml:id="def1">the process by which ...</definition></item>
   <item><term ref="def2">gene</term> — <definition xml:id="def2">a segment of DNA...</definition></item>
</list>

A variable list can also be implemented in a similar fashion with the addition of CSS styles: 

<list class="varList">
   <item>
      <term ref="defn1">evolution</term>
      <definition xml:id="defn1">the process by which ...</definition>
   </item>
   <item>
      <term ref="defn2">gene</term>
      <definition xml:id="defn2">a segment of DNA...</definition>
   </item>
</list>

The absence of the type attribute on the list element in the preceding example outputs each item without a prefix, similar to the default formatting for glossary entries.

There are times where even more simplicity is needed. The glossary and list elements can be used for single definitions, but are typically more tagging than is needed, especially when the definition occurs in the flow of the body: 

<p>
   A <term ref="defn01">gene</term> is <definition xml:id="defn01">a segment of DNA...</definition>. 
</p>

The convenience of using term and definition in these ways comes at the price of having to explicitly link the elements together via their ref and xml:id attributes, however.