Back to Search Back to Search Results

Conditional Processing (Profiling)

Titania Delivery supports conditional processing using DITAVAL files.

DITAVAL files, specified by the DITA standard, are XML documents describing filtering rules to be applied to a document during processing. Titania Delivery uses DITAVAL files for both DITA and non-DITA documents. In order for a given document to be filtered using the rules in a DITAVAL file, that DITAVAL file must be associated with the document. This can be done in one of three ways.

  1. Specify the location of the DITAVAL file using the metadata key _td.ditaval. The value can either be an absolute path from the root of the project, or a relative path from the location of the file. This is the only way to specify the filtering to use for documents which are not DITA maps.
    Note: After modifying _td.ditaval, the content must be re-processed for the filtering to be applied.
  2. In a DITA map, you can use the DITA 1.3 <ditavalref> element with the other elements in the DITAVAL Reference Domain to associate DITAVAL files with all or part of a map. As described by the DITA 1.3 specification, if more than one <ditavalref> element is present for a section of a map, that section will be replicated and individually filtered for each reference.
  3. Inside any <topicmeta> element, you can specify one or more <data> elements with name="ditavalref" and whose @href attribute identifies a DITAVAL file to apply to the map or topicref. This allows you to associate DITAVAL files with DITA maps authored using a version of the standard prior to DITA 1.3.
    Note: Unlike the <ditavalref> element, multiple <data name="ditavalref"> references in the same <topicmeta> element will be combined into a single rule set; branch replication does not occur.
Note: If you need to profile a document multiple ways, then you must upload it to Titania Delivery multiple times with distinct file names, and associate the appropriate DITAVAL files with each instance of the file.

Ad-Hoc Profiling

It is possible to configure profiling without a DITAVAL file using the special metadata field _td.profiles. The value for this is a string describing the profiling rules. Just as with DITAVAL rules, if specified on a DITA map, it will be applied to all content referenced by that map. If both _td.profiles and _td.ditaval are specified, _td.profiles value takes precedence.

The value may contain multiple rules, separated by whitespace and/or semicolons (;). Each rule is of the form:

ACTION $attribute $operator $value
ACTION
The action to perform. Either INCLUDE or EXCLUDE.
$attribute
The attribute to which the rule applies. May be an asterisk (*) to apply to all attributes.
$operator
The operator to apply. There are four possible operators.
=
Equality. The attribute value must match at least one of the specified values.
!=
Inequality. The attribute value must not match any of the specified values.
~=
Contains Word. The attribute must contain at least one of the words specified in the value. (DITAVAL <prop> elements specify this kind of rule.)
!~=
Does Not Contain Word. The attribute must not contain any of the words specified in the value.
$value
The value or values to test the specified $attribute against using $operator. Values are specified literally, without any quotation marks (" or '). Multiple values can be specified, delimited by vertical bars (|). An asterisk may be specified (*) for all values.

Here are some example rules:

# Exclude elements whose product attribute contains either Product1 or Product2.
EXCLUDE product ~= Product1 | Product2

# Include elements marked with product only if they specify Product1 exactly.
INCLUDE product = Product1
EXCLUDE product = *

# Alternative formulation of the above.
EXCLUDE product != Product1

These rules follow DITAVAL rules for resolution. Specifically:

  • If the evaluation of all rules for a given attribute on a given element resolves to an EXCLUDE action, the element will be excluded. If any rule for an attribute evaluates to INCLUDE, it will be included.
  • For attributes that only have Includes-Word rules (~=), the attribute will resolve as EXCLUDE if and only if all of its words explicitly resolve to EXCLUDE. If a word in an attribute does not have any rules associated with it, the attribute resolves as INCLUDE.

Generally, rules should use the ~= or !~= operators. Matching on exact values is rare. For example: 

EXCLUDE audience = secret | top-secret
This will exclude only if the @audience attribute exactly equals "secret" or "top-secret". It would not exclude an element whose @audience contains both. For instance: 
<ph audience="secret top-secret">
would be INCLUDED because the value does not exactly match. Rather than using the strict-equality operator, you could use the contains-word operator: 
EXCLUDE audience ~= secret | top-secret
This is equivalent to the following DITAVAL rules: 
<prop action="exclude" att="audience" val="secret"/>
<prop action="exclude" att="audience" val="top-secret"/>

Related information:

Conditional Processing (Profiling)
DITAVAL Elements
Parent topic: Projects