addendum for DITA 1.1 glossary

[Erik Hennum <ehennum@us.ibm.com>]

Hi, DITA Committee:

I've revised the note from a couple of weeks back to provide an updated summary as an addendum to the original write up:

http://www.oasis-open.org/apps/org/workgroup/dita/download.php/15140/Issue14.html

DITA 1.1 provides a glossary definition to handle the simple case and to provide a stable foundation for a more complete glossary capability in DITA 1.2.  That is, the simple glossary definition for DITA 1.1 is a snapshot of progress toward a more robust glossary definition.

For an example of the limitations to be addressed in DITA 1.2, many content publishers will need to distinguish a labelling abbreviation from the full term. In addition, the DITA 1.2 glossary should take advantage of the ability to bind a mention of a glossary term with a sense definition by means either of the DITA 1.2 key referencing mechanism or of the matching mechanism for mentions and definitions.  Finally, DITA 1.2 should satisfy the requirements of some content publishers for a more complete terminology and semantic representation.  DITA 1.2 might specialize the <conbody> element as <glossdetail> to meet these requirements. 


Thanks,


Erik Hennum
ehennum@us.ibm.com


DITA 1.1 provides a topic specialization to define a sense of a glossary term for a book or online deliverable.

Each sense of a term is defined in a separate topic.  A formatting process can collate these definitional topics based on the term and indent the defined senses under the term.

Putting each glossary definition in a separate topic is better suited for translation because terms that are the same in one language may be different in others. Thus, glossary definitions should be collated based on the translated terms rather than assuming that a term will have the same set of definitions in all languages.

These glossary definition topics can be provided within a single ditabase file for the simple case or in separate files.  The latter approach facilitates reuse because deliverables can assemble the glossary for the terminology used in content by selecting from a pool of available glossary definitions. 

Here is the definition of the glossary topic specialization in Schema syntax:

  <xs:complexType name="glossentry.class">
        <xs:sequence>
          <xs:group ref="glossterm"/>
          <xs:group ref="glossdef"/>
          <xs:group ref="related-links" minOccurs="0"/>
        </xs:sequence>
         <xs:attribute name="id" type="xs:ID" use="required"/>
        <xs:attribute name="conref" type="xs:string"/>
        <xs:attributeGroup ref="select-atts"/>
        <xs:attribute ref="ditaarch:DITAArchVersion" />
        <xs:attribute name="outputclass" type="xs:string"/>
        <xs:attribute ref="xml:lang"/>
        <xs:attributeGroup ref="global-atts"/>
        <xs:attribute ref="class" default="- topic/topic concept/concept glossentry/glossentry "/>
  </xs:complexType>

  <xs:element name="glossterm" type="glossterm.class"/>
  <xs:complexType name="glossterm.class" mixed="true">
    <xs:choice minOccurs="0" maxOccurs="unbounded">
      <xs:group ref="title.cnt"/>
    </xs:choice>
    <xs:attribute name="outputclass" type="xs:string"/>
    <xs:attributeGroup ref="id-atts"/>
    <xs:attributeGroup ref="global-atts"/>
    <xs:attribute ref="class" default="- topic/title concept/title glossentry/glossterm "/>
  </xs:complexType>

  <!-- placeholder - glossdef specializes the outer, section-like element for shortdesc / abstract -->
  <xs:element name="glossdef" type="glossdef.class"/>
  <xs:complexType name="glossdef.class" mixed="true">
    <xs:choice minOccurs="0" maxOccurs="unbounded">
      <xs:group ref="title.cnt"/>
    </xs:choice>
    <xs:attribute name="outputclass" type="xs:string"/>
    <xs:attributeGroup ref="id-atts"/>
    <xs:attributeGroup ref="global-atts"/>
    <xs:attribute ref="class" default="- topic/shortdesc concept/shortdesc glossentry/glossdef "/>
  </xs:complexType>

Note that the glossdef will use the section-like content model for the abstract (embedding the <shortdesc> preview) as proposed for DITA 1.1

Here's the definition in DTD syntax:

<!ELEMENT glossentry      ((%glossterm;), (%glossdef;), (%related-links;)?)>
<!ATTLIST glossentry
             id         ID                               #REQUIRED
             conref     CDATA                            #IMPLIED
             %select-atts;
             xml:lang   NMTOKEN                          #IMPLIED
             %arch-atts;
             outputclass 
                        CDATA                            #IMPLIED
             domains    CDATA                "&included-domains;"
             %global-atts;
             class CDATA "- topic/topic concept/concept glossentry/glossentry ">

<!ELEMENT glossterm         (%title.cnt;)*> 
<!ATTLIST glossterm
             %id-atts;
             outputclass 
                        CDATA                            #IMPLIED    >
<!ATTLIST title     %global-atts;  class CDATA "- topic/title "      >

<!-- placeholder - glossdef specializes the outer, section-like element for shortdesc / abstract -->
<!ELEMENT glossdef     (%title.cnt;)*>
<!ATTLIST glossdef
             %id-atts;
             outputclass 
                        CDATA                            #IMPLIED    >
<!ATTLIST shortdesc %global-atts;  class CDATA "- topic/shortdesc "  >

Here are two simple examples:

<glossentry id="ac-air">
    <glossterm>AC</glossterm>
    <glossdef>Air conditioning</glossdef>
</glossentry>

<glossentry id="ac-electric">
    <glossterm>AC</glossterm>
    <glossdef>Alternating current</glossdef>
</glossentry>

The output would resemble the following example:

AC
    1.  Air conditioning
    2.  Alternating current