Glossary entry topic

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 senses, the writer should 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

Acronyms defined within glossentry topics

The glossentry topic may 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>

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

Modules

The following DITA modules are provided for the glossary entry topic.

• glossentry.dtd, glossentry.ent, glossentry.mod (DTD)
• glossentryMod.xsd, glossentryGrp.xsd (Schema)