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 24. 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 25. Contents of win.ditaval
Figure 26. Contents of mac.ditaval
Figure 27. Contents of linux.ditaval
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 28. 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>
Parent topic