Processing key references to generate text or link text

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

OASIS DITA Technical Committee

Key references can be used to pull text from the key definition. This topic explains how to generate text from a key definition, regardless of whether the key reference also results in a link.

Note: The processing described in this topic is unrelated to the conkeyref attribute. In that case conkeyref is used to determine the target of a conref attribute, after which the normal conref rules apply.

Empty elements that include a key reference with a defined key might get their effective content from the key definition. Empty elements are defined as elements that meet the following criteria:

  • Have no text content, including white space
  • Have no sub-elements
  • Have no attributes that would be used as text content (such as alt on the image element)

When an empty element as defined above references a key definition that has a child topicmeta element, content from that topicmeta element is used to determine the effective content of the referencing element. Effective content from the key definition becomes the element content, with the following exceptions:

  • For empty image elements, effective content is used as alternate text, equivalent to creating an alt sub-element to hold that content.
  • For empty link elements, effective content is used as link text, equivalent to creating a linktext sub-element to hold that content.
  • For empty link and xref elements, a key definition can be used to provide a short description in addition to the normal effective content. If the key definition includes shortdesc inside of topicmeta, that shortdesc should be used to provide effective content for a desc sub-element.
  • The longdescref and longquoteref elements are empty elements with no effective content. Key definitions are not used to set effective text for these elements.
  • The param element does not have any effective content, so key definitions do not result in any effective content for param elements.
  • The indextermref element is not completely defined, so determining effective content for this element is also left undefined.
  • The abbreviated-form element is an empty element with special rules that determine its effective content.

Effective text content is determined using the following set of rules:

  1. For the abbreviated-form element, see the rules described in abbreviated-form
  2. For elements that also exist as a child of topicmeta in the key definition, effective content is taken from the first matching direct child of topicmeta. For example, given the following key definition, an empty author element with the attribute keyref="justMe" would result in the matching content "Just M. Name":
    <keydef keys="justMe" href="" format="html" scope="external">
        <author>Just M. Name</author>
  3. For elements that do not allow the href attribute, content is taken from the first keyword element inside of keywords inside of the topicmeta. For example, given the following key definition, empty keyword, term, and dt elements with the attribute keyref="nohref" would all result in the matching content "first":
    <keydef keys="nohref">
  4. For elements that do allow href, elements from within topicmeta that are legal within the element using keyref are considered matching text. For example, the xref element allows href, and also allows keyword as a child. Using the code sample from the previous item, an empty xref with keyref="nohref" would use all three of these elements as text content; after processing, the result would be equivalent to:
    <xref keyref="test"><keyword>first</keyword><keyword>second</keyword><keyword>third</keyword></xref>
  5. Otherwise, if linktext is specified inside of topicmeta, the contents of linktext are used as the effective content.
    Note: Because all elements that get effective content will eventually look for content in the linktext element, using linktext for effective content is a best practice for cases where all elements getting text from a key definition should result in the same value.
  6. Otherwise, if the element with the key reference results in a link, normal link text determination rules apply as they would for xref (for example, using the navtitle or falling back to the URI of the link target).

When the effective content for a key reference element results in invalid elements, those elements SHOULD be generalized to produce a valid result. For example, linktext in the key definition might use a domain specialization of keyword that is not valid in the key reference context, in which case the specialized element should be generalized to keyword. If the generalized content is also not valid, a text equivalent should be used instead. For example, linktext might include ph or a specialized ph in the key definition, but neither of those are valid as the effective content for a keyword. In that case, the text content of the ph should be used.