Glossary · Conditional processing

DITA branch filtering

Also known as: branch filtering, ditavalref, DITAVAL reference

In DITA 1.3, branch filtering is the application of conditional processing rules to one branch of a map, declared with a <ditavalref> element that references a DITAVAL file. A branch with several DITAVAL references is processed once per reference, producing several filtered copies.

DITA
Conditional processing
New in DITA 1.3

In one sentence

DITA 1.3 branch filtering applies DITAVAL conditions to one branch of a map with <ditavalref>, and can publish filtered copies side by side.

Example

The installation chapter is referenced once with two DITAVAL references, producing installation-linux and installation-windows in the same guide.

How it applies

Technical documentation: Before DITA 1.3, one DITAVAL file applied to the whole publication. With branch filtering, one map can contain the same branch several times with different filters — for example the installation chapter once for Linux and once for Windows.
How it works: A <ditavalref href="linux.ditaval"/> inside a topicref applies the conditions to that branch. Several sibling <ditavalref> elements produce one copy of the branch per DITAVAL file.
Naming the copies: Because each copy is a separate result, <ditavalmeta> can rename them with <dvrResourcePrefix> or <dvrResourceSuffix> (for file names) and <dvrKeyscopePrefix> or <dvrKeyscopeSuffix> (for key scopes), so links can address each copy.
AI and retrieval: Branch filtering multiplies resolved versions of the same topic. Treat each filtered copy as its own chunk with its own metadata, rather than indexing the unfiltered source.

Branch filtering vs. global filtering

A global DITAVAL file is passed to the publishing process and applies everywhere. Branch filtering is recorded in the map and applies only to the branch, on top of any global conditions.

In DITA markup

<topicref href="installation.dita">
  <ditavalref href="linux.ditaval">
    <ditavalmeta><dvrResourceSuffix>-linux</dvrResourceSuffix></ditavalmeta>
  </ditavalref>
  <ditavalref href="windows.ditaval">
    <ditavalmeta><dvrResourceSuffix>-windows</dvrResourceSuffix></ditavalmeta>
  </ditavalref>
</topicref>