Table of Contents
Starting with this release, you will be able to associate one or more DITAVAL files with some or all of a map. This allows a great deal of flexibility. If a map should always be published with a given set of rules, you can associate those rules directly with the map without having to specify them every time the map is published. You can also specify different profiling settings for different sections in the same map.
To associate a DITAVAL file with a map, reference it via a data element
within topicmeta with a name attribute of
ditavalref and an href attribute referencing the DITAVAL
file.
<data name="ditavalref" href="" />
When resolving references to DITAVAL files, the ditapath setting will be consulted.
The portion of the map affected by a DITAVAL file referenced in this way is contained by the parent topicref of such a reference, including the topicref itself. More specifically, it applies to:
-
The parent topicref of the DITAVAL reference.
-
The topic or map, if any, referenced by that topicref.
-
All markup, including
topicmetacontents andtopicrefelements, occurring within the map branch encapsulated by the parent topicref, except for other DITAVAL references. -
Any topics or maps referenced via
topicrefwithin the branch encapsulated by the parent element of the DITAVAL reference, except where thetopicrefthat references the file is excluded by the effective DITAVAL rules.
So to affect an entire map, place the reference within topicmeta within
the root-level map element. To have the rules apply only for part of the map,
place the reference within the topicmeta of a topicref (or
specialization thereof) containing the region of the map structure to which the rules should
apply.
| Note | |
|---|---|
|
This design was discussed at the DITA Technical Committee meeting on November 29, 2011 and met with provisional approval. The minutes for this meeting can be found at http://www.oasis-open.org/apps/org/workgroup/dita/download.php/44501/latest/minutes20111129.txt. One of the things that will likely be part of the DITA 1.3 proposal is the ability to duplicate a section of a map (or 'branch' in DITA terminology), once for each DITAVAL file associated with that branch. We will not be supporting this use-case in this release. We will treat the DITAVAL associations as additive, and apply all files to the specified region. We expect the markup for the branch duplication use-case to be different from what we're using. |
DITAVAL associations are additive. If two DITAVAL files are referenced at the same level in the map, both sets of rules apply at that level. If the two files contain rules for the same attribute-value pair, the rules from the first file in document order take precedence. Similarly, if a parent scope and a child scope both reference DITAVAL files, the effective rule set for the inner scope will be the combination of the rules in the two files. Where there are rules for matching attribute-value pairs for both the parent and the child scope, the rules from the parent scope overrule those in the child scope. This allows top-level map authors to override the DITAVAL rules specified in child maps.
Any DITAVAL specified via the composition UI for the whole map is considered to have "global" scope. Normal additivity rules apply for DITAVAL references within the map, with the global DITAVAL file being considered the top-level rule set.
Note that traditional Arbortext profiling occurs in addition to DITAVAL processing. Since DITAVAL processing is part of the DITA preprocessing done before standard publishing, DITAVAL filtering occurs before profiling is applied.
Note that the data element supports the keyref
attribute. When specified, the keyref will be resolved the same as any
other reference. So, for example, you could specify this DITAVAL association in your
map:
<data name="ditavalref" keyref="productDitaval" />
And define the "productDitaval" key just like any other key definition, elsewhere in the map.
<keydef keys="productDitaval" format="ditaval" href="" />
Note that DITAVAL references can, themselves, be marked for conditional processing. DITAVAL references can not be filtered by rules from other DITAVAL references. They can only be filtered from the rules passed in via composition parameters. This is because the act of finding DITAVAL references must happen before DITAVAL filtering from those references can occur.
For example, consider this:
<topicref href="">
<topicmeta>
<data name="ditavalref" href="" product="ProjectY" />
</topicmeta>
</topicref>
This says, essentially, "When publishing for Project Y, flag expert regions in red."
However, the filtering of this DITAVAL reference based on @product will
only occur based on rules from the DITAVAL passed in to the composition operation. If a higher
scope references a DITAVAL file that would exclude product="ProjectY", that
filtering will be ignored. So this has no effect:
<map>
<title>Map Title</title>
<topicmeta>
<data name="ditavalref" href="" />
</topicmeta>
<topicref href="">
<topicmeta>
<!-- This will not be filtered out
because one ditaval reference cannot
remove others -->
<data name="ditavalref"
href=""
product="ProjectY" />
</topicmeta>
</topicref>
</map>
Example 1.1. Appling a DITAVAL File to an Entire Map
You can specify DITAVAL rules for a whole map structure by referencing it from
topicmeta within the top-level map element.
<map xml:lang="en">
<!-- the <ph> tags will be filtered using the rules in expert.ditaval -->
<title>
<ph audience="Expert">Expert</ph>
<ph audience="Novice">Novice</ph>
Instructions
</title>
<topicmeta>
<data name="ditavalref" href="" />
</topicmeta>
<!-- All topics will be filtered via 'expert.ditaval' -->
<topicref href="" />
<topicref href="" />
</map>
Example 1.2. Profiling the Same TOC with Different Rules
You can use DITAVAL association to have the same set of topics filtered differently by wrapping them in different "wrapper" maps with different DITAVAL associations.
<map xml:lang="en">
<title>Expert Instructions</title>
<topicmeta>
<data name="ditavalref" href="" />
</topicmeta>
<mapref href="" />
</map>
<map xml:lang="en">
<title>Novice Instructions</title>
<topicmeta>
<data name="ditavalref" href="" />
</topicmeta>
<mapref href="" />
</map>
Example 1.3. Different DITAVAL Rules for Different Sections of a Map
You can use different DITAVAL rules at different locations in the same map structure. In
the example below, content affected by teacher.ditaval will be
highlighted in green, and content affected by student.ditaval will be
highlighted in orange.
<map xml:lang="en">
<title>Teacher's Guide</title>
<!-- Section One -->
<topichead navtitle="Section One (Teacher)">
<topicmeta>
<data name="ditavalref" href="" />
</topicmeta>
<topicref href=""/>
</topichead>
<topichead navtitle="Section One (Student)">
<topicmeta>
<data name="ditavalref" href="" />
</topicmeta>
<topicref href=""/>
</topichead>
<!-- Section Two -->
<topichead navtitle="Section Two (Teacher)">
<topicmeta>
<data name="ditavalref" href="" />
</topicmeta>
<topicref href=""/>
</topichead>
<topichead navtitle="Section Two (Student)">
<topicmeta>
<data name="ditavalref" href="" />
</topicmeta>
<topicref href=""/>
</topichead>
</map>
Example 1.4. DITAVAL Rule Additivity
Let's say you had two DITAVAL files.
-
ProjectX.ditaval:<val> <prop att="product" val="ProjectX" action="" /> <prop att="otherprops" val="Green" action="" color="green" /> </val>
-
ProjectY.ditaval:<val> <prop att="product" val="ProjectX" action="" /> <prop att="product" val="ProjectY" action="" /> <prop att="otherprops" val="Red" action="" color="red" /> </val>
When these two DITAVAL files are referenced from nested topicrefs in a map, the effect
for the inner scope will be the same as if you took the prop elements
from the 'inner' scope and appended them to the DITAVAL file from the 'outer' scope.
<map>
<topicref href="">
<topicmeta>
<data name="ditavalref" href="" />
</topicmeta>
<topicref href="">
<topicmeta>
<data name="ditavalref" href="" />
</topicmeta>
</topicref>
</topicref>
</map>
In this example, only the rules in ProjectX.ditaval apply to
topic1.dita, but the effective DITAVAL rules for
topic2.dita will be the combination of the rules from
ProjectX.ditaval and ProjectY.ditaval:
<val> <!-- From ProjectX --> <prop att="product" val="ProjectX" action="" /> <prop att="otherprops" val="Green" action="" color="green" /> <!-- From ProjectY. Since product="ProjectX" is already --> <!-- defined, the second rule is ignored. --> <prop att="product" val="ProjectX" action="" /> <prop att="product" val="ProjectY" action="" /> <prop att="otherprops" val="Red" action="" color="red" /> </val>
So the effective action for product="ProjectX" is "include." If the order were reversed,
and ProjectY were referenced from the outer scope and ProjectX from the inner scope, the
effective rules at topic2.dita would be reversed:
<val> <!-- From ProjectY --> <prop att="product" val="ProjectX" action="" /> <prop att="product" val="ProjectY" action="" /> <prop att="otherprops" val="Red" action="" color="red" /> <!-- From ProjectX --> <prop att="product" val="ProjectX" action="" /> <prop att="otherprops" val="Green" action="" color="green" /> </val>
So the effective rule for product="ProjectX" is "exclude."
