Using the -dita-use-conref-target value

Darwin Information Typing Architecture (DITA) Version 1.3 Part 3: All-Inclusive Edition

Document
Darwin Information Typing Architecture (DITA) Version 1.3 Part 3: All-Inclusive Edition
Version
1.3
Author
OASIS DITA Technical Committee

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.

Note: In earlier versions of DITA, 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.
Figure. Pre-resolution
<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>
Figure. Effective result post-resolution
<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>