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.
- 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.
- 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.
- 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.
- 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.
|topic (technical content), map (technical content), concept, ditabase, glossary, glossentry, glossgroup, reference, task, bookmap||no content|
+ topic/term abbrev-d/abbreviated-form
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>
An Anti-lock Braking System (ABS) helps a driver to stop. For this reason many find an ABS useful.
|Name||Description||Data Type||Default Value||Required?|
|keyref||The keyref attribute on <abbreviated-form> is used to reference a term, typically defined in a <glossentry> topic. See The keyref attribute for details about syntax and processing concerns.||CDATA||#REQUIRED||Yes|
|univ-atts attribute group (includes select-atts, id-atts, and localization-atts groups)||A set of related attributes, described in univ-atts attribute group|
|global-atts attribute group (xtrf, xtrc)||A set of related attributes, described in global-atts attribute group|
|class, outputclass||Common attributes described in Other common DITA attributes|