Conditional processing

Conditional processing is the filtering or flagging of information based on processing-time criteria

DITA tries to implement conditional processing in a semantically meaningful way: rather than allowing arbitrary values to accumulate in a document over time in a general-purpose processing attribute, with meaning only to the original author, we encourage the authoring of metadata using specific metadata attributes on content. These metadata values can then be leveraged by any number of processes, including filtering, flagging, search, and indexing, rather than being suitable for filtering only.

There are four attributes intended for conditional processing, available on most elements:

product: the product that is the subject of the discussion.
platform: the platform on which the product is deployed.
audience: the intended audience of the text
rev: the revision or draft number of the current document (typically used for flagging only, not for filtering)
otherprops: anything else

Using metadata attributes

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.

Figure 1. Example source

<p audience="administrator">Set the configuration options:
 <ul>
  <li product="extendedprod">Set foo to bar</li>
  <li product="basicprod extendedprod">Set your blink rate</li>
  <li>Do some other stuff</li>
  <li platform="Linux">Do a special thing for Linux</li>
 </ul>
</p>

Processing metadata attributes

At processing time, you specify the values you want to exclude and the values you want to flag. For example, a publisher producing information for a mixed audience using the basic product could choose to flag information that applies to administrators, and exclude information that applies to the extended product:

<prop att="audience" val="administrator" action="flag" use="ADMIN"/>
<prop att="product"  val="extendedprod"  action="exclude"/>

The format shown here for identifying values for filtering and flagging is not normative, and is shown purely for the sake of illustrating the expected processing logic.

At output time, the paragraph is flagged, and the first list item is excluded (since it applies to extendedprod), but the second list item is still included (even though it does apply to extendedprod, it also applies to basicprod, which was not excluded).

The result should look something like:

ADMIN Set the configuration options:

Set your blink rate
Do some other stuff
Do a special thing for Linux

Filtering logic

When deciding whether to exclude a particular element, a process should evaluate each attribute, and then evaluate the set of attributes:

If all the values in an attribute have been set to "exclude", the attribute evaluates to "exclude"
If any of the attributes evaluate to exclude, the element is excluded.

For example, if a paragraph applies to three products and the publisher has chosen to exclude all of them, the process should exclude the paragraph; even if the paragraph applies to an audience or platform that you aren't excluding. But if the paragraph applies to an additional product that has not been excluded, then its content is still relevant for the intended output and should be preserved.

Flagging logic

When deciding whether to flag a particular element, a process should evaluate each value. Wherever a value that has been set as flagged appears in its attribute (for example, audience="ADMIN") the process should add the flag. When multiple flags apply to a single element, multiple flags should be output, typically in the order they are encountered.

Flagging could be done using text (for example, bold text against a colored background) or using images. When the same element evaluates as both flagged and filtered (for example, flagged because of an audience attribute value and filtered because of its product attribute values), the element should be filtered.