Processing order within the DITA-OT
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 <note> element uses conref, but also contains a product attribute:
<note conref="documentA.dita#doc/note" product="MyProd"/>
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.
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:
- Time is saved simply by discarding unused content as early as possible; all future steps can load the document without this extra content.
- More significant time is saved in this case by not evaluating the conref attribute; in fact, documentA does not even need to be parsed.
- 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.
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:
<note id="note" product="SomeOtherProduct">This is an important note!</note>
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.