Processing xrefs and conrefs within a conref
- 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
Example: Resolving conrefs to elements that contain cross references
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>
Following resolution of the content references and processing of the
<xref> elements in 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
( If |
| 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 key-based cross references
Consider the following map, which uses the topics from the previous example:
<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.