Processing key references to generate text or link text

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.

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

1. 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>

2. 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>

3. 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>

4. 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.
5. 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.