Example: Multiple <ditavalref> elements on a 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.

<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">
      <topicref href="mac-specific-stuff.dita" platform="mac"/>
    </topicref>
    <!-- End of installing branch -->
    <topicref href="cleanup.dita"/>
  </topicref>
</map>

<val>
  <prop att="platform" val="win" action="include"/>
  <prop att="platform" action="exclude"/>
</val>

<val>
  <prop att="platform" val="mac" action="include"/>
  <prop att="platform" action="exclude"/>
</val>

<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.

<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>