Processing key references

When a key definition is bound to a resource addressed by @href or @keyref and does not specify "none" for the @linking attribute, all references to that key definition become navigation links to the bound resource. When a key definition is not bound to a resource or specifies "none" for the @linking attribute, references to that key do not become navigation links.

When a key definition has a <topicmeta> subelement, elements that refer to that key and that are empty may get their effective content from the first matching subelement of the <topicmeta> subelement of the key-defining topicref. If no matching element is found, the contents of the <linktext> tag, if present, should be used. Elements within <linktext> that do not match the content model of the key reference directly or after generalization should be skipped. For <link> tags with a keyref attribute, the contents of the <shortdesc> tag in the key-defining element should provide the <desc> contents.

When a key definition has no @href value and no @keyref value, references to that key will not result in a link, even if they do contain an @href attribute of their own. If the key definition also does not contain a <topicmeta> subelement, empty elements that refer to the key (such as <link keyref="a"/> or <xref keyref="a" href="fallback.dita"/>) are removed.

Matching element content for key references contained in @keyref or @conkeyref attributes falls into one of two categories:

For elements on which no @href attribute is available (such as cite, dt, keyword, term, ph, indexterm, index-base, and indextermref, and their specializations), matching content is taken from the <keyword> or <term> elements within <keywords> within <topicmeta>. If more than one <keyword> or <term> is present, the matching content is taken from the first of them.
For elements that in addition to @keyref or @conkeyref do specify an @href attribute (such as author, data, data-about, image, link, lq, navref, publisher, source, topicref, xref, and their specializations), matching content includes all elements from within the key definition element that are in valid context within the key reference. Elements that are invalid within the key reference element directly or after generalization are not included or are filtered out.

For key reference elements that become navigation links, if there is no matching element in the key definition, normal link text determination rules apply as for <xref>.

If a referencing element contains a key reference with an undefined key, it is processed as if there were no key reference, and the value of the @href attribute is used as the reference. If the @href attribute is not specified either, the element is not treated as a navigation link. If it is an error for the element to be empty, an implementation may give an error message, and may recover from this error condition by leaving the key reference element empty.

For topic references that use the @keyref attribute, the effective value of the <topicref> element is determined as follows:

The effective resource bound to the <topicref> element is determined by resolving all intermediate key references. Each key reference is resolved either to a resource addressed directly by URI reference in an @href attribute, or to no resource. Processors may impose reasonable limits on the number of intermediate key references they will resolve. Processors should support at least three levels of key references.

Note: This rule applies to all topic references, including those that define keys. Thus, the effective bound resource for a key definition that uses the @keyref attribute cannot be determined until the key space has been constructed.

The attributes that are common to a key definition element and a key reference element using that key, other than the @keys and @id attributes, are combined as for content references, including the special processing for the @xml:lang, @dir, and @translate attributes. There is no special processing associated with either the @locktitle or the @lockmeta attributes when attributes are combined.
When attributes are combined, the attributes on a key definition element take precedence over the attributes on a key reference element. For a chain of key reference elements, the priority for combining attributes is:
- First key-defining element
- Second key-defining element
- ...
- last key-defining element
- key reference element
Content from a key reference element and a key-defining element is combined following the rules for combining metadata between maps and other maps and between maps and topics. The @lockmeta attribute is honored when metadata content is combined.
The combined attributes and content cascade from one map to another or from a map to a topic, but this is controlled by existing rules for cascading, which are not affected by the use of key references.

2.1.3.4.3.3 Processing key references