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>
- 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
<term>
markup in a
particular collection of topics. Acronyms defined within glossentry topics
- <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