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:
- 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:
- Otherwise, if <linktext> is specified inside of
<topicmeta>, the contents of
<linktext> are used as the effective content.
NoteBecause 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.