Using the -dita-use-conref-target value

The value -dita-use-conref-target is available on enumerated attributes, and may also be specified manually on other attributes. It indicates that when the element uses conref to pull in content, the attribute with a value of "-dita-use-conref-target" should also be pulled in from the target.

Ordinarily, when an element uses conref, any other attributes specified locally will be preserved. This feature can be used to override settings on the conref target that may not be appropriate in the new context. This causes problems when attributes are required. For example, the topichead element requires the navtitle attribute. Because the attribute is required, any topichead that uses conref must also provide a navtitle attribute – even if it is empty. Standard DITA processing rules would cause this value to override the navtitle on the target, even though the target navtitle is probably desired.

This example shows a map where the topichead element uses conref. It specifies the required navtitle attribute, as well as the toc attribute. In the resolved element, navtitle is not preserved, because it uses -dita-use-conref-target; the toc attribute is preserved using normal rules.

Pre-resolution:
<map><title>Conref demonstration</title>
  <topichead id="heading"
             navtitle="This is a heading"
             toc="yes"
             print="yes">
    <topicref href="topic.dita" navtitle="content"/>
  </topichead>
  <topichead conref="#heading"
             navtitle="-dita-use-conref-target"
             toc="no">
  </topichead>
</map>

Post-resolution:
<map><title>Conref demonstration</title>
  <topichead id="heading"
             navtitle="This is a heading"
             toc="yes"
             print="yes">
    <topicref href="topic.dita" navtitle="content"/>
  </topichead>
  <topichead navtitle="This is a heading"
             toc="no"
             print="yes">
    <topicref href="topic.dita" navtitle="content"/>
  </topichead>
</map>

More information on this and other conref rules can be found in the DITA Architectural specification.