The value -dita-use-conref-target is available on enumerated attributes and can also be specified on other attributes. When an element uses
@conref
to pull in content, for any of its attributes assigned a value of
"-dita-use-conref-target", the resulting value for those attributes is also pulled in from the
referenced element.
Ordinarily, when an element uses @conref
, any other attributes specified locally
will be preserved when the reference is resolved. This causes problems when attributes are
required, because required attributes must be specified regardless of whether the
@conref
attribute is present. The purpose of the -dita-use-conref-target
value is to allow the author to specify a value for a required attribute while still
allowing the conref resolution process to use the matching attribute from the referenced
element. The value has the same result when the attribute is not required.
The -dita-use-conref-target token is allowed on any attribute where
it is not prohibited by the XML grammar files or by the specification. For example, while
@cols
on the <tgroup>
element is defined as being a
number, this token is implicitly allowed in order to support conref processing for
<tgroup>
. However, the token is not allowed for the
@id
attribute on the <topic>
element, because
"-dita-use-conref-target" does not fit the syntax required by the XML grammar files.
This example shows a map where the <topichead>
element uses
@conref
. It specifies the @navtitle
attribute as well as
the @toc
attribute. In the resolved element, @navtitle
from
the referencing element is not preserved because it uses -dita-use-conref-target. The
@toc
attribute from the referencing element overrides the
@toc
attribute on the referenced element using normal conref resolution
rules.
@navtitle
was required on
the <topichead>
element. While it is no longer required, the example
still illustrates the expected processing for both required and non-required
attributes.<map><title>Conref demonstration</title>
<topichead id="heading"
navtitle="This is a heading"
toc="yes"
linking="normal">
<topicref href="topic.dita" navtitle="content"/>
</topichead>
<topichead conref="#heading"
navtitle="-dita-use-conref-target"
toc="no">
</topichead>
</map>
<map><title>Conref demonstration</title>
<topichead id="heading"
navtitle="This is a heading"
toc="yes"
linking="normal">
<topicref href="topic.dita" navtitle="content"/>
</topichead>
<topichead navtitle="This is a heading"
toc="no"
linking="normal">
<topicref href="topic.dita" navtitle="content"/>
</topichead>
</map>