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:
If the ABS term had appeared previously within the book, the same sentence could instead be rendered as follows:
See appendix for information about this element in OASIS document type shells.
+ topic/term abbrev-d/abbreviated-form
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.