56 lines
No EOL
9.5 KiB
HTML
56 lines
No EOL
9.5 KiB
HTML
<!DOCTYPE html
|
|
SYSTEM "about:legacy-compat">
|
|
<html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta charset="UTF-8"><meta name="copyright" content="(C) Copyright 2020"><meta name="generator" content="DITA-OT"><meta name="description" content="The conref step resolves content references, processing only the DITA maps or topics that use the conref attribute. This step is implemented in XSLT."><meta name="keywords" content=", fig, xref, section, , conref, resolving, id, resolution, preprocessing, XSLT, step"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Resolve content references (conref)</title></head><body id="preprocess-conref"><header role="banner"><div class="header">
|
|
<p>DITA Open Toolkit</p>
|
|
<hr>
|
|
</div></header><nav role="toc"><ul><li><a href="../index.html">DITA Open Toolkit 3.6</a></li><li><a href="../release-notes/index.html">Release Notes</a></li><li><a href="../topics/installing-client.html">Installing DITA-OT</a></li><li><a href="../topics/building-output.html">Building output</a></li><li><a href="../topics/input-formats.html">Authoring formats</a></li><li><a href="../topics/output-formats.html">Output formats</a></li><li><a href="../parameters/index.html">Parameters</a></li><li><a href="../topics/html-customization.html">Customizing HTML</a></li><li><a href="../topics/pdf-customization.html">Customizing PDF</a></li><li><a href="../topics/adding-plugins.html">Adding plug-ins</a></li><li><a href="../topics/custom-plugins.html">Creating plug-ins</a></li><li><a href="../topics/troubleshooting-overview.html">Troubleshooting</a></li><li><a href="../reference/index.html">Reference</a><ul><li><a href="../reference/architecture.html">DITA-OT architecture</a><ul><li><a href="../reference/processing-structure.html">Processing structure</a></li><li><a href="../reference/map-first-preprocessing.html">Map-first preprocessing</a></li><li><a href="../reference/processing-pipeline-modules.html">Processing modules</a></li><li><a href="../reference/processing-order.html">Processing order</a></li><li><a href="../reference/store-api.html">Store API</a></li><li><a href="../reference/preprocessing.html">Pre-processing modules</a><ul><li><a href="../reference/preprocess-genlist.html">Generate lists (gen-list)</a></li><li><a href="../reference/preprocess-debugfilter.html">Debug and filter (debug-filter)</a></li><li><a href="../reference/preprocess-mapref.html">Resolve map references (mapref)</a></li><li><a href="../reference/preprocess-branch-filter.html">Branch filtering (branch-filter)</a></li><li><a href="../reference/preprocess-keyref.html">Resolve key references (keyref)</a></li><li><a href="../reference/preprocess-copy-to.html">Copy topics (copy-to)</a></li><li><a href="../reference/preprocess-conrefpush.html">Conref push (conrefpush)</a></li><li class="active"><a href="../reference/preprocess-conref.html">Resolve content references (conref)</a></li><li><a href="../reference/preprocess-profile.html">Filter conditional content (profile)</a></li><li><a href="../reference/preprocess-topic-fragment.html">Resolve topic fragments and code references (topic-fragment)</a></li><li><a href="../reference/preprocess-chunk.html">Chunk topics (chunk)</a></li><li><a href="../reference/preprocess-metadata.html">Move metadata (move-meta-entries) and pull content into maps (mappull) </a></li><li><a href="../reference/preprocess-maplink.html">Map based linking (maplink)</a></li><li><a href="../reference/preprocess-topicpull.html">Pull content into topics (topicpull)</a></li><li><a href="../reference/preprocess-flagging.html">Flagging (flag-module)</a></li><li><a href="../reference/preprocess-clean-map.html">Map cleanup (clean-map)</a></li><li><a href="../reference/preprocess-copyfiles.html">Copy related files (copy-files)</a></li></ul></li><li><a href="../reference/html-based-processing.html">HTML-based processing modules</a></li><li><a href="../reference/pdf-transform.html">PDF processing modules</a></li></ul></li><li><a href="../reference/dita-spec-support.html">DITA specification support</a></li><li><a href="../extension-points/plugin-extension-points.html">Extension points</a></li><li><a href="../reference/license.html">License</a></li><li><a href="../reference/glossary.html#glossary">Glossary</a></li></ul></li><li><a href="../topics/dita-and-dita-ot-resources.html">Resources</a></li></ul></nav><main role="main"><article role="article" aria-labelledby="ariaid-title1">
|
|
<h1 class="title topictitle1" id="ariaid-title1">Resolve content references (conref)</h1>
|
|
|
|
|
|
<div class="body conbody"><p class="shortdesc">The <code class="ph codeph">conref</code> step resolves content references, processing only the DITA maps or topics that
|
|
use the <code class="keyword markupname xmlatt">@conref</code> attribute. This step is implemented in XSLT.</p>
|
|
<section class="section">
|
|
<p class="p">The values of the <code class="keyword markupname xmlatt">@id</code> attribute on referenced content are changed as the elements are pulled
|
|
into the new locations. This ensures that the values of the <code class="keyword markupname xmlatt">@id</code> attribute within the referencing
|
|
topic remain unique.</p>
|
|
<div class="p">If an element is pulled into a new context along with a cross reference that references the target, both the
|
|
values of the <code class="keyword markupname xmlatt">@id</code> and <code class="keyword markupname xmlatt">@xref</code> attributes are updated so that they remain valid in
|
|
the new location. For example, a referenced topic might include a section as in the following example: <figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 1. </span>Referenced topic that contains a section and cross reference</figcaption>
|
|
|
|
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code><topic id="referenced_topic">
|
|
<title>...</title>
|
|
<body>
|
|
<section id="sect">
|
|
<title>Sample section</title>
|
|
<p>Figure <xref href="#referenced_topic/fig"/>
|
|
contains a code sample that demonstrates ... .</p>
|
|
<fig id="fig">
|
|
<title>Code sample</title>
|
|
<codeblock>....</codeblock>
|
|
</fig>
|
|
</section>
|
|
</body>
|
|
</topic></code></pre>
|
|
</figure></div>
|
|
<div class="p">When the section is referenced using a <code class="keyword markupname xmlatt">@conref</code> attribute, the value of the <code class="keyword markupname xmlatt">@id</code>
|
|
attribute on the <code class="keyword markupname xmlelement"><fig></code> element is modified to ensure that it remains unique in the new
|
|
context. At the same time, the <code class="keyword markupname xmlelement"><xref></code> element is also modified so that it remains valid
|
|
as a local reference. For example, if the referencing topic has an <code class="keyword markupname xmlatt">@id</code> set to "new_topic", then
|
|
the conrefed element may look like this in the intermediate document <code class="keyword markupname xmlelement"><section></code>. <figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 2. </span>Resolved conrefed <code class="keyword markupname xmlelement"><section></code> element after the conref step</figcaption>
|
|
|
|
<pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code><section id="sect">
|
|
<title>Sample section</title>
|
|
<p>Figure <xref href="#new_topic/d1e25"/> contains a code sample
|
|
that demonstrates ... .</p>
|
|
<fig id="d1e25">
|
|
<title>Code sample</title>
|
|
<codeblock>....</codeblock>
|
|
</fig>
|
|
</section></code></pre>
|
|
</figure></div>
|
|
<p class="p">In this case, the value of the <code class="keyword markupname xmlatt">@id</code> attribute on the <code class="keyword markupname xmlelement"><fig></code> element has
|
|
been changed to a generated value of "d1e25". At the same time, the <code class="keyword markupname xmlelement"><xref></code> element has
|
|
been updated to use that new generated ID, so that the cross reference remains valid.</p>
|
|
</section>
|
|
</div>
|
|
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../reference/preprocessing.html" title="The pre-processing operation is a set of steps that typically runs at the beginning of every DITA-OT transformation. Each step or stage corresponds to an Ant target in the build pipeline; the preprocess target calls the entire set of steps.">Pre-processing modules</a></div><div class="previouslink"><strong>Previous topic:</strong> <a class="link" href="../reference/preprocess-conrefpush.html" title="The conrefpush step resolves "conref push" references. This step only processes documents that use conref push or that are updated due to the push action. This step is implemented in Java.">Conref push (conrefpush)</a></div><div class="nextlink"><strong>Next topic:</strong> <a class="link" href="../reference/preprocess-profile.html" title="The profile step removes content from topics and maps based on the rules in DITAVAL files or the print attribute setting. Output can differ based on when filtering is done.">Filter conditional content (profile)</a></div></div></nav></article></main></body></html> |