<?xml version="1.0" encoding="UTF-8"?>
<!-- This file is part of the DITA Open Toolkit project hosted on 
 Sourceforge.net. See the accompanying license.txt file for 
 applicable licenses.-->
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
 "reference.dtd">
<reference id="processing-order" xml:lang="en-us">
<title>Processing order within the DITA-OT</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, the toolkit has over time found that the current
order best meets user expectations. Switching the order of processing,
while legal, may give different results. </shortdesc>
<refbody>
<section><p>For example, if conref is evaluated before filtering,
it is possible to reuse content that will later be filtered out of
its original location. However, we have found that filtering first
provides several benefits. For example, the following &lt;note> element
uses conref, but also contains a product attribute:</p><codeblock>&lt;note conref="documentA.dita#doc/note" product="MyProd"/></codeblock><p>If
the conref 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>However,
if the filtering is done first as in the toolkit, this element is
discarded immediately, and documentA is never examined. This provides
several important benefits:</p><ul>
<li>Time is saved simply by discarding unused content as early as
possible; all future steps can load the document without this extra
content.</li>
<li>More significant time is saved in this case by not evaluating
the conref 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></section>
<section><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,
on the sample above, the product attribute will override a product
setting on the referenced note. Now assume that the note in documentA
is defined as follows:<codeblock>&lt;note id="note" product="SomeOtherProduct">This is an important note!&lt;/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
-- resulting 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 desirable,
benefits such as those described above resulted in the current processing
order.</p></section>
</refbody>
</reference>
