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 may also include acronyms and acronym expansions. Glossentry topics may be assembled by authors or processes to create glossaries for various purposes, including books, websites, or other projects.
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 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>
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
Return to main page.
OASIS DITA Version 1.2 -- OASIS Standard, 1 December 2010
Copyright © OASIS Open 2005, 2010. All Rights Reserved.