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.
@conkeyrefattribute. In that case
@conkeyrefis used to determine the target of a
@conrefattribute, after which the normal
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:
<image>elements, effective content is used as alternate text, equivalent to creating an
<alt>sub-element to hold that content.
<link>elements, effective content is used as link text, equivalent to creating a
<linktext>sub-element to hold that content.
<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>should be used to provide effective content for a
<longquoteref>elements are empty elements with no effective content. Key definitions are not used to set effective text for these elements.
<param>element does not have any effective content, so key definitions do not result in any effective content for
<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:
<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>
@hrefattribute, content is taken from the first
<keyword>element inside of
<keywords>inside of the
<topicmeta>. For example, given the following key definition, empty
<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>
@href, elements from within
<topicmeta>that are legal within the element using
@keyrefare considered matching text. For example, the
@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:
<linktext>is specified inside of
<topicmeta>, the contents of
<linktext>are used as the effective content.
<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.
<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,
<ph> or a
<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.
Return to main page.
Standards Track Work Product
|Copyright © OASIS Open 2016. All Rights Reserved.||25 October 2016|