| 1 | <?xml version="1.0" encoding="UTF-8"?>
|
|---|
| 2 | <!DOCTYPE html
|
|---|
| 3 | PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|---|
| 4 | <html xml:lang="en-us" lang="en-us">
|
|---|
| 5 | <head>
|
|---|
| 6 | <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
|
|---|
| 7 | <meta name="copyright" content="(C) Copyright 2005"/>
|
|---|
| 8 | <meta name="DC.rights.owner" content="(C) Copyright 2005"/>
|
|---|
| 9 | <meta name="DC.Type" content="concept"/>
|
|---|
| 10 | <meta name="DC.Title" content="DITA-OT processing order"/>
|
|---|
| 11 | <meta name="abstract" content="The order of processing is often significant when evaluating DITA content. Although the DITA specification does not mandate a specific order for processing, the 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."/>
|
|---|
| 12 | <meta name="description" content="The order of processing is often significant when evaluating DITA content. Although the DITA specification does not mandate a specific order for processing, the 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."/>
|
|---|
| 13 | <meta name="DC.Relation" scheme="URI" content="../dev_ref/DITA-OTArchitecture.html"/>
|
|---|
| 14 | <meta name="DC.Format" content="XHTML"/>
|
|---|
| 15 | <meta name="DC.Identifier" content="processing-order"/>
|
|---|
| 16 | <meta name="DC.Language" content="en-us"/>
|
|---|
| 17 | <link rel="stylesheet" type="text/css" href="../commonltr.css"/>
|
|---|
| 18 | <link rel="stylesheet" type="text/css" href="../dita-ot-doc.css"/>
|
|---|
| 19 | <title>DITA-OT processing order</title>
|
|---|
| 20 | </head>
|
|---|
| 21 | <body id="processing-order">
|
|---|
| 22 |
|
|---|
| 23 |
|
|---|
| 24 | <h1 class="title topictitle1">DITA-OT processing order</h1>
|
|---|
| 25 |
|
|---|
| 26 |
|
|---|
| 27 | <div class="body conbody"><p class="shortdesc">The order of processing is often significant when evaluating DITA content. Although the
|
|---|
| 28 | DITA specification does not mandate a specific order for processing, the DITA-OT has determined that
|
|---|
| 29 | performing filtering before conref resolution best meets user expectations. Switching the order of
|
|---|
| 30 | processing, while legal, may give different results. </p>
|
|---|
| 31 |
|
|---|
| 32 | <div class="section">
|
|---|
| 33 | <div class="p">The DITA-OT project has found that filtering first provides several benefits. Consider the
|
|---|
| 34 | following sample that contains a <note> element that both uses conref and contains a @product
|
|---|
| 35 | attribute:<pre class="pre codeblock"><note conref="documentA.dita#doc/note" product="MyProd"/></pre>
|
|---|
| 36 | </div>
|
|---|
| 37 | <p class="p">If the @conref attribute is evaluated first, then documentA must be parsed in order to retrieve
|
|---|
| 38 | the note content. That content is then stored in the current document (or in a representation of
|
|---|
| 39 | that document in memory). However, if all content with product="MyProd" is filtered out, then that
|
|---|
| 40 | work is all discarded later in the build.</p>
|
|---|
| 41 | <div class="p">If the filtering is done first (as in the DITA-OT), this element is discarded immediately, and
|
|---|
| 42 | documentA is never examined. This provides several important benefits:<ul class="ul">
|
|---|
| 43 | <li class="li">Time is saved by discarding unused content as early as possible; all future steps can load the
|
|---|
| 44 | document without this extra content.</li>
|
|---|
| 45 |
|
|---|
| 46 | <li class="li">Additional time is saved case by not evaluating the @conref attribute; in fact, documentA does
|
|---|
| 47 | not even need to be parsed.</li>
|
|---|
| 48 |
|
|---|
| 49 | <li class="li">Any user reproducing this build does not need documentA. If the content is sent to a translation
|
|---|
| 50 | team, that team can reproduce an error-free build without documentA; this means documentA can be
|
|---|
| 51 | kept back from translation, preventing accidental translation and increased costs.</li>
|
|---|
| 52 |
|
|---|
| 53 | </ul>
|
|---|
| 54 | </div>
|
|---|
| 55 |
|
|---|
| 56 | <div class="p">If the order of these two steps is reversed, so that conref is evaluated first, it is possible
|
|---|
| 57 | that results will differ. For example, in the code sample above, the @product attribute will
|
|---|
| 58 | override the product setting on the referencing note. Assume that the <note> elements in
|
|---|
| 59 | documentA is defined as
|
|---|
| 60 | follows:<pre class="pre codeblock"><note id="note" product="SomeOtherProduct">This is an important note!</note></pre>
|
|---|
| 61 | </div>
|
|---|
| 62 |
|
|---|
| 63 | <p class="p">A process that filters out product="SomeOtherProduct" will remove the target of the original
|
|---|
| 64 | conref before that conref is ever evaluated, which will result in a broken reference. Evaluating
|
|---|
| 65 | conref first would resolve the reference, and only later filter out the target of the conref. While
|
|---|
| 66 | some use cases can be found where this is the desired behavior, benefits such as those described
|
|---|
| 67 | above resulted in the current processing order used by the DITA-OT..</p>
|
|---|
| 68 | </div>
|
|---|
| 69 |
|
|---|
| 70 | </div>
|
|---|
| 71 |
|
|---|
| 72 | <div class="related-links">
|
|---|
| 73 | <div class="familylinks">
|
|---|
| 74 | <div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../dev_ref/DITA-OTArchitecture.html" title="The DITA Open Toolkit (DITA-OT) is an open-source implementation of the OASIS specification for the Darwin Information Typing Architecture (DITA). The toolkit uses ANT, XSLT, and Java to implement transforming DITA content (maps and topics) into different deliverable formats.">Architecture of the DITA Open Toolkit</a></div>
|
|---|
| 75 | </div>
|
|---|
| 76 | </div>
|
|---|
| 77 |
|
|---|
| 78 | </body>
|
|---|
| 79 | </html>
|
|---|
