Very often in technical documentation area we are coming to need of publishing of terminology glossaries. DITA provides a way to define glossaries with some important aspects to keep in mind. This article explains specifics of glossaries support in DITA 1.1 and DITA 1.2. It also describes how DITAworks supports generation of glossaries.

Defining glossaries

Glossaries in DITA are defined using <glossentry> elements that represent a separate glossary entries. glossentry is defined as independent topic type specialized from standard DITA topic.

We have point out to significant difference about how glossaries are defined in DITA 1.1 and DITA 1.2.

In DITA 1.1 glossentries are quite simple topics consisting of glossterm and glossdef elements + optional related-links. As in DITA 1.2 content model of glossentry is pretty much developed, providing possibility to define abbreviations, synonyms and s.o.

In both DITA 1.1 and DITA 1.2 glossentry elements can be defined either in separate files (one entry per file) or inside of DITA composite topic (<dita> element).

Example:

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN"

 "glossary.dtd">
<dita>

 <glossentry id="Term_1_dita_glossentry_3">

    <glossterm>Term 1</glossterm>

    <glossdef>Definition 1</glossdef>

 </glossentry>

 <glossentry id="Term_2_dita_glossentry_4">

    <glossterm>Term 2</glossterm>

    <glossdef>Definition 2</glossdef>

 </glossentry>

 <glossentry id="Term_3_dita_glossentry_5">

    <glossterm>Term 3</glossterm>

    <glossdef>Definition 3</glossdef>

 </glossentry>

</dita>

Later glossentries are linked to publications using glossarylist element of bookmap.

Example:

<backmatter>

  <booklists>

    <indexlist/>

    <bibliolist/>

    <glossarylist >

        <topicref format="dita" href="../../TBD/Glossary_2.dita" toc="no" type="glossary"/>

    </glossarylist>

  </booklists>

</backmatter>

In DITA 1.2 support of glossaries is much more mature (see http://dita.xml.org/sites/dita.xml.org/files/DITA1.2GlossaryTerminologySpecialization.pdf). Content model itself is more developed and there is a way to make references to glossary entries from content using <term> element.

Publishing glossaries

DITA does not define any restrictions or guidelines as to processing of <glossarylist>. It is completely responsibility of processing engine. In DITA Open Toolkit 1.5. glossaries have no special processing and are published like ordinary topics. So we can say that glossary publication is not supported properly in DITA Open Toolkit yet.

Support in DITAworks

DITAworks 1.1 is based on DITA 1.1 and it uses all data structures available in DITA 1.1 to define glossaries. Possibilities of DITA 1.1 glossaries are enough to be able to define new glossary terms and link them to published documentation. There are some difficulties with linking to glossary topics from <term> elements though.

In DITAworks version 1.2 we plan to fully support DITA 1.2 and users will get all advantages of new support of glossaries in DITA 1.2 starting from this version.

As to publishing glossaries:  DITAworks 1.1 extends standard DITA Open Toolkit and provides convenient way to generate standard alphabetically grouped glossaries in our books based on <glossarylist> element.

This entry was posted on Monday, October 12th, 2009 at 14:33 by Alexej Spas and is filed under Features, Problems and Solutions. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.