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.
@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:
@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:
<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.<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.<longdescref>
and <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 <param>
elements.<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>
@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>
@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>
<linktext>
is specified inside of
<topicmeta>
, the contents of
<linktext>
are used as the effective content. <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.<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.
Return to main page.
dita-v1.3-errata01-os-part1-base-complete Standards Track Work Product | Copyright © OASIS Open 2016. All Rights Reserved. | 25 October 2016 |