Example: Single ditavalref on a branch

Darwin Information Typing Architecture (DITA) Version 1.3 Part 1: Base Edition

version
1.3
author
OASIS DITA Technical Committee

A single ditavalref element can be used to supply filtering conditions for a branch.

Consider the following DITA map and the DITAVAL file that is referenced from the ditavalref element:

Figure. input.ditamap:
<map>
  <topicref href="intro.dita"/>
  <topicref href="install.dita">
    <ditavalref href="novice.ditaval"/>
    <topicref href="do-stuff.dita"/>
    <topicref href="advanced-stuff.dita" audience="admin"/>
    <!-- more topics -->
  </topicref>
  <!-- Several chapters worth of other material -->
</map>
Figure. Contents of novice.ditaval
<val>
  <prop att="audience" val="novice" action="include"/>
  <prop att="audience" val="admin" action="exclude"/>
</val>

When this content is published, the following processing occurs:

  • The first topic (intro.dita) does not use any of the conditions that are specified in novice.ditaval. It is published normally, potentially using other DITAVAL conditions that are specified externally.
  • The second topic (install.dita) is filtered using any external conditions as well as the conditions that are specified in novice.ditaval.
  • The third topic (do-stuff.dita) is filtered using any external conditions as well as the conditions that are specified in novice.ditaval.
  • The fourth topic (advanced-stuff.dita) is removed from the map entirely, because it is filtered out with the conditions that are specified for the branch.

In this example, no resources are renamed based on the ditavalref processing.

Note: In cases where the original resource names map directly to names or anchors in a deliverable, the absence of renaming ensures that external links to those topics are stable regardless of whether a DITAVAL document is used.