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:
- 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:
If the ABS term had appeared previously within the book, the same sentence could instead be rendered as follows:
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>
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.
|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|