A specialized topic for glossary entries.
The problem: DITA users need to publish glossaries and, more generally, identify the terminology for key concepts in an information set.
The solution: Add a specialized topic for reusable glossary entries.
Major - new topic type
Here are some examples of potential uses of a glossary entry.
Here is one example (http://tb1.siderean.com:7880/test/test2query3.jsp) of browsing based on different aspects of the subject matter.
Finally, because topics must be reusable in many different combinations, the glossary definitions for the terminology associated with topics must be reusable in many combinations as well.
The relationship between concepts and terms is complex. A term can have many meanings. For instance, "element" can have a chemical, programming, or XML sense. Conversely, a concept can have many labels. For instance, an XML delimiter for hierarchical structured content could be called an "element" or "tag". A strict formal model of the relationship between concepts and terms would allow many-to-many relationships between the two.
A content creator, however, usually wants a one-to-one mapping between key concepts and terms. That is, within an information set, most content creators would like each key concept to have a single preferred label and each key term to have a standard, unambiguous meaning.
Thus, the glossary specialization should focus on the common, simple case where a single glossary entry specifies both the concept and term. The specialization should scale to more complex cases where the concept and term need to be defined separately and associated by reference.
The simplest possible glossary entry might resemble the following:
<glossentry id="ddl"> <glossterm>Data Definition Language</glossterm> <glossdef>A language used for defining databases....</glossdef> </glossentry>
The glossary entry must be able to accept optional, additional detail about the term or concept:
In most cases, content providers won't want to display terminology or conceptual properties to the reader. Instead, these properties enable terminology or semantic processing. Regardless of the initial set of properties, organizations with specific needs must be able to extend the set of terminology or conceptual properties through specialization. Organizations must be able to share the specializations for terminology properties separately from conceptual properties based on their level of requirement in each area.
The content provider might need to maintain status and workflow metadata on the glossary entry, but that's a separate issue that applies generally to many different topic types.
A glossary entry that uses the full glossary capabilities might resemble the following:
<glossentry id="ddl"> <glossterm>Data Definition Language</glossterm> <glossdef>A language used for ....</glossdef> <glossdetail> <glalt-terms> <glacronym>DDL</glacronym> <glsynonym>Data Description Language</glsynonym> ... other alternative terms ... </glalt-terms> <glterm-detail> <glpart-of-speech>noun</glpart-of-speech> ... other terminology detail ... </glterm-detail> <glsubject-detail> <glscope-note>Covers SQL schema....</glscope-note> ... other concept detail ... </glsubject-detail> <example> <p>Before using ...</p> </example> </glossdetail> <glosslinks> <glrelated-entry href="glossary/database.dita"/> ... other relationships ... </glosslinks> </glossentry>
The content provider can use the DITA map to establish relationships between glossary entries, either based on the term or based on the concept. For instance, the content provider might indicate deprecated terms or related concepts. The content provider could also choose to identify the terminology and conceptual properties in separate topics with relationships. The map can also indicate glossary entries that should be used in terminology or semantic processing but not displayed to the reader.
Reuse of topics that are authored independently can result in glossary misalignment. For example, the topics might use different labels for the same concept or the same label for different concepts. To mitigate this problem, one approach could be to use keyref or conref when authoring mentions of the term so a different label can be assigned to the concept at any time.
If the term is embedded inline, however, the content provider should produce a glossary that reflects the terminology of the actual topics. That is, the reuser should specify the related synonyms (identifying the preferred definition) and generate a listing that is sorted and grouped by term.
Provides DITA adopters with an efficient way to enable glossary publishing, terminology processing, and semantic processing from a single set of definitions.