Conditional text allows you to set up a document so that some content can be shown or hidden, or flagged (perhaps with an icon), allowing you to print multiple documents from a single set of content. For example, to produce different flavors of documentation for different operating systems (e.g., Windows, Mac, Unix), for different audiences (Internal, Customer), or for different products or versions of a product.
The purpose of conditions is to allow you to produce multiple documents from a single set of content. To use conditions, you mark your text with an attribute. Then, when you want to print the content you specify which content marked is to be excluded or flagged.
The savings from using conditional text in terms of writing, comparing, and editing can be significant. However, conditions should be used wisely because excessive complexity can be difficult to manage and difficult for writers new to the content to become familiar with.
DITA tries to implement conditional processing in a meaningful way. Instead of using arbitrary in a document, which only have meaning to the original author, DITA has specific attributes that can then be used for filtering, flagging, search, and indexing.
All the select attributes (%select-attr), available on most elements, can be used for conditional processing, for example:
product Name of the product being documented
platform Platform (e.g., Unix, Windows) on which
the product is deployed.
audience Intended audience of the topic
rev Revision or draft number of the current
document
importance Importance or priority of an element.
otherprops Anything else
Each attribute takes zero or more space-delimited string values. For example, you can use the product attribute to identify that an element applies to two particular products:
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN"
"dtd/topic.dtd">
<topic id="conditionaltext">
<title>Conditional Text Example</title>
<body>
<p audience=”customer”>Product accessories:
<ul>
<li product="product1">accessory1</li>
<li product="product2 product1">accessory2</li>
</ul>
</p>
</body>
</topic>
You specify the values you want to exclude and the values you want to flag in a .ditaval file, which contains the processing directives that handle exclusion and flagging. For example, if I want exclude content that applies to product1. My .ditaval file would look like:
<val><prop att="product" val="product1"
action="exclude" /></val>
At processing time the first list item is excluded (filtered) from the output because it applies to product1 only. The second list item will not be excluded because even though it applies to product1, it also applies to product2, which was not excluded in the .ditaval file. However, we also specified an audience attribute of customer on the enclosing <p> element, which was not excluded in the .ditaval file but the first list item was still excluded.
To understand why this is, it helps to understand the filtering rule, which is: "If any one attribute (product, platform, audience, rev, or otherprops) has all values set to exclude then exclude the element."
In the example, only one value (product1) was specified for the product attribute of the first list item, so it conforms to the filtering rule and is excluded.
To actually process, the conditional text, you must process the DITA files with the /filter parameter, for example:
java -jar lib\dost.jar /i: source/test.xml
/outdir:out
/transtype:xhtml
/filter:c:/dita/source/myfilter.ditaval
Flagging content
Flagging works in the same way as exclusion, except that if all values of an attribute are set to flag DITA adds an extra flagging element (a text string or an image) to the output, instead of removing the element.
Probably the simplest way to flag would be to output the flagging text in an <em> tag in HTML, with a class setting “flag” that you can use CSS to style as white, in small caps with a purple background. For example,
<em class=”flag”>ADMIN</em> Set the
configuration options:
<ul>
<li><em class=”flag”>BP </em>Set foo to bar</li>
<li><em class=”flag”>BP </em><em class=”flag”>EP </em>
Set your link rate</li>
<li>Do some other stuff</li>
<li><em class=”flag”>WINDOWS </em>Do a
special thing for Windows</li>
</ul>
0 comments:
Post a Comment