218 lines
No EOL
24 KiB
HTML
218 lines
No EOL
24 KiB
HTML
<!DOCTYPE html
|
||
SYSTEM "about:legacy-compat">
|
||
<html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta charset="UTF-8"><meta name="copyright" content="(C) Copyright 2020"><meta name="generator" content="DITA-OT"><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="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"><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.6</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/building-output.html">Building output</a></li><li><a href="../topics/input-formats.html">Authoring formats</a></li><li><a href="../topics/output-formats.html">Output formats</a></li><li><a href="../parameters/index.html">Parameters</a></li><li><a href="../topics/html-customization.html">Customizing HTML</a></li><li><a href="../topics/pdf-customization.html">Customizing PDF</a></li><li><a href="../topics/adding-plugins.html">Adding plug-ins</a></li><li><a href="../topics/custom-plugins.html">Creating plug-ins</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/store-api.html">Store API</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/html-based-processing.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="../extension-points/plugin-extension-points.html">Extension points</a></li><li><a href="../reference/license.html">License</a></li><li><a href="../reference/glossary.html#glossary">Glossary</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> |