Filtering

At processing time, a conditional processing profile can be used to specify profiling attribute values that determine whether an element with those values is included or excluded.

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 can change this default to "exclude", so that any value not explicitly defined in the DITAVAL profile will evaluate to "exclude". The DITAVAL profile also can be used to change the default for a single attribute; for example, it can 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.

When deciding whether to include or exclude a particular element, a processor should evaluate each attribute independently:

  1. For each attribute:
    • If the attribute is empty, or contains only empty groups, it is equivalent to omitting the attribute from the element. If evaluated for the purposes of filtering, the attribute is treated as "include", because an omitted attribute cannot evaluate to "exclude".
    • If the attribute value does not contain any groups, then if any token in the attribute value evaluates to "include", the element evaluates to "include"; otherwise it evaluates to "exclude". In other words, the attribute evaluates to "exclude" only when all the values in that attribute evaluate to "exclude".
    • If the attribute value does include groups, evaluate as follows, treating ungrouped tokens together as a group:
      1. For each group (including the group of ungrouped tokens), if any token inside the group evaluates to "include", the group evaluates to "include"; otherwise it evaluates to "exclude". In other words, a group evaluates to "exclude" only when every token in that group evaluates to "exclude".
      2. If any group within an attribute evaluates to "exclude", that attribute evaluates to "exclude"; otherwise it evaluates to "include".
  2. If any single attribute evaluates 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 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.

Similarly, with groups, a step might apply to one application server and two database applications: 
<steps>
  <step><cmd>Common step</cmd></step>
  <step product="appserver(mySERVER) database(ABC dbOtherName)">
    <cmd>Do something special for databases ABC or OtherName when installing on mySERVER</cmd>
  </step>
  <!-- additional steps -->
</steps>

If a publisher decides to exclude the application server mySERVER, then the appserver() group evaluates to exclude. This can be done by setting product="mySERVER" to exclude or by setting appserver="mySERVER" to exclude. This means the step should be excluded, regardless of how the values "ABC" or "dbOtherName" evaluate. If a rule is specified for both product="mySERVER" and appserver="mySERVER", the rule for the more specific group name "appserver" takes precedence.

Similarly, if both "ABC" and "dbOtherName" evaluate to exclude, then the database() group evaluates to exclude and the element should be excluded regardless of how the "mySERVER" value is set.

In more advanced usage, a DITAVAL can be used to specify a rule for a group name. For example, an author could create a DITAVAL rule that sets product="database" to "exclude". This is equivalent to setting a default of "exclude" for any individual value in a database() group; it also excludes the more common usage of "database" as a single value within the @product attribute. Thus when "myDB" appears in a database() group within the @product attribute, the full precedence for determining whether to include or exclude the value is as follows:
  1. Check for a DITAVAL rule for database="myDB"
  2. Check for a DITAVAL rule for product="myDB"
  3. Check for a DITAVAL rule for product="database" (default for the database group)
  4. Check for a DITAVAL rule for "product" (default for the @product attribute)
  5. Check for a default rule for all conditions (default of include or exclude for all attributes)
  6. Otherwise, evaluate to "include"