| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218 |
- <!DOCTYPE html
- SYSTEM "about:legacy-compat">
- <html lang="en-us"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta charset="UTF-8"><meta name="copyright" content="(C) Copyright 2019"><meta name="DC.rights.owner" content="(C) Copyright 2019"><meta name="DC.type" content="reference"><meta name="description" content="Beginning with DITA-OT 1.7, flagging support is implemented as a common flag-module preprocessing step. The module evaluates the DITAVAL against all flagging attributes, and adds DITA-OT–specific hints to the topic when flags are active. Any extended transformation type may use these hints to support flagging without adding logic to interpret the DITAVAL."><meta name="DC.subject" content=", foreign, ditaval-startprop, prop, revprop, startflag, endflag, ditaval-endprop, ditaval-prop, p, ol, li, outputclass, xtrf, xtrc, rev, DITAVAL, preprocess step, flag-module, DITA, specializations, preprocessing, flagging, XSLT, CSS, images"><meta name="keywords" content=", foreign, ditaval-startprop, prop, revprop, startflag, endflag, ditaval-endprop, ditaval-prop, p, ol, li, outputclass, xtrf, xtrc, rev, DITAVAL, preprocess step, flag-module, DITA, specializations, preprocessing, flagging, XSLT, CSS, images"><meta name="DC.relation" scheme="URI" content="../reference/preprocessing.html"><meta name="DC.relation" scheme="URI" content="../reference/preprocess-topicpull.html"><meta name="DC.relation" scheme="URI" content="../reference/preprocess-clean-map.html"><meta name="DC.format" content="HTML5"><meta name="DC.identifier" content="flagging"><meta name="DC.language" content="en-US"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Flagging (flag-module)</title></head><body id="flagging"><header role="banner"><div class="header">
- <p>DITA Open Toolkit</p>
- <hr>
- </div></header><nav role="toc"><ul><li><a href="../index.html">DITA Open Toolkit 3.3</a></li><li><a href="../release-notes/index.html">Release Notes</a></li><li><a href="../topics/installing-client.html">Installing DITA-OT</a></li><li><a href="../topics/alternative-input-formats.html">Authoring formats</a></li><li><a href="../topics/building-output.html">Building output</a></li><li><a href="../parameters/index.html">Setting parameters</a></li><li><a href="../topics/customizing.html">Customizing DITA-OT</a></li><li><a href="../topics/troubleshooting-overview.html">Troubleshooting</a></li><li><a href="../reference/index.html">Reference</a><ul><li><a href="../reference/architecture.html">DITA-OT architecture</a><ul><li><a href="../reference/processing-structure.html">Processing structure</a></li><li><a href="../reference/map-first-preprocessing.html">Map-first preprocessing</a></li><li><a href="../reference/processing-pipeline-modules.html">Processing modules</a></li><li><a href="../reference/processing-order.html">Processing order</a></li><li><a href="../reference/preprocessing.html">Pre-processing modules</a><ul><li><a href="../reference/preprocess-genlist.html">Generate lists (gen-list)</a></li><li><a href="../reference/preprocess-debugfilter.html">Debug and filter (debug-filter)</a></li><li><a href="../reference/preprocess-mapref.html">Resolve map references (mapref)</a></li><li><a href="../reference/preprocess-branch-filter.html">Branch filtering (branch-filter)</a></li><li><a href="../reference/preprocess-keyref.html">Resolve key references (keyref)</a></li><li><a href="../reference/preprocess-copy-to.html">Copy topics (copy-to)</a></li><li><a href="../reference/preprocess-conrefpush.html">Conref push (conrefpush)</a></li><li><a href="../reference/preprocess-conref.html">Resolve content references (conref)</a></li><li><a href="../reference/preprocess-profile.html">Filter conditional content (profile)</a></li><li><a href="../reference/preprocess-topic-fragment.html">Resolve topic fragments and code references (topic-fragment)</a></li><li><a href="../reference/preprocess-chunk.html">Chunk topics (chunk)</a></li><li><a href="../reference/preprocess-metadata.html">Move metadata (move-meta-entries) and pull content into maps (mappull) </a></li><li><a href="../reference/preprocess-maplink.html">Map based linking (maplink)</a></li><li><a href="../reference/preprocess-topicpull.html">Pull content into topics (topicpull)</a></li><li class="active"><a href="../reference/preprocess-flagging.html">Flagging (flag-module)</a></li><li><a href="../reference/preprocess-clean-map.html">Map cleanup (clean-map)</a></li><li><a href="../reference/preprocess-copyfiles.html">Copy related files (copy-files)</a></li></ul></li><li><a href="../reference/XhtmlWithNavigation.html">HTML-based processing modules</a></li><li><a href="../reference/pdf-transform.html">PDF processing modules</a></li></ul></li><li><a href="../reference/DITA_spec-support.html">DITA specification support</a></li><li><a href="../reference/license.html">License</a></li></ul></li><li><a href="../topics/dita-and-dita-ot-resources.html">Resources</a></li></ul></nav><main role="main"><article role="article" aria-labelledby="ariaid-title1">
- <h1 class="title topictitle1" id="ariaid-title1">Flagging (flag-module)</h1>
-
-
- <div class="body refbody"><p class="shortdesc">Beginning with DITA-OT 1.7, flagging support is implemented as a common <code class="ph codeph">flag-module</code>
- preprocessing step. The module evaluates the DITAVAL against all flagging attributes, and adds DITA-OT–specific
- hints to the topic when flags are active. Any extended transformation type may use these hints to support flagging
- without adding logic to interpret the DITAVAL.</p>
- <section class="section"><h2 class="title sectiontitle">Evaluating the DITAVAL flags</h2>
-
- <p class="p">Flagging is implemented as a reusable module during the preprocess stage. If a DITAVAL file is not used with a
- build, this step is skipped with no change to the file.</p>
- <p class="p">When a flag is active, relevant sections of the DITAVAL itself are copied into the topic as a sub-element of
- the current topic. The active flags are enclosed in a pseudo-specialization of the
- <code class="keyword markupname xmlelement"><foreign></code> element (referred to as a pseudo-specialization because it is used only under
- the covers, with all topic types; it is not integrated into any shipped document types).</p>
- <dl class="dl parml">
-
- <dt class="dt pt dlterm"><code class="keyword markupname xmlelement"><ditaval-startprop></code></dt>
- <dd class="dd pd">
- <p class="p">When any flag is active on an element, a <code class="keyword markupname xmlelement"><ditaval-startprop></code> element will be
- created as the first child of the flagged element:</p>
- <pre class="pre codeblock language-xml"><code><ditaval-startprop class="+ topic/foreign ditaot-d/ditaval-startprop "></code></pre>
- <div class="p">The <code class="keyword markupname xmlelement"><ditaval-startprop></code> element will contain the following:
- <ul class="ul">
- <li class="li">If the active flags should create a new style, that style is included using standard CSS markup on
- the <code class="keyword markupname xmlatt">@outputclass</code> attribute. Output types that make use of CSS, such as XHTML, can use
- this value as-is.</li>
- <li class="li">If styles conflict, and a <code class="keyword markupname xmlelement"><style-conflict></code> element exists in the DITAVAL, it
- will be copied as a child of <code class="keyword markupname xmlelement"><ditaval-startprop></code>.</li>
- <li class="li">Any <code class="keyword markupname xmlelement"><prop></code> or <code class="keyword markupname xmlelement"><revprop></code> elements that define active
- flags will be copied in as children of the <code class="keyword markupname xmlelement"><ditaval-startprop></code> element. Any
- <code class="keyword markupname xmlelement"><startflag></code> children of the properties will be included, but
- <code class="keyword markupname xmlelement"><endflag></code> children will not.</li>
- </ul>
- </div>
- </dd>
-
-
- <dt class="dt pt dlterm"><code class="keyword markupname xmlelement"><ditaval-endprop></code></dt>
- <dd class="dd pd">
- <p class="p">When any flag is active on an element, a <code class="keyword markupname xmlelement"><ditaval-endprop></code> element will be created
- as the last child of the flagged element:</p>
- <pre class="pre codeblock language-xml"><code><ditaval-endprop class="+ topic/foreign ditaot-d/ditaval-endprop "></code></pre>
- <p class="p">CSS values and <code class="keyword markupname xmlelement"><style-conflict></code> elements are not included on this element.</p>
- <p class="p">Any <code class="keyword markupname xmlelement"><prop></code> or <code class="keyword markupname xmlelement"><revprop></code> elements that define active flags
- will be copied in as children of <code class="keyword markupname xmlelement"><ditaval-prop></code>. Any
- <code class="keyword markupname xmlelement"><startflag></code> children of the properties will be included, but
- <code class="keyword markupname xmlelement"><endflag></code> children will not.</p>
- </dd>
-
- </dl>
- </section>
- <section class="section"><h2 class="title sectiontitle">Supporting flags in overrides or custom transformation types</h2>
-
- <p class="p">For most transformation types, the <code class="keyword markupname xmlelement"><foreign></code> element should be ignored by default,
- because arbitrary non-DITA content may not mix well unless coded for ahead of time. If the
- <code class="keyword markupname xmlelement"><foreign></code> element is ignored by default, or if a rule is added to specifically ignore
- <code class="keyword markupname xmlelement"><ditaval-startprop></code> and <code class="keyword markupname xmlelement"><ditaval-endprop></code>, then the added
- elements will have no impact on a transform. If desired, flagging support may be integrated at any time in the
- future.</p>
- <p class="p">The processing described above runs as part of the common preprocess, so any transform that uses the default
- preprocess will get the topic updates. To support generating flags as images, XSLT based transforms can use
- default fallthrough processing in most cases. For example, if a paragraph is flagged, the first child of
- <code class="keyword markupname xmlelement"><p></code> will contain the start flag information; adding a rule to handle images in
- <code class="keyword markupname xmlelement"><ditaval-startprop></code> will cause the image to appear at the start of the paragraph
- content.</p>
- <p class="p">In some cases fallthrough processing will not result in valid output; for those cases, the flags must be
- explicitly processed. This is done in the XHTML transform for elements like <code class="keyword markupname xmlelement"><ol></code>, because
- fallthrough processing would place images in between <code class="keyword markupname xmlelement"><ol></code> and
- <code class="keyword markupname xmlelement"><li></code>. To handle this, the code processes <code class="keyword markupname xmlelement"><ditaval-startprop></code>
- before starting the element, and <code class="keyword markupname xmlelement"><ditaval-endprop></code> at the end. Fallthrough processing is
- then disabled for those elements as children of <code class="keyword markupname xmlelement"><ol></code>.</p></section>
- <div class="example"><h2 class="title sectiontitle">Example DITAVAL</h2>
-
- <p class="p">Assume the following DITAVAL file is in use during a build. This DITAVAL will be used for each of the following
- content examples.</p>
- <pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code><?xml version="1.0" encoding="UTF-8"?>
- <val>
- <em class="ph i"><!-- Define what happens in the case of conflicting styles --></em>
- <style-conflict background-conflict-color="red"/>
- <em class="ph i"><!-- Define two flagging properties that give styles (no image) --></em>
- <prop action="flag" att="audience" style="underline" val="user"
- backcolor="green"/>
- <prop action="flag" att="platform" style="overline" val="win"
- backcolor="blue"/>
- <em class="ph i"><!-- Define a property that includes start and end image flags --></em>
- <prop action="flag" att="platform" val="linux" style="overline"
- backcolor="blue">
- <startflag imageref="startlin.png">
- <alt-text>Start linux</alt-text></startflag>
- <endflag imageref="endlin.png">
- <alt-text>End linux</alt-text></endflag>
- </prop>
- <em class="ph i"><!-- Define a revision that includes start and end image flags --></em>
- <revprop action="flag" style="double-underline" val="rev2">
- <startflag imageref="start_rev.gif">
- <alt-text>START</alt-text></startflag>
- <endflag imageref="end_rev.gif"><alt-text>END</alt-text></endflag>
- </revprop>
- </val></code></pre>
- </div>
- <div class="example"><h2 class="title sectiontitle">Content example 1: Adding style</h2>
-
- <p class="p">Now assume the following paragraph exists in a topic. Class attributes are included, as they would normally be
- in the middle of the preprocess routine; <code class="keyword markupname xmlatt">@xtrf</code> and <code class="keyword markupname xmlatt">@xtrc</code> are left off for
- clarity.</p>
- <pre class="pre codeblock language-xml"><code><p audience="user">Simple user; includes style but no images</p></code></pre>
- <p class="p">Based on the DITAVAL above, audience="user" results in a style with underlining and with a green background.
- The interpreted CSS value is added to <code class="keyword markupname xmlatt">@outputclass</code> on
- <code class="keyword markupname xmlelement"><ditaval-startprop></code>, and the actual property definition is included at the start and end
- of the element. The output from the flagging step looks like this (with newlines added for clarity, and class
- attributes added as they would appear in the temporary file):</p>
- <p class="p">The resulting file after the flagging step looks like this; for clarity, newlines are added, while
- <code class="keyword markupname xmlatt">@xtrf</code> and <code class="keyword markupname xmlatt">@xtrc</code> are removed:</p>
- <pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code><p audience="user" class="- topic/p ">
- <strong class="ph b"><ditaval-startprop</strong>
- <strong class="ph b">class="+ topic/foreign ditaot-d/ditaval-startprop "</strong>
- <strong class="ph b">outputclass="background-color:green;text-decoration:underline;"></strong>
- <strong class="ph b"><prop action="flag" att="audience" style="underline" val="user"
- backcolor="green"/></strong>
- <strong class="ph b"></ditaval-startprop></strong>
- Simple user; includes style but no images
- <strong class="ph b"><ditaval-endprop</strong>
- <strong class="ph b">class="+ topic/foreign ditaot-d/ditaval-endprop "></strong>
- <strong class="ph b"><prop action="flag" att="audience" style="underline" val="user"
- backcolor="green"/></strong>
- <strong class="ph b"></ditaval-endprop></strong>
- </p></code></pre>
- </div>
- <div class="example"><h2 class="title sectiontitle">Content example 2: Conflicting styles</h2>
-
- <p class="p">This example includes a paragraph with conflicting styles. When the audience and platform attributes are both
- evaluated, the DITAVAL indicates that the background color is both green and blue. In this situation, the
- <code class="keyword markupname xmlelement"><style-conflict></code> element is evaluated to determine how to style the content.</p>
- <pre class="pre codeblock language-xml"><code><p audience="user" platform="win">Conflicting styles (still no images)</p></code></pre>
- <p class="p">The <code class="keyword markupname xmlelement"><style-conflict></code> element results in a background color of red, so this value is
- added to <code class="keyword markupname xmlatt">@outputclass</code> on <code class="keyword markupname xmlelement"><ditaval-startprop></code>. As above, active properties
- are copied into the generated elements; the <code class="keyword markupname xmlelement"><style-conflict></code> element itself is also
- copied into the generated <code class="keyword markupname xmlelement"><ditaval-startprop></code> element.</p>
- <p class="p">The resulting file after the flagging step looks like this; for clarity, newlines are added, while
- <code class="keyword markupname xmlatt">@xtrf</code> and <code class="keyword markupname xmlatt">@xtrc</code> are removed:</p>
- <pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code><p audience="user" platform="win" class="- topic/p ">
- <strong class="ph b"><ditaval-startprop</strong>
- <strong class="ph b">class="+ topic/foreign ditaot-d/ditaval-startprop "</strong>
- <strong class="ph b">outputclass="background-color:red;"></strong>
- <strong class="ph b"><style-conflict background-conflict-color="red"/></strong>
- <strong class="ph b"><prop action="flag" att="audience" style="underline" val="user"
- backcolor="green"/></strong>
- <strong class="ph b"><prop action="flag" att="platform" style="overline" val="win"
- backcolor="blue"/></strong>
- <strong class="ph b"></ditaval-startprop></strong>
- Conflicting styles (still no images)
- <strong class="ph b"><ditaval-endprop</strong>
- <strong class="ph b">class="+ topic/foreign ditaot-d/ditaval-endprop "></strong>
- <strong class="ph b"><prop action="flag" att="platform" style="overline" val="win"
- backcolor="blue"/></strong>
- <strong class="ph b"><prop action="flag" att="audience" style="underline" val="user"
- backcolor="green"/></strong><strong class="ph b">
- </ditaval-endprop></strong>
- </p></code></pre>
- </div>
- <div class="example"><h2 class="title sectiontitle">Content example 3: Adding image flags</h2>
-
- <p class="p">This example includes image flags for both <code class="keyword markupname xmlatt">@platform</code> and <code class="keyword markupname xmlatt">@rev</code>, which are
- defined in DITAVAL <code class="keyword markupname xmlelement"><prop></code> and <code class="keyword markupname xmlelement"><revprop></code> elements.</p>
- <pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code><ol platform="linux" rev="rev2">
- <li>Generate images for platform="linux" and rev="2"</li>
- </ol></code></pre>
- <p class="p">As above, the <code class="keyword markupname xmlelement"><ditaval-startprop></code> and <code class="keyword markupname xmlelement"><ditaval-endprop></code> nest the
- active property definitions, with the calculated CSS value on <code class="keyword markupname xmlatt">@outputclass</code>. The
- <code class="keyword markupname xmlelement"><ditaval-startprop></code> drops the ending image, and
- <code class="keyword markupname xmlelement"><ditaval-endprop></code> drops the starting image. To make document-order processing more
- consistent, property flags are always included before revisions in <code class="keyword markupname xmlelement"><ditaval-startprop></code>,
- and the order is reversed for <code class="keyword markupname xmlelement"><ditaval-endprop></code>.</p>
- <p class="p">The resulting file after the flagging step looks like this; for clarity, newlines are added, while
- <code class="keyword markupname xmlatt">@xtrf</code> and <code class="keyword markupname xmlatt">@xtrc</code> are removed:</p>
- <pre class="pre codeblock language-xml normalize-space show-line-numbers show-whitespace"><code><ol platform="linux" rev="rev2" class="- topic/ol ">
- <strong class="ph b"><ditaval-startprop</strong>
- <strong class="ph b">class="+ topic/foreign ditaot-d/ditaval-startprop "</strong>
- <strong class="ph b">outputclass="background-color:blue;</strong>
- <strong class="ph b">text-decoration:underline;</strong>
- <strong class="ph b">text-decoration:overline;"></strong>
- <strong class="ph b"><prop action="flag" att="platform" val="linux" style="overline"
- backcolor="blue"></strong>
- <strong class="ph b"><startflag imageref="startlin.png"></strong>
- <strong class="ph b"><alt-text>Start linux</alt-text></startflag></prop></strong>
- <strong class="ph b"><revprop action="flag" style="double-underline" val="rev2"></strong>
- <strong class="ph b"><startflag imageref="start_rev.gif"></strong>
- <strong class="ph b"><alt-text> </alt-text></startflag></revprop></strong>
- <strong class="ph b"></ditaval-startprop></strong>
- <li class="- topic/li ">
- Generate images for platform="linux" and rev="2"
- </li>
- <strong class="ph b"><ditaval-endprop</strong>
- <strong class="ph b">class="+ topic/foreign ditaot-d/ditaval-endprop "></strong>
- <strong class="ph b"><revprop action="flag" style="double-underline" val="rev2"></strong>
- <strong class="ph b"><endflag imageref="end_rev.gif"></strong>
- <strong class="ph b"><alt-text>END</alt-text></endflag></revprop></strong>
- <strong class="ph b"><prop action="flag" att="platform" val="linux" style="overline"</strong>
- <strong class="ph b">backcolor="blue"></strong>
- <strong class="ph b"><endflag imageref="endlin.png"></strong>
- <strong class="ph b"><alt-text>End linux</alt-text></endflag></prop></strong>
- <strong class="ph b"></ditaval-endprop></strong>
- </ol></code></pre>
- </div>
- </div>
- <nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../reference/preprocessing.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><div class="previouslink"><strong>Previous topic:</strong> <a class="link" href="../reference/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><div class="nextlink"><strong>Next topic:</strong> <a class="link" href="../reference/preprocess-clean-map.html" title="The clean-map step removes any elements and attributes that were added to files to support preprocessing.">Map cleanup (clean-map)</a></div></div></nav></article></main></body></html>
|
