3.2.4.2.1 abbreviated-form

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

Rendering <abbreviated-form> references to glossentry

When the writer provides a keyref to a glossentry topic that contains a <glossSurfaceForm> element, a process should emit the surface form in introductory contexts where the term might be unfamiliar to the reader or in other contexts where a precise term is appropriate. In other contexts a process should submit 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 may 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 may emit the surface form as a hover tooltip on every instance of the term.

Renderers should follow these rules when displaying an <abbreviated-form> element that refers to a glossentry topic:

1. In an introductory context, processors SHOULD render the surface form of the term by displaying the contents of the glossSurfaceForm element from the referenced glossentry topic.
2. If the glossentry topic does not contain a glossSurfaceForm element or the glossSurfaceForm element is empty, processors SHOULD render the contents of the glossterm element in introductory contexts.
3. In non-introductory contexts, processors SHOULD render the abbreviated form of the term by displaying the contents of the <glossAcronym> element from the referenced glossentry topic.
4. If the glossentry topic does not contain a glossAcronym element or the glossAcronym element is empty, processors SHOULD render the contents of the glossterm element in non-introductory contexts.

For instance, if the topic with the keyref to the "abs" key 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."

Rendering <abbreviated-form> references to other topics

Typically the <abbreviated-form> is used to refer to a glossentry topic. In situations where it refers to another topic type, renderers should display the content of the referenced topic's title.

Contains

Contained by

Inheritance

+ topic/term abbrev-d/abbreviated-form

Example

The term and acronym may be defined as follows, in a glossentry topic. Note that the id 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 that wishes to reference this topic may do so using the abbreviated-form element. The keyref attribute should reference 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

Previous Topic:  3.2.4.2 Glossary related elements

Next Topic:  3.2.4.2.2 glossref

Parent Topic:  3.2.4.2 Glossary related elements

Sibling Topics:

3.2.4.2.2 glossref

3.2.4.2.3 glossgroup