Example: Multiple <ditavalref> elements on a branch

Multiple <ditavalref> elements can be used on a single map branch to create multiple distinct copies of the branch.

Consider the following DITA map that contains a branch with three peer <ditavalref> elements. Because topics in the branch are filtered in three different ways, processors are effectively required to handle three copies of the entire branch. Sub-elements within the <ditavalref> elements are used to control how new resource names are constructed for two copies of the branch; one copy (based on the conditions in win.ditaval) is left with the original file names.

Figure 1. input.ditamap
<map>
  <topicref href="intro.dita"/>
  <!-- Begining of installing branch -->
  <topicref href="install.dita">
    <ditavalref href="win.ditaval"/>
    <ditavalref href="mac.ditaval">
      <ditavalmeta>
        <dvrResourceSuffix>-apple</dvrResourceSuffix>
      </ditavalmeta>
    </ditavalref>
    <ditavalref href="linux.ditaval">
      <ditavalmeta>
        <dvrResourceSuffix>-linux</dvrResourceSuffix>
      </ditavalmeta>
    </ditavalref>
    <topicref href="do-stuff.dita">
    <!-- more topics and nested branches -->
      <topicref href="mac-specific-stuff.dita" platform="mac"/>
    </topicref>
    <!-- End of installing branch -->
    <topicref href="cleanup.dita"/>
  </topicref>
</map>
Figure 2. Contents of win.ditaval
<val>
  <prop att="platform" val="win" action="include"/>
  <prop att="platform" action="exclude"/>
</val>
Figure 3. Contents of mac.ditaval
<val>
  <prop att="platform" val="mac" action="include"/>
  <prop att="platform" action="exclude"/>
</val>
Figure 4. Contents of linux.ditaval
<val>
  <prop att="platform" val="linux" action="include"/>
  <prop att="platform" action="exclude"/>
</val>
When a processor evaluates this markup, it results in three copies of the installing branch. The following processing takes place:
  • The first topic (intro.dita) is published normally, potentially using any other DITAVAL conditions that are specified externally.
  • The installing branch appears three times, once for each DITAVAL document. The branches are created as follows:
    • The first branch uses the first DITAVAL document (win.ditaval). Resources use their original names as specified in the map. The mac-specific-stuff.dita topic is removed. The resulting branch, with indenting to show the hierarchy, matches the original without the mac topic: 
      install.dita
   do-stuff.dita
     ...more topics and nested branches...
   cleanup.dita
    • The second branch uses the second DITAVAL document (mac.ditaval). Resources are renamed based on the <dvrResourceSuffix> element. The mac-specific-stuff.dita topic is included. The resulting branch, with indenting to show the hierarchy, is as follows: 
      install-apple.dita
   do-stuff-apple.dita
      mac-specific-stuff-apple.dita
      ...more topics and nested branches...
   cleanup-apple.dita
    • The third branch uses the last DITAVAL document (linux.ditaval). Resources are renamed based on the <dvrResourceSuffix> element. The mac-specific-stuff.dita topic is removed. The resulting branch, with indenting to show the hierarchy, is as follows: 
      install-linux.dita
   do-stuff-linux.dita
     ...more topics and nested branches...
   cleanup-linux.dita

The example used three DITAVAL documents to avoid triple maintenance of the installing branch in a map; the following map is functionally equivalent, but it requires parallel maintenance of each branch.

Figure 5. input.ditamap
<map>
  <topicref href="intro.dita"/>
  <!-- Windows installing branch -->
  <topicref href="install.dita">
    <ditavalref href="win.ditaval"/>
    <topicref href="do-stuff.dita">
      <!-- more topics and nested branches -->
    </topicref>
    <topicref href="cleanup.dita"/>
  </topicref>
  <!-- Mac installing branch -->
  <topicref href="install.dita">
    <ditavalref href="mac.ditaval">
      <ditavalmeta><dvrResourceSuffix>-apple</dvrResourceSuffix></ditavalmeta>
    </ditavalref>
    <topicref href="do-stuff.dita">
      <topicref href="mac-specific-stuff.dita" platform="mac"/>
      <!-- more topics and nested branches -->
    </topicref>
    <topicref href="cleanup.dita"/>
  </topicref>
  <!-- Linux installing branch -->
  <topicref href="install.dita">
    <ditavalref href="linux.ditaval">
      <ditavalmeta><dvrResourceSuffix>-linux</dvrResourceSuffix></ditavalmeta>
    </ditavalref>
    <topicref href="do-stuff.dita">
      <!-- more topics and nested branches -->
    </topicref>
    <topicref href="cleanup.dita"/>
  </topicref>
  <!-- Several chapters worth of other material -->
</map>