2.1.3.6 Conditional processing (profiling)

Conditional processing attributes

For a topic or topicref, the audience, platform, and product metadata can be expressed with attributes on the topic or topicref element or with elements within the topic prolog or topicmeta element. While the metadata elements are more expressive, the meaning of the values is the same, and can be used in coordination. For example, the prolog elements can fully define the audiences for a topic, and then metadata attributes can be used within the content to identify parts that apply to only some of those audiences.

audience

The values in the audience attribute may also be used to reference a more complete description of an audience in an audience element. Use the name of the audience in the audience element when referring to the same audience in an audience attribute.

The audience attribute takes a space-delimited list of values, which may or may not match the name value of any audience elements.

platform

The platform might be the operating system, hardware, or other environment. This attribute is equivalent to the platform element for the topic metadata.

The platform attribute takes a space-delimited list of values, which may or may not match the content of a platform element in the prolog.

product

The product or component name, version, brand, or internal code or number. This attribute is equivalent to the prodinfo element for the topic metadata.

The product attribute takes a space-delimited list of values, which may or may not match the value of the prodname element in the prolog.

rev

The identifier for the revision level. For example, if a paragraph was changed or added during revision 1.1, the rev attribute might contain the value "1.1".

otherprops

A catch-all for metadata qualification values about the content. This attribute is equivalent to the othermeta element for the topic metadata.

The attribute takes a space-delimited list of values, which may or may not match the values of othermeta elements in the prolog.

For example, a simple otherprops value list: <codeblock otherprops="java cpp">

The attribute may take labeled groups of values as for @props. Processors may treat such values as equivalent to @props or they may treat such values as simple strings. The use of labeled groups in @otherprops is deprecated in favor of using specializations of @props. Processors should clearly document how they treat grouped @otherprops values. See Attribute generalization for details on generalized @props attribute values.

props

A generic attribute for conditional processing values. Starting with DITA 1.1, the props attribute can be specialized to create new conditional processing attributes. See Attribute generalization.

Using conditional processing 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.

<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>
            

Evaluating conditional processing attributes

At processing time, a DITAVAL conditional processing profile may be used to specify values you want to include, exclude, or flag.

<val>
  <prop att="audience" val="administrator" action="flag">
    <startflag><alt-text>ADMIN</alt-text></startflag>
  </prop>
  <prop att="product" val="extendedprod" action="exclude"/>
</val>

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).

Filtering logic

By default, values in conditional processing attributes that are not defined in a DITAVAL profile evaluate to "include". For example, if the value audience="novice" is used on a paragraph, but this value is not defined in a DITAVAL profile, the attribute evaluates to "include". However, the DITAVAL profile may change this default to "exclude", so that any value not explicitly defined in the DITAVAL profile will evaluate to "exclude". The profile may also be used to change the default for a single attribute; for example, it may declare that values in the platform attribute default to exclude while those in the product attribute default to include. See DITAVAL elements for information on how to set up a DITAVAL profile and how to change default behaviors.

For example, if a paragraph applies to three products and the publisher has chosen to exclude all of them, the processor should exclude the paragraph. This is true even if the paragraph applies to an audience or platform that is not excluded. 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 processor should evaluate each value. Wherever a value that has been set as flagged appears in its attribute (for example, audience="administrator") the process should add the flag. When multiple flags apply to a single element, multiple flags should be rendered, 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.