Content reference (conref)

The DITA conref attributes are mechanisms that enable effective content reuse. DITA content references support complex reuse scenarios that are otherwise challenging or impossible to achieve. In addition, DITA content references have rules to ensure that the content is valid DITA after the content reference has been resolved.

Content referencing overview

The DITA @conref, @conkeyref, @conrefend, and @conaction attributes provide mechanisms for reusing content within DITA topics or maps. These mechanisms can be used both to pull and push content.

This topic uses the definitions of referenced element and referencing element as defined in Linking and addressing terminology.

Pulling content into the referencing element

When the @conref or @conkeyref attribute is used alone, the referencing element acts as a placeholder for the referenced element. The content of the referenced element is rendered in place of the referencing element.

The combination of the @conrefend attribute with either @conref or @conkeyref specifies a range of elements that is rendered in place of the referencing element. The start and end elements in a range must be siblings. Although the start and end elements must be of the same type as the referencing element (or specialized from that element type), the elements inside the range can be any type.

Pushing content from the referencing element

The @conaction attribute reverses the direction of reuse from pull to push. With a push, the referencing element is rendered before, after, or in place of the referenced element. The location (before, after, or in place of) is determined by the value of the @conaction attribute. The @conaction and @conrefend attributes cannot both be used within the same referencing element, so it is not possible to push a range of elements.

A fragment of DITA content, such as an XML document that contains only a single paragraph without a topic ancestor, does not contain enough information for a conref processor to be able to determine the validity of a reference to it. Consequently, the value of a @conref attribute must be one of the following items:

A referenced element within a DITA map
A referenced element within a DITA topic
An entire DITA map
An entire DITA topic

Direct URI-based content reuse

The @conref attribute is used to reference reusable content by URI. It allows reuse of DITA elements, including topic- or map-based elements.

The value of the @conref attribute is a URI reference to a DITA element. See URI-based (direct) addressing for details on specifying URI references to DITA elements. As with other DITA references, a @conref attribute that references a resource without an ID is treated as a reference to the first topic or map in the document.

Note (non-normative):

When using the @conref attribute on an element, the content of that element is ignored by processors. For example, if a phrase is marked up like this:

<ph conref="#topic/ph">Something</ph>

the word "Something" will be replaced by the content of the referenced <ph> element.

Indirect key-based content reuse

The @conkeyref attribute provides an indirect content reference to topic elements, map elements, or elements within maps or topics. It allows the referencing element to use a key in place of a URI reference when referencing another topic or map.

When the target of a content reference is a topic or map, the value of the @conkeyref attribute is a key name that directly resolves to that topic or map.

When the target of a content reference is an element within a topic or map, the value of the @conkeyref attribute is a key name, followed by a slash ("/"), followed by the ID of the referenced element. The key name must be bound to the topic or map that contains the referenced element.

When the key name specified by the @conkeyref attribute is not defined and the element also specifies a @conref attribute, the @conref attribute is used to determine the referenced element. If no @conref attribute is specified there is no content reference relationship.

The @conrefend attribute, which defines the end of a conref range, cannot include a key. Instead the map or topic element addressed by the key name component of the @conkeyref is used in place of whatever map or topic element is addressed by the @conrefend attribute. See Using conrefend together with conkeyref for more information and for examples of this behavior.

Reusing a range of elements

The @conrefend attribute is used in a conref range. A @conref or @conkeyref attribute references the first element in the range, while @conrefend references the last element in the range.

Using `@conref` together with `@conrefend`

The following markup rules apply when using or implementing @conrefend:

The start and end elements of a range MUST be of the same type as the referencing element or generalizable to the referencing element.
The start and end elements in a range MUST share the same parent, and the start element MUST precede the end element in document order.
The parent of the referencing element MUST be the same type as the parent of the referenced range or generalizable to the parent of the referencing element.

In addition, several other items must be taken into account:

Processors will resolve the range by pulling in the starting referenced element and following sibling XML nodes up to and including the ending referenced element.
As with @conref, if the @conrefend attribute references a more specialized version of the referencing element, applications can generalize the target when resolving.
As with @conref, it is not valid to use @conrefend to reference a more general version of an element (such as using <step> to reference an <li> element).
Other nodes (such as elements or text) between the start and end of a range do not have to match the referencing element.
With single conref, an @id attribute from the referenced element will not be preserved on the resolved content. With a range, an @id on both the start and the end elements will not be preserved. @id attributes on intermediate or child nodes should be preserved; if this results in duplicate @id values, an application can recover by changing the @id, warning the user, or implementing another strategy.
With a single conref, attributes specified on the referencing element can be used to override attributes on the referenced element. With a conref range, the same is true, with the following clarifications:
- When an @id attribute is specified on the referencing element, it will only be preserved on the first element of the resolved range.
- When other attributes are specified, they will only apply to referenced elements of the same type. For example, if <step> is used to pull in a range of sequential <step> elements, locally specified attributes apply to all steps in the range. If <ol> is used to pull in a series of (<ol>, <p>, <ol>), locally specified attributes apply only to the <ol> elements in that range.

Using `@conrefend` together with `@conkeyref`

When the @conkeyref attribute is used in place of @conref, a key is used to address the target of the reference. The @conrefend attribute, which indicates the end of a @conref range, cannot use a key. Instead the map or topic element addressed by the key name component of the @conkeyref is used in place of whatever map or topic element is addressed by the @conrefend attribute.

For example, if the value of the @conkeyref attribute is config/step1 and the value of the @conrefend is defaultconfig.dita#config/laststep, the conref range will end with the step that has id="laststep" in whatever topic is addressed by the key name config. If the key name config is not defined, and the @conref attribute itself is not present for fallback, the @conrefend attribute is ignored.

Pushing reusable content to a new location

The @conaction attribute allows users to push content from one location into another. It causes the @conref attribute to work in reverse, so that content is pushed from the referencing element into another location, rather than pulled from another location to replace the referencing element.

Note (non-normative):

In the descriptions below, the word target always refers to the element referenced by a @conref or @conkeyref attribute.

There are three possible functions using the @conaction attribute: replacing an element, pushing content before an element, or pushing content after an element. The @conaction attribute always declares the desired function while the @conref or @conkeyref attribute provides the target of the reference using standard syntax for that attribute.

In each case, an element pushed using @conref or @conkeyrefmust be of the same type as, or more specialized than, its target. If the pushed element is more specialized than the target, then it should be generalized when the @conref or @conkeyref is resolved. This ensures that the content will be valid in the target topic.

It is valid to push using @conref or @conkeyref when the two elements involved are of the same type. For example, a <step> element can use the conref push feature with another <step> as the target of the @conref or @conkeyref.
The target element can be more general than the source. For example, it is legal to push a <step> element to replace a general list item (<li>); the <step> element should be generalized back to a list item during the process.
It is not possible to push a more general element into a specialized context. For example, it is not legal to push a list item (<li>) in order to replace a <step>, because the list item allows many items that are not valid in the specialized context.

Replacing content in another topic

When the @conaction attribute is set to pushreplace, the referencing element will replace the referenced element specified by the @conref or @conkeyref attribute. The pushed content remains in the source topic where it was originally authored.

When resolving a conref push action, attributes are resolved using the same precedence as for normal @conref, with one exception. Attributes on the element with the @conref or @conkeyref attribute (in this case, the source doing the push) will take priority over those on the referenced element. The exception is that if the source element does not specify an ID, the ID on the referenced element remains; if the source element does specify an ID then that replaces the ID on the referenced element.

It is an error for two source topics to replace the same element. Applications MAY warn users if more than one element attempts to replace a single target.

Pushing content before or after another element

Setting the @conaction attribute to pushbefore allows an element to be pushed before the element referenced by the @conref or @conkeyref attribute. Likewise, setting the @conaction attribute to pushafter allows an element to be pushed after the element referenced by the @conref or @conkeyref attribute. Multiple sources can push content before or after the same referenced element; the order in which that content is pushed is undefined.

When an element is pushed before or after a referenced element, the resulting document will have at least two of that element. Because this is not always valid, a document attempting to push content before or after a target must take an extra step to ensure that the result will be valid. The extra step makes use of the conaction="mark" value. For example, this restriction prevents a topic from trying to push a <body> element before or after another <body> element, because it is not valid to have two body elements in sequence.

When pushing before, the @conref or @conkeyref attribute itself looks just as it did when replacing, but the @conaction attribute is set to mark because it is marking the referenced element. This element remains empty; its purpose is to ensure that it is legal to have more than one of the current element. The element immediately before the marking element is the content that will actually be pushed. This element will set the @conaction attribute to pushbefore.

When pushing after, the procedure is the same, except that the order of the elements is reversed. The element with conaction="pushafter" comes immediately after the element which marks the target.

Attributes on the element which is pushed (the one with conaction="pushbefore" or conaction="pushafter") must be retained on the target, apart from the @conaction attribute itself. If this causes the result document to end up with duplicate IDs, an application can recover by changing the @id, warning the user, or implementing another strategy.

The following restrictions apply when pushing content before or after an element:

The elements that use conaction="mark" and conaction="pushbefore" are the same type as each other and appear in sequence.
Either the container elements of the source and target match, or the container of the source element is a specialization of the target's container. This is also to ensure validity of the target; for example, while it is possible to include multiple titles in a <section>, it is not possible to do so in a figure. Comparing the parents prevents a second <section> title from being pushed before a figure title. This restriction only applies to the pushbefore or pushafter actions, not to the pushreplace action.

When content is pushed from one topic to another, it is still rendered in the original context. Processors might choose not to render the empty element that has the conaction="mark" attribute. In order to push content from a topic without actually rendering that topic on its own, the topic should be referenced from the map with the @processing-role attribute set to "resource-only".

Combining `@conaction` with `@conkeyref` or `@conrefend`

The @conkeyref attribute can be used as an indirect way to specify a @conref target. If the @conkeyref attribute is specified on an element that also uses the @conaction attribute, the @conkeyref attribute is used to determine the target of the conref push (as it would normally be used to determine the target of @conref).

The conref push function does not provide the ability to push a range of elements, so it is an error to specify the @conrefend attribute together with the @conaction attribute. If the two are specified together an application can recover by warning the user, ignoring the @conrefend attribute, or with some other implementation strategy.

Processing conrefs

When processing content references, DITA processors compare the restrictions of each context to ensure that the conrefed content is valid in its new context.

Note (non-normative):

The DITA @conref attribute is a transclusion mechanism similar to XML XInclude. DITA differs from these mechanisms, however, in that conref validity does not apply simply to the current content at the time of replacement, but to the possible resolved content given the restrictions of both the referencing document type and the referenced document type.

When content is reused between two documents with different domains or constraints, it is possible for the reused content to include domain extensions that are not defined for the new context, or to include elements that would be constrained out of the new context. When pulling or pushing content with the conref mechanism, processors resolving conrefs can can optionally generalize specializations as needed for the resolving context.

A conref processor SHOULD NOT permit resolution of a reuse relationship that could be rendered invalid under the rules of either the reused or reusing content.

When resolving @conkeyref attributes, processors SHOULD issue a warning when a @conkeyref reference cannot be resolved and there is no @conref attribute to use as a fallback. Processors MAY issue a warning when a @conkeyref cannot be resolved to an element and a specified @conref is used as a fallback.

Common error conditions related to conref ranges

When encountering the following error conditions, an implementation can optionally issue an error message.


Condition or Issue	Result
The `@conref` attribute cannot be resolved in the target document (the target element might have been removed or its id has changed).	The `@conref` is ignored.
The `@conrefend` attribute cannot be resolved in the target document (the target element might have been removed or its id has changed).	Range cannot be resolved, optional recovery processes the result as a simple conref.
Start and end elements are not siblings in the target document.	If the start element exists, optional recovery processes the result as a simple conref.
End element occurs before the start element in the target document.	If the start element exists, optional recovery processes the result as a simple conref.
An element has a `@conrefend` attribute but is missing the `@conref` attribute.	The `@conrefend` attribute is ignored.

Processing attributes when resolving conrefs

When resolving conrefs, processors need to combine the attributes that are specified on the referencing and referenced element.

The attribute specifications on the resolved element are drawn from both the referencing element and the referenced element, according to the following priority:

All attributes as specified on the referencing element, except for attributes set to "-dita-use-conref-target".
All attributes as specified on the referenced element except the @id attribute.
The @xml:lang attribute has special treatment as described in The xml:lang attribute.

The token -dita-use-conref-target is defined by the specification to enable easier use of @conref on elements with required attributes. The only time the resolved element would include an attribute whose specified value is "-dita-use-conref-target" is when the referenced element had that attribute specified with the "-dita-use-conref-target" value and the referencing element either had no specification for that attribute or had it also specified with the "-dita-use-conref-target" value.

If the final resolved element (after the complete resolution of any conref chain) has an attribute with the "-dita-use-conref-target" value, that element MUST be treated as equivalent to having that attribute unspecified.

A given attribute value on the resolved element comes in its entirety from either the referencing element or the referenced element. The attribute values of the referencing and referenced elements for a given attribute are never additive, even if the property (such as @audience) takes a list of values.

If the referenced element has a content referencing attribute specified, the above rules MUST be applied recursively with the resolved element from one referencing/referenced combination becoming one of the two elements participating in the next referencing/referenced combination. The result should preserve without generalization all elements that are valid in the originating context, even if they are not valid in an intermediate context.

For example, if topic A and topic C allow highlighting, and topic B does not, then a content reference chain of topic A-to-topic B-to-topic C should preserve any highlighting elements in the referenced content. The result, however it is achieved, is equivalent to the result of resolving the conref pairs recursively starting from the original referencing element in topic A.

Using the -dita-use-conref-target value

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.

Processing xrefs and conrefs within a conref

When referenced content contains a content reference or cross reference, the effective target of the reference depends on the form of address that is used in the referenced content. It also might depend on the map context, especially when key scopes are present.

Direct URI reference (but not a same-topic fragment identifier ): When the address is a direct URI reference of any form other than a same-topic fragment identifier, processors MUST resolve it relative to the source document that contains the original URI reference.
Same-topic fragment identifier: When the address is a same-topic fragment identifier, processors MUST resolve it relative to the location of the content reference (referencing context).
Key reference: When the address is a key reference, processors MUST resolve it relative to the location of the content reference (referencing context).

When resolving key references or same-topic fragment identifiers, the phrase location of the content reference means the final resolved context. For example, in a case where content references are chained (topic A pulls from topic B, which in turn pulls a reference from topic C), the reference is resolved relative to the topic that is rendered. When topic B is rendered, the reference is resolved relative to the content reference in topic B; when topic A is rendered, the reference is resolved relative to topic A. If content is pushed from topic A to topic B to topic C, then the same-topic fragment identifier is resolved in the context of topic C.

The implication is that a content reference or cross reference can resolve to different targets in different use contexts. This is because a URI reference that contains a same-topic fragment identifier is resolved in the context of the topic that contains the content reference, and a key reference is resolved in the context of the key scope that is in effect for each use of the topic that contains the content reference.

Note (non-normative):

In the case of same-topic fragment identifiers, the author of the content reference needs to ensure that any element IDs that are specified in same-topic fragment identifiers in the referenced content will also be available in the referencing topic at resolution time.

Examples of content referencing

This section is non-normative.

This section contains examples and scenarios that illustrate the use and processing of @conref, @conkeyref, and related content-referencing attributes.

Example: Simple `@conref` usage

This section is non-normative.

In this scenario, a @conref attribute is used to pull content from the referenced element in another topic.

Consider the following topic:

<task id="setup-widget" xml:lang="en">
  <title>Setting up the widget</title>
  <taskbody>
    <steps>
      <step><cmd>Turn the widget on for the first time.</cmd></step>
      <step><cmd>Follow the prompts to select your language and region.</cmd></step>
      <step conref="reuse-library.dita#reuse/setup-profile"><cmd></cmd></step>
      <step><cmd>Step outside and activate the widget.</cmd></step>
    </steps>
  </taskbody>
</task>

That topic requires the existence of another topic, reuse-library.dita:

<task id="reuse-library" xml:lang="en">
  <title>Reuse library topic</title>
  <taskbody>
    <steps>
      <!-- ... other steps used across tasks ... -->
      <step id="setup-profile">
        <cmd>Follow the prompts to set up your name and contact information.</cmd>
        <info>Contact information is optional, but recommended.</info>
      </step>
    </steps>
  </taskbody>
</task>

These topics highlight some important things to remember when using @conref attributes:

The attribute includes both the ID of the referenced topic and the ID of the referenced element.
When an element with a @conref attribute has required child elements, those child elements must still be specified. The use of DITA's @conref attribute does not override the XML rules that require such child elements.

When the @conref attribute is resolved, the processed version of the original topic will include content from the referenced element:

<task id="setup-widget" xml:lang="en">
  <title>Setting up the widget</title>
  <taskbody>
    <steps>
      <step><cmd>Turn the widget on for the first time.</cmd></step>
      <step><cmd>Follow the prompts to select your language and region.</cmd></step>
      <step>
        <cmd>Follow the prompts to set up your name and contact information.</cmd>
        <info>Contact information is optional, but recommended.</info>
      </step>
      <step><cmd>Step outside and activate the widget.</cmd></step>
    </steps>
  </taskbody>
</task>

Example: Simple `@conkeyref` usage

This section is non-normative.

In this scenario, a @conkeyref attribute is used as an indirect reference to pull content from the referenced element in another topic.

Consider the following topic:

<task id="setup-widget" xml:lang="en">
  <title>Setting up the widget</title>
  <taskbody>
    <steps>
      <step><cmd>Turn the widget on for the first time.</cmd></step>
      <step><cmd>Follow the prompts to select your language and region.</cmd></step>
      <step conkeyref="reuselibrary/setup-profile"><cmd></cmd></step>
      <step><cmd>Step outside and activate the widget.</cmd></step>
    </steps>
  </taskbody>
</task>

The key is defined as a reference to a resue library:

<map>
  <title>Key definitions</title>
  <keydef keys="reuselibrary" href="reuse-library.dita"/>
  <!-- ... -->
</map>

The library topic reuse-library.dita is set up as follows:

<task id="reuse-library" xml:lang="en">
  <title>Reuse library topic</title>
  <taskbody>
    <steps>
      <!-- ... other steps used across tasks ... -->
      <step id="setup-profile">
        <cmd>Follow the prompts to set up your name and contact information.</cmd>
        <info>Contact information is optional, but recommended.</info>
      </step>
    </steps>
  </taskbody>
</task>

When the @conkeyref attribute is resolved, the key resolves to the topic that contains the referenced ID setup-profile. The result is the same as if the original topic contained conref="reuse-library.dita#reuse-library/setup-profile" instead of conkeyref="reuselibrary/setup-profile". However, the indirection created by using a key allows this reference to resolve differently in other contexts.

The processed version of the original topic will include content from the referenced element:

<task id="setup-widget" xml:lang="en">
  <title>Setting up the widget</title>
  <taskbody>
    <steps>
      <step><cmd>Turn the widget on for the first time.</cmd></step>
      <step><cmd>Follow the prompts to select your language and region.</cmd></step>
      <step>
        <cmd>Follow the prompts to set up your name and contact information.</cmd>
        <info>Contact information is optional, but recommended.</info>
      </step>
      <step><cmd>Step outside and activate the widget.</cmd></step>
    </steps>
  </taskbody>
</task>

Example: Reusing a sequence of list items

This section is non-normative.

In this scenario, a @conref and @conrefend are used to reference a range of list items.

In the following code sample, we have a library topic that defines a series of list items. Each list item has an @id attribute, making it possible to reuse them individually or as ranges.

Figure 1. Source document topic.dita

<topic id="x">
  <title>Sample file topic.dita</title>
  <body>
    <ol id="list">
      <li id="apple">A</li>
      <li id="bear">B</li>
      <li id="cat">C</li>
      <li id="dog">D</li>
      <li id="eel">E</li>
    </ol>
  </body>
</topic>

The following topic reuses a range of items from that list, without reusing the entire list.

Figure 2. Reusing a range of items

<topic id="y">
  <title>Sample file reusing content</title>
  <body>
    <ol>
      <li>My own first item</li>
      <li conref="topic.dita#x/bear" conrefend="topic.dita#x/dog"/>
      <li>And a different final item</li>
    </ol>
  </body>
</topic>

In the resolved topic, all list items from the starting "bear" to the ending "dog" are pulled in to replace the referencing element. The @id attributes on the referenced elements are not preserved, but any @id attributes on intermediate elements are preserved.

Figure 3. Processed result of reusing topic

<topic id="y">
  <title>Sample file reusing content</title>
  <body>
    <ol>
      <li>My own first item</li>
      <li>B</li>
      <li id="cat">C</li>
      <li>D</li>
      <li>And a different final item</li>
    </ol>
  </body>
</topic>

Example: Reusing a sequence of elements of different types

This section is non-normative.

In this scenario, a @conref and @conrefend are used to reference a range of block elements that do not have the same element type.

In the following code sample, we have a library topic that defines several elements, including paragraphs and lists. Each block element has an @id attribute, making it possible to reuse them individually or as ranges.

Figure 4. Source topic.dita with ids

<topic id="x">
  <title>Library file topic.dita</title>
  <body>
    <p id="p1">First para</p>
    <ol id="mylist">
      <li id="apple">A</li>
      <li id="bear">B</li>
      <li id="cat">C</li>
      <li id="dog">D</li>
      <li id="eel">E</li>
    </ol>
    <p id="p2">Second para</p>
  </body>
</topic>

In the following sample, the referencing element is a paragraph. It references a starting paragraph and an ending paragraph, which defines a range that includes those paragraphs along with everything that falls between them.

Figure 5. Referencing the starting and ending paragraphs

<topic id="y">
  <title>Sample file reusing content</title>
  <body>
    <p conref="topic.dita#x/p1" conrefend="topic.dita#x/p2"/>
  </body>
</topic>

In the resolved topic, all list items from the starting paragraph to the ending paragraph are pulled in to replace the referencing element. The @id attributes on the referenced elements are not preserved, but any @id attributes on intermediate elements are preserved.

Figure 6. Block level example: Processed result of reusing topic

<topic id="y">
  <title>Sample file reusing content</title>
  <body>
    <p>First para</p>
    <ol id="mylist">
      <li id="apple">A</li>
      <li id="bear">B</li>
      <li id="cat">C</li>
      <li id="dog">D</li>
      <li id="eel">E</li>
    </ol>
    <p>Second para</p>
  </body>
</topic>

Example: Reusing a range with `@conkeyref`

This section is non-normative.

In this scenario, a @conkeyref is used to define the start of a range and @conrefend is used to define the end of a range.

In the following sample, the key xmp is defined as the first topic in the file examples.dita.

Figure 7. Defining and referencing a key with @conkeyref

<map>
  <!-- ... -->
  <keydef keys="xmp" href="examples.dita"/>
  <!-- ... -->
</map>

<!-- examples.dita: -->
<topic id="examples">
  <title>These are examples</title>
  <body>
    <ul>
      <li id="first">A first example</li>
      <li>Another trivial example</li>
      <li id="last">Final example</li>
    </ul>
  </body>
</topic>

To reuse these list items by using the key, the @conkeyref attribute combines the key itself with the sub-topic id first to define the start of the range. The @conrefend attribute defines a default high-level object along with the sub-topic id last that ends the range:

  <li conkeyref="xmp/first" 
      conrefend="default.dita#default/last"/>

The @conkeyref attribute uses a key to reference the first topic in examples.dita, so the range begins with the object examples.dita#examples/first. The high-level object in the @conrefend attribute (default.dita#default) is replaced with the object represented by the key (the first topic in examples.dita), resulting in a range that ends with the object examples.dita#examples/last.

Figure 8. Combining @conref, @conkeyref, and @conrefend

When @conref, @conkeyref, and @conrefend are all specified, the key value takes priority.

  <li conkeyref="thisconfig/start"
      conref="standardconfig.dita#config/start"
      conrefend="standardconfig.dita#config/end"/>

If the key thisconfig is defined as mySpecialConfig.dita#myconfig, then the range will go from the list item with id="start" to the list item withid="end" in the topic mySpecialConfig.dita#myconfig.
If the key thisconfig is defined as myConfig.dita, then the range will go from the list item with id="start" to the list item with id="end" within the first topic in myConfig.dita.
If the key thisconfig is not defined, then the unchanged @conref and @conrefend attributes are used as fallback. In that case, the range will go from the list item with id="start" to the list item with id="end" within the topic standardconfig.dita#config.

Example: Using `@conaction` to replace content

This section is non-normative.

In this scenario, a @conref and @conaction are used to replace content in another topic.

Consider the following task in example.dita that has the @id attribute set to example. The task contains a <step> element with the @id set to b:

<task id="example" xml:lang="en">
  <title>Example topic</title>
  <taskbody>
    <steps>
      <step id="a"><cmd>A</cmd></step>
      <step id="b"><cmd>B</cmd></step>
      <step id="c"><cmd>C</cmd></step>
    </steps>
  </taskbody>
</task>

In order to replace the step with id="b", another topic must combine a @conaction value of pushreplace with a @conref attribute that references this <step>:

<!-- Steps element within another task -->
<steps>
  <step conaction="pushreplace" 
        conref="example.dita#example/b">
    <cmd>Updated B</cmd>
  </step>
</steps>
</task>

The result will be an updated version of example.dita which contains the pushed <step>:

<task id="example" xml:lang="en">
  <title>Example topic</title>
  <taskbody>
    <steps>
      <step id="a"><cmd>A</cmd></step>
      <step id="b"><cmd>Updated B</cmd></step>
      <step id="c"><cmd>C</cmd></step>
    </steps>
  </taskbody>
</task>

Example: Using `@conaction` to push content before another element

This section is non-normative.

In this scenario, a @conref and @conaction are used to push content before an element in another topic.

Consider the following topic, which is set up to push a step before a step in another topic. It needs to use two step elements to set up the reuse. The referencing element itself uses conaction="mark" to mark the referenced element. The element to be pushed immediately preceeds the marking element and uses conaction="pushbefore":

<steps>
  <step conaction="pushbefore">
    <cmd>Do this before B</cmd>
  </step>
  <step conaction="mark" conref="example.dita#example/b">
    <cmd/>
  </step>
</steps>

The referenced element is in the file example.dita, which looks like this before a processor resolves the reference:

<task id="example" xml:lang="en">
  <title>Example topic</title>
  <taskbody>
    <steps>
      <step id="a"><cmd>A</cmd></step>
      <step id="b"><cmd>B</cmd></step>
      <step id="c"><cmd>C</cmd></step>
    </steps>
  </taskbody>
</task>

After the content reference is resolved, the document example.dita includes the pushed <step> element before the step with @id set to b:

<task id="example" xml:lang="en">
  <title>Example topic</title>
  <taskbody>
    <steps>
      <step id="a"><cmd>A</cmd></step>
      <step><cmd>Do this before B</cmd></step>
      <step id="b"><cmd>B</cmd></step>
      <step id="c"><cmd>C</cmd></step>
    </steps>
  </taskbody>
</task>

Example: Using `@conaction` to push content after another element

This section is non-normative.

In this scenario, a @conref and @conaction are used to push content after an element in another topic.

Consider the following topic, which is set up to push a step after a step in another topic. It needs to use two step elements to set up the reuse. The referencing element itself uses conaction="mark" to mark the referenced element. The element to be pushed immediately follows the marking element and uses conaction="pushafter":

<steps>
  <step conaction="mark" conref="example.dita#example/b">
    <cmd/>
  </step>
  <step conaction="pushafter">
    <cmd>Do this after B</cmd>
  </step>
</steps>

The referenced element is in the file example.dita, which looks like this before a processor resolves the reference:

<task id="example" xml:lang="en">
  <title>Example topic</title>
  <taskbody>
    <steps>
      <step id="a"><cmd>A</cmd></step>
      <step id="b"><cmd>B</cmd></step>
      <step id="c"><cmd>C</cmd></step>
    </steps>
  </taskbody>
</task>

After the content reference is resolved, the document example.dita includes the pushed <step> element after the step with @id set to b:

<task id="example" xml:lang="en">
  <title>Example topic</title>
  <taskbody>
    <steps>
      <step id="a"><cmd>A</cmd></step>
      <step id="b"><cmd>B</cmd></step>
      <step><cmd>Do this after B</cmd></step>
      <step id="c"><cmd>C</cmd></step>
    </steps>
  </taskbody>
</task>

Example: Resolving conrefs to elements that contain cross references

This section is non-normative.

In this scenario, elements referenced by conref include cross references using a variety of referencing styles.

Consider the following paragraphs in paras-01.dita that are intended to be used by reference from other topics:

<topic id="paras-01">
    <title>Reusable paragraphs</title>
    <body>
        <p id="p1">See <xref href="#paras-01/p5"/>.</p>
        <p id="p2">See <xref href="topic-02.dita#topic02/fig-01"/>.</p>
        <p id="p3">See <xref href="#./p5"/>.</p>
        <p id="p4">See <xref keyref="task-remove-cover"/>.</p>
        <p id="p5">Paragraph 5 in paras-01.</p>
    </body>
</topic>

The paragraphs are used by content reference from other topics, including the using-topic-01.dita topic:

<topic id="using-topic-01"><title>Using topic one</title>
    <body>
        <p id="A" conref="paras-01.dita#paras-01/p1"/> 
        <p id="B" conref="paras-01.dita#paras-01/p2"/> 
        <p id="C" conref="paras-01.dita#paras-01/p3"/>
        <p id="D" conref="paras-01.dita#paras-01/p4"/>
        <p id="p5">Paragraph 5 in using-topic-01</p>  
    </body>
</topic>

Processors must consider different contexts when resolving <xref> references within the referenced paragraphs. The rendered cross references in using-topic-01.dita are shown in the following table.

Paragraph	Value of `@id` attribute on conrefed paragraph	`<xref>` within conrefed paragraph	Resolution
A	p1	`<xref href="#paras-01/p5"/>`	The cross reference in paragraph p1 is a direct URI reference that does not contain a same-topic fragment identifier. It can be resolved only to paragraph p5 in paras-01.dita, which contains the content "Paragraph 5 in paras-01".
B	p2	`<xref href="topic-02.dita#topic02/fig-01"/>`	The cross reference in paragraph p2 is a direct URI reference. It can be resolved only to the element with `id="fig-01"` in topic-02.dita.
C	p3	`<xref href="#./p5"/>`	The cross reference in paragraph p3 is a direct URI reference that contains a same-topic fragment identifier. Because the URI reference contains a same-topic fragment identifier, the reference is resolved in the context of the referencing topic (using-topic-01.dita). If using-topic-01.dita did not contain an element with `id="p5"`, then the conref to paragraph p3 would result in a link resolution failure.
D	p4	`<xref keyref="task-remove-cover"/>`	The cross reference in paragraph p4 is a key reference. It is resolved to whatever resource is bound to the key name "task-remove-cover" in the applicable map context.

Example: Resolving conrefs to elements that contain cross references, with key scopes

This section is non-normative.

In this scenario, elements referenced by conref include cross references using a variety of referencing styles. The topics themselves are used in a map that makes use of key scopes.

Consider the following paragraphs in paras-01.dita that are intended to be used by reference from other topics:

<topic id="paras-01">
    <title>Reusable paragraphs</title>
    <body>
        <p id="p1">See <xref href="#paras-01/p5"/>.</p>
        <p id="p2">See <xref href="topic-02.dita#topic02/fig-01"/>.</p>
        <p id="p3">See <xref href="#./p5"/>.</p>
        <p id="p4">See <xref keyref="task-remove-cover"/>.</p>
        <p id="p5">Paragraph 5 in paras-01.</p>
    </body>
</topic>

The paragraphs are used by content reference from other topics, including the using-topic-01.dita topic:

<topic id="using-topic-01"><title>Using topic one</title>
    <body>
        <p id="A" conref="paras-01.dita#paras-01/p1"/> 
        <p id="B" conref="paras-01.dita#paras-01/p2"/> 
        <p id="C" conref="paras-01.dita#paras-01/p3"/>
        <p id="D" conref="paras-01.dita#paras-01/p4"/>
        <p id="p5">Paragraph 5 in using-topic-01</p>  
    </body>
</topic>

Now consider the following map, which uses each of the topics above:

<map>
  <topicgroup keyscope="product-1">
    <topicref keys="task-remove-cover" href="prod-1-task-remove-cover.dita"/>
    <topicref href="using-topic-01.dita"/>
  </topicgroup>
  <topicgroup keyscope="product-2">
    <topicref keys="task-remove-cover" href="prod-2-task-remove-cover.dita"/>
    <topicref href="using-topic-01.dita"/>
  </topicgroup>
</map>

The map establishes two key scopes: "product-1" and "product-2". Within the map branches, the key name "task-remove-cover" is bound to a different topic. The topic using-topic-01.dita, which includes a conref to a paragraph that includes a cross reference to the key name "task-remove-cover", is also referenced in each branch. When each branch is rendered, the target of the cross reference is different.

In the first branch with the key scope set to "product-1", the cross reference from paragraph p4 is resolved to prod-1-task-remove-cover.dita. In the second branch with the key scope set to "product-2", the cross reference from paragraph p4 is resolved to prod-2-task-remove-cover.dita.

Example: Using the -dita-use-conref-target value

This section is non-normative.

In this scenario, an element in a map is reused, with some of the attributes resolved using the -dita-use-conref-target token.

Consider the following scenario, where a <topichead> element in a DITA map uses @conref. It specifies the @deliveryTarget attribute as well as the @toc attribute.

<map><title>Conref demonstration</title>
  <topichead id="heading"
             deliveryTarget="pdf"
             toc="yes"
             linking="normal">
    <topicmeta>
       <navtitle>This is a heading</navtitle>
    </topicmeta>
    <topicref href="topic.dita"/>
  </topichead>

  <topichead conref="#heading"
             deliveryTarget="-dita-use-conref-target"
             toc="no">
  </topichead>
</map>

When the content reference is resolved, the @deliveryTarget attribute from the referencing element is not preserved because it uses -dita-use-conref-target. Instead, it uses the value pdf from the referenced element. The @linking attribute, which is not specified on the referencing element, is also resolved based on the referenced element. The @toc attribute from the referencing element overrides the @toc attribute on the referenced element using normal conref resolution rules:

<map><title>Conref demonstration</title>
  <topichead id="heading"
             deliveryTarget="pdf"
             toc="yes"
             linking="normal">
    <topicmeta>
       <navtitle>This is a heading</navtitle>
    </topicmeta>
    <topicref href="topic.dita"/>
  </topichead>

  <topichead deliveryTarget="pdf"
             toc="no"
             linking="normal">
    <topicmeta>
       <navtitle>This is a heading</navtitle>
    </topicmeta>
    <topicref href="topic.dita"/>
  </topichead>
</map>

Content reference (conref)