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:

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:

For the <abbreviated-form> element, see the rules described in <abbreviated-form>
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>
```
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>
```
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>
```
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.
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.