2.7.1.7 Glossary entry topic

Each glossary entry <glossentry> topic defines a single sense of one term. Besides identifying the term and providing a definition, the topic accommodates basic terminology information, such as part of speech. A glossentry topic might also include acronyms and acronym expansions. Glossentry topics can be assembled by authors or processes to create glossaries for various purposes, including books, websites, or other projects.

The purpose of the glossary entry topic

Defining terminology in a glossary ensures that a team of writers uses the same term for the same concept. A glossary added to a book or available online in conjunction with other subject matter provides the reader with definitions of unfamiliar terms and expands acronyms.

The structure of the glossentry topic

The top-level element for a DITA glossentry topic is the <glossentry> element. Every glossentry topic contains a <glossterm> and a <glossdef> element and optional <related-links>.

Where a term has multiple definitions, best practices call for the writer to create multiple glossentry topics with the same term in the <glossterm> element but different definitions in the <glossdef> element. A process can collate and group glossentry topics by term when generating formatted output. Note that definitions with the same term in one language can have different terms in other languages, so translations can result in different collation and grouping of the same set of glossentry topics.

Here is an example of a simple glossentry topic:

<glossentry id="ddl">
    <glossterm>Data Definition Language</glossterm>
    <glossdef>A language used for defining database schemas.</glossdef>
</glossentry>

To create a glossary, authors can group multiple entries together by

authoring in a single document using the Glossary group document type
authoring in a single document under a container topic using the ditabase document type
referencing the glossentry topics from a map
using an automated process

For example, an automated process might assemble glossentry topics from a repository based on the <term> markup in a particular collection of topics.

Acronyms defined within glossentry topics

The glossentry topic can be used to provide expansions of acronyms in online text and assist in the proper translation of acronyms into multiple languages. The acronym elements of the glossentry topic include the following:

<glossterm> to enter the full text to which the acronym refers
<glossSurfaceForm> to provide the appropriate rendering of the full text plus the acronym in each language
<glossAcronym> to provide the acronym text itself

Here is an example of an acronym used in the glossentry topic:

<glossentry id="wmd" xml:lang="en">
  <glossterm>Weapons of Mass Destruction</glossterm>
  <glossBody>
    <glossSurfaceForm>Weapons of Mass Destruction (WMD)</glossSurfaceForm>
    <glossAlt>
      <glossAcronym>WMD</glossAcronym>
    </glossAlt>
  </glossBody>
</glossentry>

Here is an example of how the glossentry topic would be translated into Spanish:

<glossentry id="wmd" xml:lang="es">
  <glossterm>armas de destrucción masiva</glossterm>
  <glossBody>
    <glossSurfaceForm></glossSurfaceForm>
    <glossAlt>
      <glossAcronym></glossAcronym>
    </glossAlt>
  </glossBody>
</glossentry>

Note that because no acronym exists for the term in Spanish, the <glossSurfaceForm> and <glossAcronym> elements are left blank.

In some languages, the surface form that expands the acronym in its first use handles the formatting differently than in English. For example, in Polish, the acronym precedes the expansion.

<glossentry id="eu" xml:lang="pl">
  <glossterm>Unia Europejska</glossterm>
  <glossBody>
    <glossSurfaceForm>UE (Unia Europejska)</glossSurfaceForm>
    <glossAlt>
      <glossAcronym>UE</glossAcronym>
    </glossAlt>
  </glossBody>
</glossentry>

For more information about the correct use of acronym expansions in multiple languages, see Best Practice for Managing Acronyms and Abbreviations in DITA, produced by the DITA Translation Subcommittee. http://www.oasis-open.org/committees/download.php/29734/AcronymBestPractice_08112008.doc