Home > Appendix > DITA 1.3 specification > Architectural specification: All-inclusive edition > DITA addressing > Indirect key-based addressing > Processing key references to generate text or link text

Processing key references to generate text or link text

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:

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:

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="http://www.example.com/my-profile" format="html" scope="external">
      <topicmeta>
        <author>Just M. Name</author>
      </topicmeta>
    </keydef>
  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">
      <topicmeta>
        <keywords><keyword>first</keyword><keyword>second</keyword><keyword>third</keyword></keywords>
      </topicmeta>
    </keydef>
  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.