abbreviated-form

Darwin Information Typing Architecture (DITA) Version 1.3 Part 2: Technical Content Edition

Document
Darwin Information Typing Architecture (DITA) Version 1.3 Part 2: Technical Content Edition
Version
1.3
Author
OASIS DITA Technical Committee

The abbreviated-form element represents a reference to a term that might appear in an abbreviated form (often an acronym). The long and short forms of the term are generally defined in a glossentry topic. Processors display the referenced term when rendering an abbreviated-form element.

Rendering the abbreviated-form element

The abbreviated-form element is intended to reference a glossentry topic that contains both a term and an abbreviated form of that term. The topic might also provide a surface form that differs from the original term. The full term or surface form is rendered in introductory contexts where the term might be unfamiliar to a reader or in other contexts where a precise term is appropriate. In other contexts a processor substitutes the abbreviated form of the term. Note that the definition of an introductory context will differ for every deliverable format.

For instance, a process composing a book deliverable might emit the surface form of a term on the first reference to the glossentry topic within the book or for every reference within a copyright or a warranty-related warning. A process generating an online page might emit the surface form as a hover tooltip on every instance of the term.

The following rules determine how to render an abbreviated-form element. As described, the definition of "introductory context" will vary based on the rendered format and processor.
  1. If the referenced topic is not a glossentry topic (or a specialization of glossentry), the title of the topic SHOULD be displayed.
  2. Otherwise, if abbreviated-form is located in an introductory context, and the referenced topic contains a non-empty glossSurfaceForm element, processors SHOULD render the contents of the glossSurfaceForm element from the referenced glossentry topic.
  3. Otherwise, if abbreviated-form is located in an introductory context, processors SHOULD render the contents of the glossterm element from the referenced glossentry topic.
  4. Otherwise (in non-introductory contexts), if the referenced glossentry topic contains a non-empty glossAcronym element, processors SHOULD render the abbreviated form of the term by displaying the contents of the glossAcronym element from the referenced glossentry topic.
  5. Otherwise, processors SHOULD render the contents of the glossterm element from the referenced glossentry topic.

For instance, if an abbreviated-form element with the attribute keyref="abs" provided the first occurrence of the ABS term within a book, the sentence could be rendered as follows:

"The Anti-lock Brake System (ABS) will prevent the car from skidding in adverse weather conditions."

If the ABS term had appeared previously within the book, the same sentence could instead be rendered as follows:

"The ABS will prevent the car from skidding in adverse weather conditions."

Content models

See appendix for information about this element in OASIS document type shells.

Inheritance

+ topic/term abbrev-d/abbreviated-form

Example

The term and acronym can be defined as follows, in a glossentry topic. Note that the id attribute of the topic does not need to match the term or acronym.

<glossentry id="abs-definition">
  <glossterm>Anti-lock Braking System</glossterm>
  <glossBody>
    <glossSurfaceForm>Anti-lock Braking System (ABS)</glossSurfaceForm>
    <glossAlt>
      <glossAcronym>ABS</glossAcronym>
    </glossAlt>
  </glossBody>
</glossentry>

Note that there are three important elements for the purposes of rendering the abbreviated-form element.

  • The glossSurfaceForm element defines the term as it should be displayed in an introductory context.
  • The glossAcronym element defines the acronym associated with this term.
  • The glossterm element provides a fallback version of the term, which will be displayed in situations where the preferred representation is unavailable.

The glossentry topic will be added to a map in the following manner. Again, the key (in this case "abs") does not need to match the term or acronym value.

<glossref keys="abs" href="antilock.dita"/>

An author who wants to reference this topic can do so by using the abbreviated-form element. The keyref attribute references the value defined on the keys attribute above.

<section>An <abbreviated-form keyref="abs"/> helps a
driver to stop. For this reason many find an
<abbreviated-form keyref="abs"/> useful.
</section>
When rendered, the introductory usage of "abs" will display the surface form of the referenced term, while the later uses will display the acronym, as demonstrated here.
An Anti-lock Braking System (ABS) helps a driver to stop. For this reason many find an ABS useful.

Attributes

The following attributes are available on this element: Universal attribute group, outputclass, and keyref.