In addition to filtering, you can use conditional attributes to flag (or highlight) content that is intended for different readers or different products. You can use any conditional attribute for flagging, and you can use the rev attribute to indicate and flag a specific revision of your product or service.
Note: The DITA sources shown in the following examples are in the downloadable samples file reuse_advanced_samples.zip. The DITA file is c_filtering_and_flagging.dita; the ditaval files are wild.ditaval and show_rev.ditaval.
Flagging the conditional attributes
To use the conditional attributes for flagging, use the ditaval <prop> element with the action=”flag” attribute. This allows you to flag text with color, background color, text styles, and images (depending on what is supported in your transforms and the output generator). For example:
<prop att="platform" val="android" action="flag" color="purple"/>
The <prop> element show here directs the output generator to use purple text on any element in which the platform attribute contains the value “android”.
When flagging, you can use these <prop> attributes to flag text:
- color: style the text using the specified color
- background: place the specified color behind the text
- style: format the text using a specific style (italics, bold, underline, double-underline, or overline).
The color and background attributes can use either a 6-digit hex color code (such as “#0000FF”) or a color name (aqua, black, blue, fuchsia, gray, green, lime, maroon, navy, olive, purple, red, silver, teal, white, or yellow).
For example, if you use this example (from the previous topic):
<p>For the healthiest ducks, we recommend using our feeds.</p> <p>All our duck feeds are composed of cracked corn, oats, rice, and milo seed. <ph product="wild_ducks">Our wild duck feed also includes worm meal and fish meal. </ph> </p> <p>All feeds are available in 5, 10, and 20 pound sacks.</p>
With this ditaval file:
<val>
<prop action="flag" att="product" val="wild_ducks" color="red" style="underline"/>
</val>
The output looks like this:
You can also specify images to place before and after the flagged element. Use the <startflag> and <endflag> elements as children of a <prop action=”flag”> element. The imageref attribute indicates the path to the image to use.
<prop att="platform" val="android" action="flag">
<startflag imageref="images/android_icon.png">
<alt-text>Android icon</alt-text>
</startflag>
</prop>
The <startflag> and <endflag> elements can optionally contain an <alt-text> element that contains alternate text for the image.
The rev attribute
You use the rev attribute to indicate and flag a specific revision of your product or service. The rev attribute is available on almost all DITA elements. You use it just as you would a conditional attribute:
<p rev="v2.1">If you have additional needs, consider using the custom table feature. </p>
The values you use with the rev attribute are up to you and your organization. The important thing is to be consistent in how you use the values.
As with the conditional attributes you can specify multiple revision values in the rev attribute; separate the values with one or more spaces.
<p rev="v2.7 v2.8">The field is limited to 32 characters.</p>
Note: It is important to note that you cannot use the rev attribute for filtering content. Its only purpose is for flagging.
Showing rev flagging in output
You control the display of the rev attribute with the <revprop> element in the ditaval file. You can apply styling just as with the <prop> element (using the color, background color, and style attributes). You can also use the <startflag> and <endflag> elements to add images before and after the element marked with the rev attribute.
For example, if a DITA topic contains this content:
<p>The Duck Database tables will handle most of your duck needs.</p> <p rev="2.1">If you have additional needs, consider using the custom table feature.</p> <p>For more information on the standard tables, see Appendix C.</p>
And you generate output using a ditaval file containing:
<val>
<revprop action="flag" val="2.1" backcolor="aqua"/>
</val>
The output might look like this:
Depending on the format of your output and your output generator, you can also use the <revprop> element to place change bars in the margins next to text marked with a rev attribute. However, the capabilities and the syntax of the changebar attribute vary depending on the output format and the output generator. If you need to use this feature, it is best to review the documentation for your output generator.
For more information about ditaval files and how to use them for flagging, see http://docs.oasis-open.org/dita/v1.2/os/spec/common/about-ditaval.html#ditaval