62 lines
3.9 KiB
XML
62 lines
3.9 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
|
|
<!-- This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license. -->
|
|
<concept id="processing-order">
|
|
<title>Processing order</title>
|
|
<shortdesc>The order of processing is often significant when evaluating DITA content. Although the DITA specification
|
|
does not mandate a specific order for processing, DITA-OT has determined that performing filtering before conref
|
|
resolution best meets user expectations. Switching the order of processing, while legal, may give different
|
|
results.</shortdesc>
|
|
<prolog>
|
|
<metadata>
|
|
<keywords>
|
|
<indexterm><xmlelement>note</xmlelement></indexterm>
|
|
<indexterm><xmlatt>product</xmlatt></indexterm>
|
|
<indexterm><xmlatt>conref</xmlatt>
|
|
<indexterm>resolving</indexterm></indexterm>
|
|
<indexterm>filters
|
|
<indexterm>processing order</indexterm></indexterm>
|
|
<indexterm>processing</indexterm>
|
|
<indexterm>pipelines
|
|
<indexterm>processing order</indexterm></indexterm>
|
|
</keywords>
|
|
</metadata>
|
|
</prolog>
|
|
<conbody>
|
|
<section>
|
|
<p>The DITA-OT project has found that filtering first provides several benefits. Consider the following sample
|
|
that contains a <xmlelement>note</xmlelement> element that both uses conref and contains a
|
|
<xmlatt>product</xmlatt>
|
|
attribute:<codeblock
|
|
outputclass="language-xml"
|
|
><note conref="documentA.dita#doc/note" product="MyProd"/></codeblock></p>
|
|
<p>If the <xmlatt>conref</xmlatt> attribute is evaluated first, then documentA must be parsed in order to retrieve
|
|
the note content. That content is then stored in the current document (or in a representation of that document
|
|
in memory). However, if all content with product="MyProd" is filtered out, then that work is all discarded later
|
|
in the build.</p>
|
|
<p>If the filtering is done first (as in DITA-OT), this element is discarded immediately, and documentA is never
|
|
examined. This provides several important benefits:
|
|
<ul>
|
|
<li>Time is saved by discarding unused content as early as possible; all future steps can load the document
|
|
without this extra content.</li>
|
|
<li>Additional time is saved case by not evaluating the <xmlatt>conref</xmlatt> attribute; in fact, documentA
|
|
does not even need to be parsed.</li>
|
|
<li>Any user reproducing this build does not need documentA. If the content is sent to a translation team,
|
|
that team can reproduce an error-free build without documentA; this means documentA can be kept back from
|
|
translation, preventing accidental translation and increased costs.</li>
|
|
</ul></p>
|
|
<p>If the order of these two steps is reversed, so that conref is evaluated first, it is possible that results
|
|
will differ. For example, in the code sample above, the <xmlatt>product</xmlatt> attribute on the reference
|
|
target will override the product setting on the referencing note. Assume that the referenced
|
|
<xmlelement>note</xmlelement> element in documentA is defined as follows:
|
|
<codeblock
|
|
outputclass="language-xml"
|
|
><note id="note" product="SomeOtherProduct">This is an important note!</note></codeblock></p>
|
|
<p>A process that filters out product="SomeOtherProduct" will remove the target of the original conref before that
|
|
conref is ever evaluated, which will result in a broken reference. Evaluating conref first would resolve the
|
|
reference, and only later filter out the target of the conref. While some use cases can be found where this is
|
|
the desired behavior, benefits such as those described above resulted in the current processing order used by
|
|
DITA-OT.</p>
|
|
</section>
|
|
</conbody>
|
|
</concept>
|