Example: Multiple ditavalref elements on a branch

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

Document

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

Version

1.3

Author

OASIS DITA Technical Committee

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

Figure. Contents of win.ditaval

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

Figure. Contents of mac.ditaval

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

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