Evaluating the DITAVAL flags
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.
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
foreign 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).
ditaval-startprop
When any flag is active on an element, a ditaval-startprop element will be
created as the first child of the flagged element:
<ditaval-startprop class="+ topic/foreign ditaot-d/ditaval-startprop ">
The ditaval-startprop element will contain the following:
- If the active flags should create a new style, that style is included using standard CSS markup on
the outputclass attribute. Output types that make use of CSS, such as XHTML, can use
this value as-is.
- If styles conflict, and a style-conflict element exists in the DITAVAL, it
will be copied as a child of ditaval-startprop.
- Any prop or revprop elements that define active
flags will be copied in as children of the ditaval-startprop element. Any
startflag children of the properties will be included, but
endflag children will not.
ditaval-endprop
When any flag is active on an element, a ditaval-endprop element will be created
as the last child of the flagged element:
<ditaval-endprop class="+ topic/foreign ditaot-d/ditaval-endprop ">
CSS values and style-conflict elements are not included on this element.
Any prop or revprop elements that define active flags
will be copied in as children of ditaval-prop. Any
startflag children of the properties will be included, but
endflag children will not.
Supporting flags in overrides or custom transformation types
For most transformation types, the foreign element should be ignored by default,
because arbitrary non-DITA content may not mix well unless coded for ahead of time. If the
foreign element is ignored by default, or if a rule is added to specifically ignore
ditaval-startprop and ditaval-endprop, then the added
elements will have no impact on a transform. If desired, flagging support may be integrated at any time in the
future.
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
p will contain the start flag information; adding a rule to handle images in
ditaval-startprop will cause the image to appear at the start of the paragraph
content.
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 ol, because
fallthrough processing would place images in between ol and
li. To handle this, the code processes ditaval-startprop
before starting the element, and ditaval-endprop at the end. Fallthrough processing is
then disabled for those elements as children of ol.
Example DITAVAL
Assume the following DITAVAL file is in use during a build. This DITAVAL will be used for each of the following
content examples.
<?xml version="1.0" encoding="UTF-8"?>
<val>
<!-- Define what happens in the case of conflicting styles -->
<style-conflict background-conflict-color="red"/>
<!-- Define two flagging properties that give styles (no image) -->
<prop action="flag" att="audience" style="underline" val="user"
backcolor="green"/>
<prop action="flag" att="platform" style="overline" val="win"
backcolor="blue"/>
<!-- Define a property that includes start and end image flags -->
<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>
<!-- Define a revision that includes start and end image flags -->
<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>
Content example 1: Adding style
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; xtrf and xtrc are left off for
clarity.
<p audience="user">Simple user; includes style but no images</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 outputclass on
ditaval-startprop, 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):
The resulting file after the flagging step looks like this; for clarity, newlines are added, while
xtrf and xtrc are removed:
<p audience="user" class="- topic/p ">
<ditaval-startprop
class="+ topic/foreign ditaot-d/ditaval-startprop "
outputclass="background-color:green;text-decoration:underline;">
<prop action="flag" att="audience" style="underline" val="user"
backcolor="green"/>
</ditaval-startprop>
Simple user; includes style but no images
<ditaval-endprop
class="+ topic/foreign ditaot-d/ditaval-endprop ">
<prop action="flag" att="audience" style="underline" val="user"
backcolor="green"/>
</ditaval-endprop>
</p>
Content example 2: Conflicting styles
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
style-conflict element is evaluated to determine how to style the content.
<p audience="user" platform="win">Conflicting styles (still no images)</p>
The style-conflict element results in a background color of red, so this value is
added to outputclass on ditaval-startprop. As above, active properties
are copied into the generated elements; the style-conflict element itself is also
copied into the generated ditaval-startprop element.
The resulting file after the flagging step looks like this; for clarity, newlines are added, while
xtrf and xtrc are removed:
<p audience="user" platform="win" class="- topic/p ">
<ditaval-startprop
class="+ topic/foreign ditaot-d/ditaval-startprop "
outputclass="background-color:red;">
<style-conflict background-conflict-color="red"/>
<prop action="flag" att="audience" style="underline" val="user"
backcolor="green"/>
<prop action="flag" att="platform" style="overline" val="win"
backcolor="blue"/>
</ditaval-startprop>
Conflicting styles (still no images)
<ditaval-endprop
class="+ topic/foreign ditaot-d/ditaval-endprop ">
<prop action="flag" att="platform" style="overline" val="win"
backcolor="blue"/>
<prop action="flag" att="audience" style="underline" val="user"
backcolor="green"/>
</ditaval-endprop>
</p>
Content example 3: Adding image flags
This example includes image flags for both platform and rev, which are
defined in DITAVAL prop and revprop elements.
<ol platform="linux" rev="rev2">
<li>Generate images for platform="linux" and rev="2"</li>
</ol>
As above, the ditaval-startprop and ditaval-endprop nest the
active property definitions, with the calculated CSS value on outputclass. The
ditaval-startprop drops the ending image, and
ditaval-endprop drops the starting image. To make document-order processing more
consistent, property flags are always included before revisions in ditaval-startprop,
and the order is reversed for ditaval-endprop.
The resulting file after the flagging step looks like this; for clarity, newlines are added, while
xtrf and xtrc are removed:
<ol platform="linux" rev="rev2" class="- topic/ol ">
<ditaval-startprop
class="+ topic/foreign ditaot-d/ditaval-startprop "
outputclass="background-color:blue;
text-decoration:underline;
text-decoration:overline;">
<prop action="flag" att="platform" val="linux" style="overline"
backcolor="blue">
<startflag imageref="startlin.png">
<alt-text>Start linux</alt-text></startflag></prop>
<revprop action="flag" style="double-underline" val="rev2">
<startflag imageref="start_rev.gif">
<alt-text> </alt-text></startflag></revprop>
</ditaval-startprop>
<li class="- topic/li ">
Generate images for platform="linux" and rev="2"
</li>
<ditaval-endprop
class="+ topic/foreign ditaot-d/ditaval-endprop ">
<revprop action="flag" style="double-underline" val="rev2">
<endflag imageref="end_rev.gif">
<alt-text>END</alt-text></endflag></revprop>
<prop action="flag" att="platform" val="linux" style="overline"
backcolor="blue">
<endflag imageref="endlin.png">
<alt-text>End linux</alt-text></endflag></prop>
</ditaval-endprop>
</ol>