| 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="reference"/>
|
|---|
| 10 | <meta name="DC.Title" content="Flagging in the toolkit"/>
|
|---|
| 11 | <meta name="abstract" content="Beginning with DITA-OT 1.7, flagging support is implemented as a common preprocess module. The module evaluates the DITAVAL against all flagging attributes, and adds DITA-OT specific hints in to the topic when flags are active. Any extended transform type may use these hints to support flagging without adding logic to interpret the DITAVAL."/>
|
|---|
| 12 | <meta name="description" content="Beginning with DITA-OT 1.7, flagging support is implemented as a common preprocess module. The module evaluates the DITAVAL against all flagging attributes, and adds DITA-OT specific hints in to the topic when flags are active. Any extended transform type may use these hints to support flagging without adding logic to interpret the DITAVAL."/>
|
|---|
| 13 | <meta name="DC.Relation" scheme="URI" content="../dev_ref/DITA-OTPreprocess.html"/>
|
|---|
| 14 | <meta name="DC.Relation" scheme="URI" content="../dev_ref/preprocess-topicpull.html"/>
|
|---|
| 15 | <meta name="DC.Format" content="XHTML"/>
|
|---|
| 16 | <meta name="DC.Identifier" content="flagging"/>
|
|---|
| 17 | <meta name="DC.Language" content="en-us"/>
|
|---|
| 18 | <link rel="stylesheet" type="text/css" href="../commonltr.css"/>
|
|---|
| 19 | <link rel="stylesheet" type="text/css" href="../dita-ot-doc.css"/>
|
|---|
| 20 | <title>Flagging in the toolkit</title>
|
|---|
| 21 | </head>
|
|---|
| 22 | <body id="flagging">
|
|---|
| 23 |
|
|---|
| 24 |
|
|---|
| 25 | <h1 class="title topictitle1">Flagging in the toolkit</h1>
|
|---|
| 26 |
|
|---|
| 27 |
|
|---|
| 28 | <div class="body refbody"><p class="shortdesc">Beginning with DITA-OT 1.7, flagging support is implemented
|
|---|
| 29 | as a common preprocess module. The module evaluates the DITAVAL against
|
|---|
| 30 | all flagging attributes, and adds DITA-OT specific hints in to the
|
|---|
| 31 | topic when flags are active. Any extended transform type may use these
|
|---|
| 32 | hints to support flagging without adding logic to interpret the DITAVAL.</p>
|
|---|
| 33 |
|
|---|
| 34 | <div class="section"><h2 class="title sectiontitle">Evaluating the DITAVAL flags</h2><p class="p">Flagging is
|
|---|
| 35 | implemented as a reusable module during the preprocess stage. If a
|
|---|
| 36 | DITAVAL file is not used with a build, this step is skipped with no
|
|---|
| 37 | change to the file.</p>
|
|---|
| 38 | <p class="p">When a flag is active, relevant sections
|
|---|
| 39 | of the DITAVAL itself are copied into the topic as a sub-element of
|
|---|
| 40 | the current topic. The active flags are enclosed in a pseudo-specialization
|
|---|
| 41 | of the <samp class="ph codeph"><foreign></samp> element (referred to as a pseudo-specialization
|
|---|
| 42 | because it is used only under the covers, with all topic types; it
|
|---|
| 43 | is not integrated into any shipped document types).</p>
|
|---|
| 44 | <dl class="dl">
|
|---|
| 45 | <dt class="dt dlterm"><samp class="ph codeph"><ditaval-startprop></samp></dt>
|
|---|
| 46 |
|
|---|
| 47 | <dd class="dd">When any flag is active on an element, a <samp class="ph codeph"><ditaval-startprop></samp> element
|
|---|
| 48 | will be created as the first child of the flagged element:<pre class="pre codeblock"><ditaval-startprop class="+ topic/foreign ditaot-d/ditaval-startprop "></pre>
|
|---|
| 49 | <div class="p">The <samp class="ph codeph"><ditaval-startprop></samp> element
|
|---|
| 50 | will contain the following:<ul class="ul">
|
|---|
| 51 | <li class="li">If the active flags should create a new style, that style is included
|
|---|
| 52 | using standard CSS markup on the @outputclass attribute. Output types
|
|---|
| 53 | that make use of CSS, such as XHTML, can use this value as-is.</li>
|
|---|
| 54 |
|
|---|
| 55 | <li class="li">If styles conflict, and a <samp class="ph codeph"><style-conflict></samp> element
|
|---|
| 56 | exists in the DITAVAL, it will be copied as a child of <samp class="ph codeph"><ditaval-startprop></samp>.</li>
|
|---|
| 57 |
|
|---|
| 58 | <li class="li">Any <samp class="ph codeph"><prop></samp> or <samp class="ph codeph"><revprop></samp> elements
|
|---|
| 59 | that define active flags will be copied in as children of the <samp class="ph codeph"><ditaval-startprop></samp> element.
|
|---|
| 60 | Any <samp class="ph codeph"><startflag></samp> children of the properties will
|
|---|
| 61 | be included, but <samp class="ph codeph"><endflag></samp> children will not.</li>
|
|---|
| 62 |
|
|---|
| 63 | </ul>
|
|---|
| 64 | </div>
|
|---|
| 65 | </dd>
|
|---|
| 66 |
|
|---|
| 67 |
|
|---|
| 68 | <dt class="dt dlterm"><samp class="ph codeph"><ditaval-endprop></samp></dt>
|
|---|
| 69 |
|
|---|
| 70 | <dd class="dd">When any flag is active on an element, a <samp class="ph codeph"><ditaval-endprop></samp> element
|
|---|
| 71 | will be created as the last child of the flagged element:<pre class="pre codeblock"><ditaval-endprop class="+ topic/foreign ditaot-d/ditaval-endprop "></pre>
|
|---|
| 72 | <p class="p">CSS
|
|---|
| 73 | values and <samp class="ph codeph"><styleconflict></samp> elements are not included
|
|---|
| 74 | on this element.</p>
|
|---|
| 75 | <p class="p">Any <samp class="ph codeph"><prop></samp> or <samp class="ph codeph"><revprop></samp> elements
|
|---|
| 76 | that define active flags will be copied in as children of <samp class="ph codeph"><ditaval-prop></samp>.
|
|---|
| 77 | Any <samp class="ph codeph"><endflag></samp> children of the properties will
|
|---|
| 78 | be included, but <samp class="ph codeph"><startflag></samp> children will not.</p>
|
|---|
| 79 | </dd>
|
|---|
| 80 |
|
|---|
| 81 | </dl>
|
|---|
| 82 | </div>
|
|---|
| 83 |
|
|---|
| 84 | <div class="section"><h2 class="title sectiontitle">Supporting flags in overrides or custom transform
|
|---|
| 85 | types</h2><p class="p">For most transform types, the <samp class="ph codeph"><foreign></samp> element
|
|---|
| 86 | should be ignored by default, because arbitrary non-DITA content may
|
|---|
| 87 | not mix well unless coded for ahead of time. If the <samp class="ph codeph"><foreign></samp> element
|
|---|
| 88 | is ignored by default, or if a rule is added to specifically ignore <samp class="ph codeph"><ditaval-startprop></samp> and <samp class="ph codeph"><ditaval-endprop></samp>,
|
|---|
| 89 | then the added elements will have no impact on a transform. If desired,
|
|---|
| 90 | flagging support may be integrated at any time in the future.</p>
|
|---|
| 91 | <p class="p">The
|
|---|
| 92 | processing described above runs as part of the common preprocess,
|
|---|
| 93 | so any transform that uses the default preprocess will get the topic
|
|---|
| 94 | updates. To support generating flags as images, XSLT based transforms
|
|---|
| 95 | can use default fallthrough processing in most cases. For example,
|
|---|
| 96 | if a paragraph is flagged, the first child of <samp class="ph codeph"><p></samp> will
|
|---|
| 97 | contain the start flag information; adding a rule to handle images
|
|---|
| 98 | in <samp class="ph codeph"><ditaval-startprop></samp> will cause the image to
|
|---|
| 99 | appear at the start of the paragraph content.</p>
|
|---|
| 100 | <p class="p">In some cases
|
|---|
| 101 | fallthrough processing will not result in valid output; for those
|
|---|
| 102 | cases, the flags must be explicitly processed. This is done in the
|
|---|
| 103 | XHTML transform for elements like <samp class="ph codeph"><ol></samp>, because
|
|---|
| 104 | fallthrough processing would place images in between <samp class="ph codeph"><ol></samp> and <samp class="ph codeph"><li></samp>.
|
|---|
| 105 | To handle this, the code processes <samp class="ph codeph"><ditaval-startprop></samp> before
|
|---|
| 106 | starting the element, and <samp class="ph codeph"><ditaval-endprop></samp> at
|
|---|
| 107 | the end. Fallthrough processing is then disabled for those elements
|
|---|
| 108 | as children of <samp class="ph codeph"><ol></samp>.</p>
|
|---|
| 109 | </div>
|
|---|
| 110 |
|
|---|
| 111 | <div class="example"><h2 class="title sectiontitle">Example DITAVAL</h2><p class="p">Assume the following DITAVAL
|
|---|
| 112 | file is in use during a build. This DITAVAL will be used for each
|
|---|
| 113 | of the following content examples.</p>
|
|---|
| 114 | <pre class="pre codeblock"><?xml version="1.0" encoding="UTF-8"?>
|
|---|
| 115 | <val>
|
|---|
| 116 | <!-- Define what happens in the case of conflicting styles -->
|
|---|
| 117 | <style-conflict background-conflict-color="red"/>
|
|---|
| 118 |
|
|---|
| 119 | <!-- Define two flagging properties that give styles (no image) -->
|
|---|
| 120 | <prop action="flag" att="audience" style="underline" val="user" backcolor="green"/>
|
|---|
| 121 | <prop action="flag" att="platform" style="overline" val="win" backcolor="blue"/>
|
|---|
| 122 |
|
|---|
| 123 | <!-- Define a property that includes start and end image flags -->
|
|---|
| 124 | <prop action="flag" att="platform" val="linux" style="overline" backcolor="blue">
|
|---|
| 125 | <startflag imageref="startlin.png"><alt-text>Start linux</alt-text></startflag>
|
|---|
| 126 | <endflag imageref="endlin.png"><alt-text>End linux</alt-text></endflag>
|
|---|
| 127 | </prop>
|
|---|
| 128 |
|
|---|
| 129 | <!-- Define a revision that includes start and end image flags -->
|
|---|
| 130 | <revprop action="flag" style="double-underline" val="rev2">
|
|---|
| 131 | <startflag imageref="start_rev.gif"><alt-text>ssssssssssstart</alt-text></startflag>
|
|---|
| 132 | <endflag imageref="end_rev.gif"><alt-text>eeeeeeeeeeeeeend</alt-text></endflag>
|
|---|
| 133 | </revprop>
|
|---|
| 134 | </val></pre>
|
|---|
| 135 | </div>
|
|---|
| 136 |
|
|---|
| 137 | <div class="example"><h2 class="title sectiontitle">Content example 1: adding style</h2><p class="p">Now assume
|
|---|
| 138 | the following paragraph exists in a topic. Class attributes are included,
|
|---|
| 139 | as they would normally be in the middle of the preprocess routine;
|
|---|
| 140 | @xtrf and @xtrc are left off for clarity.</p>
|
|---|
| 141 | <pre class="pre codeblock"><p audience="user">Simple user; includes style but no images</p>
|
|---|
| 142 | </pre>
|
|---|
| 143 | <p class="p">Based on the DITAVAL above, audience="user" results
|
|---|
| 144 | in a style with underlining and with a green background. The interpreted
|
|---|
| 145 | CSS value is added to @outputclass on <samp class="ph codeph"><ditaval-startprop></samp>,
|
|---|
| 146 | and the actual property definition is included at the start and end
|
|---|
| 147 | of the element. The output from the flagging step looks like this
|
|---|
| 148 | (with newlines added for clarity, and class attributes added as they
|
|---|
| 149 | would appear in the temporary file):</p>
|
|---|
| 150 | <p class="p">The resulting file after
|
|---|
| 151 | the flagging step looks like this; for clarity, newlines are added,
|
|---|
| 152 | while @xtrf and @xtrc are removed:</p>
|
|---|
| 153 | <pre class="pre codeblock"><p audience="user" class="- topic/p ">
|
|---|
| 154 | <strong class="ph b"><ditaval-startprop class="+ topic/foreign ditaot-d/ditaval-startprop "
|
|---|
| 155 | outputclass="background-color:green;text-decoration:underline;">
|
|---|
| 156 | <prop action="flag" att="audience" style="underline" val="user" backcolor="green"/>
|
|---|
| 157 | </ditaval-startprop></strong>
|
|---|
| 158 | Simple user; includes style but no images
|
|---|
| 159 | <strong class="ph b"><ditaval-endprop class="+ topic/foreign ditaot-d/ditaval-endprop ">
|
|---|
| 160 | <prop action="flag" att="audience" style="underline" val="user" backcolor="green"/>
|
|---|
| 161 | </ditaval-endprop></strong>
|
|---|
| 162 | </p></pre>
|
|---|
| 163 | </div>
|
|---|
| 164 |
|
|---|
| 165 | <div class="example"><h2 class="title sectiontitle">Content example 2: conflicting styles</h2><p class="p">This
|
|---|
| 166 | example includes a paragraph with conflicting styles. When the audience
|
|---|
| 167 | and platform attributes are both evaluated, the DITAVAL indicates
|
|---|
| 168 | that the background color is both green and blue. In this situation,
|
|---|
| 169 | the <samp class="ph codeph"><style-conflict></samp> element is evaluated to determine
|
|---|
| 170 | how to style the content.</p>
|
|---|
| 171 | <pre class="pre codeblock"><p audience="user" platform="win">Conflicting styles (still no images)</p>
|
|---|
| 172 | </pre>
|
|---|
| 173 | <p class="p">The <samp class="ph codeph"><style-conflict></samp> element results
|
|---|
| 174 | in a background color of red, so this value is added to @outputclass
|
|---|
| 175 | on <samp class="ph codeph"><ditaval-startprop></samp>. As above, active properties
|
|---|
| 176 | are copied into the generated elements; the <samp class="ph codeph"><style-conflict></samp> element
|
|---|
| 177 | itself is also copied into the generated <samp class="ph codeph"><ditaval-startprop></samp> element.</p>
|
|---|
| 178 | <p class="p">The
|
|---|
| 179 | resulting file after the flagging step looks like this; for clarity,
|
|---|
| 180 | newlines are added, while @xtrf and @xtrc are removed:</p>
|
|---|
| 181 | <pre class="pre codeblock"><p audience="user" platform="win" class="- topic/p ">
|
|---|
| 182 | <strong class="ph b"><ditaval-startprop class="+ topic/foreign ditaot-d/ditaval-startprop "
|
|---|
| 183 | outputclass="background-color:red;">
|
|---|
| 184 | <style-conflict background-conflict-color="red"/>
|
|---|
| 185 | <prop action="flag" att="audience" style="underline" val="user" backcolor="green"/>
|
|---|
| 186 | <prop action="flag" att="platform" style="overline" val="win" backcolor="blue"/>
|
|---|
| 187 | </ditaval-startprop></strong>
|
|---|
| 188 | Conflicting styles (still no images)
|
|---|
| 189 | <strong class="ph b"><ditaval-endprop class="+ topic/foreign ditaot-d/ditaval-endprop ">
|
|---|
| 190 | <prop action="flag" att="platform" style="overline" val="win" backcolor="blue"/>
|
|---|
| 191 | <prop action="flag" att="audience" style="underline" val="user" backcolor="green"/>
|
|---|
| 192 | </ditaval-endprop></strong>
|
|---|
| 193 | </p>
|
|---|
| 194 | </pre>
|
|---|
| 195 | </div>
|
|---|
| 196 |
|
|---|
| 197 | <div class="example"><h2 class="title sectiontitle">Content example 3: adding image flags</h2><p class="p">This
|
|---|
| 198 | example includes image flags for both @platform and @rev, which are
|
|---|
| 199 | defined in DITAVAL <samp class="ph codeph"><prop></samp> and <samp class="ph codeph"><revprop></samp> elements.</p>
|
|---|
| 200 | <pre class="pre codeblock"><ol platform="linux" rev="rev2">
|
|---|
| 201 | <li>Generate images for platform="linux" and rev="2"</li>
|
|---|
| 202 | </ol></pre>
|
|---|
| 203 | <p class="p">As above, the <samp class="ph codeph"><ditaval-startprop></samp> and <samp class="ph codeph"><ditaval-endprop></samp> nest
|
|---|
| 204 | the active property definitions, with the calculated CSS value on
|
|---|
| 205 | @outputclass. The <samp class="ph codeph"><ditaval-startprop></samp> drops the
|
|---|
| 206 | ending image, and <samp class="ph codeph"><ditaval-endprop></samp> drops the
|
|---|
| 207 | starting image. To make document-order processing more consistent,
|
|---|
| 208 | property flags are always included before revisions in <samp class="ph codeph"><ditaval-startprop></samp>,
|
|---|
| 209 | and the order is reversed for <samp class="ph codeph"><ditaval-endprop></samp>.</p>
|
|---|
| 210 | <p class="p">The
|
|---|
| 211 | resulting file after the flagging step looks like this; for clarity,
|
|---|
| 212 | newlines are added, while @xtrf and @xtrc are removed:</p>
|
|---|
| 213 | <pre class="pre codeblock"><ol platform="linux" rev="rev2" class="- topic/ol ">
|
|---|
| 214 | <strong class="ph b"><ditaval-startprop class="+ topic/foreign ditaot-d/ditaval-startprop "
|
|---|
| 215 | outputclass="background-color:blue;text-decoration:underline;text-decoration:overline;">
|
|---|
| 216 | <prop action="flag" att="platform" val="linux" style="overline" backcolor="blue">
|
|---|
| 217 | <startflag imageref="startlin.png"><alt-text>Start linux</alt-text></startflag>
|
|---|
| 218 | </prop>
|
|---|
| 219 | <revprop action="flag" style="double-underline" val="rev2">
|
|---|
| 220 | <startflag imageref="start_rev.gif"><alt-text>ssssssssssstart</alt-text></startflag>
|
|---|
| 221 | </revprop>
|
|---|
| 222 | </ditaval-startprop></strong>
|
|---|
| 223 | <li class="- topic/li ">Generate images for platform="linux" and rev="2"</li>
|
|---|
| 224 | <strong class="ph b"><ditaval-endprop class="+ topic/foreign ditaot-d/ditaval-endprop ">
|
|---|
| 225 | <revprop action="flag" style="double-underline" val="rev2">
|
|---|
| 226 | <endflag imageref="end_rev.gif"><alt-text>eeeeeeeeeeeeeend</alt-text></endflag>
|
|---|
| 227 | </revprop>
|
|---|
| 228 | <prop action="flag" att="platform" val="linux" style="overline" backcolor="blue">
|
|---|
| 229 | <endflag imageref="endlin.png"><alt-text>End linux</alt-text></endflag>
|
|---|
| 230 | </prop>
|
|---|
| 231 | </ditaval-endprop></strong>
|
|---|
| 232 | </ol></pre>
|
|---|
| 233 | </div>
|
|---|
| 234 |
|
|---|
| 235 | </div>
|
|---|
| 236 |
|
|---|
| 237 | <div class="related-links">
|
|---|
| 238 | <div class="familylinks">
|
|---|
| 239 | <div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../dev_ref/DITA-OTPreprocess.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>
|
|---|
| 240 | <div class="previouslink"><strong>Previous topic:</strong> <a class="link" href="../dev_ref/preprocess-topicpull.html" title="The topicpull step pulls content into <xref> and <link> elements. This step is implemented in XSLT.">Pull content into topics (topicpull)</a></div>
|
|---|
| 241 | </div>
|
|---|
| 242 | </div>
|
|---|
| 243 |
|
|---|
| 244 | </body>
|
|---|
| 245 | </html>
|
|---|
