Example: Multiple <ditavalref> elements as children of <map> in a root map

Using multiple instances of the <ditavalref> element as direct children of the <map> element in a root map is equivalent to setting multiple sets of global filtering conditions for the root map.

Example

Note: Unlike most other examples of branch filtering, this example cannot be rewritten using a single valid map with alternate markup that avoids having multiple <ditavalref> elements as children of the same grouping element.

Processing the following root map is equivalent to processing all the contents of the map with the conditions in the mac.ditaval file and again with the linux.ditaval file. If additional conditions are provided externally (for example, as a parameter to the publishing process), those global conditions take precedence.

Figure 1. input.ditamap
<map>
  <title>Setting up my product 
on <keyword platform="mac">Mac</keyword><keyword platform="linux">Linux</keyword></title>
  <topicmeta>
    <othermeta platform="mac"   name="ProductID" content="1234M"/>
    <othermeta platform="linux" name="ProductID" content="1234L"/>
  </topicmeta>
  <ditavalref href="mac.ditaval"/>
  <ditavalref href="linux.ditaval"/>
  <!-- lots of content, including relationship tables -->
</map>
Figure 2. Contents of mac.ditaval
<val>
  <prop att="platform" val="mac"   action="include"/>
  <prop att="platform" val="linux" action="exclude"/>
</val>
Figure 3. Contents of linux.ditaval
<val>
  <prop att="platform" val="mac"   action="exclude"/>
  <prop att="platform" val="linux" action="include"/>
</val>

Because the title and metadata each contain filterable content, processing using the conditions that are referenced by the <ditavalref> element results in two variants of the title and common metadata. While this cannot be expressed using valid DITA markup, it is conceptually similar to something like the following.

<!-- The following wrapperElement is not a real DITA element.
     It is used here purely as an example to illustrate one possible 
     way of picturing the conditions. -->
<wrapperElement>
  <map>
    <title>Setting up my product on <keyword platform="mac">Mac</keyword></title>
    <topicmeta>
      <othermeta platform="mac"   name="ProductID" content="1234M"/>
    </topicmeta>
    <ditavalref href="mac.ditaval"/>
    <!-- lots of content, including relationship tables -->
  </map>
  <map>
    <title>Setting up my product on <keyword platform="linux">Linux</keyword></title>
    <topicmeta>
      <othermeta platform="linux" name="ProductID" content="1234L"/>
    </topicmeta>
    <ditavalref href="linux.ditaval"/>
    <!-- lots of content, including relationship tables -->
  </map>
</wrapperElement>

How this map is rendered is implementation dependent. If this root map is rendered as a PDF, possible renditions might include the following:

  • Two PDFs, with one using the conditions from mac.ditaval and another using the conditions from linux.ditaval
  • One PDF, with a title page that includes each filtered variant of the title and product ID, followed by Mac-specific and Linux-specific renderings of the content as chapters in the PDF
  • One PDF, with the first set of filter conditions used to set book level titles and metadata, followed by content filtered with those conditions, followed by content filtered with conditions from the remaining <ditavalref> element.