<abbreviated-form>

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.

If the referenced topic is not a <glossentry> topic (or a specialization of <glossentry>), the title of the topic SHOULD be displayed.
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.
Otherwise, if <abbreviated-form> is located in an introductory context, processors SHOULD render the contents of the <glossterm> element from the referenced <glossentry> topic.
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.
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.

Darwin Information Typing Architecture (DITA) Version 1.3 Part 3: All-Inclusive Edition