While the processing controls that are described here are intended primarily for use
with map branches that specify multiple condition sets, they also can be used with map
branches that include only a single ditavalref element.
When a map branch uses multiple condition sets, processors create multiple effective
copies of the branch to support the different conditions. This results in potential
conflicts for resource names, key names, and key scopes. Metadata elements inside of the
ditavalref element are available to provide control over
these values, so that keys, key scopes, and URIs can be individually referenced within a
branch.
For example, the following map branch specifies two DITAVAL documents:
<topicref href="productFeatures.dita" keys="features" keyscope="prodFeatures">
<ditavalref href="novice.ditaval"/>
<ditavalref href="admin.ditaval"/>
<topicref href="newFeature.dita" keys="newThing"/>
</topicref>
In this case, the processor has two effective copies of
productFeatures.dita and newFeature.dita.
One copy of each topic is filtered using the conditions specified in
novice.ditaval, and the other copy is filtered using the
conditions specified in admin.ditaval. If an author has referenced
a topic using keyref="features" or
keyref="prodFeatures.features", there is no way for a processor to
distinguish which filtered copy is the intended target.
Renaming based on multiple ditavalref elements
It is possible for a branch with ditavalref already in
effect to specify an additional ditavalref, where each
ditavalref includes renaming metadata. When renaming,
metadata on the ditavalref nested more deeply within the
branch appears closer to the original resource or key name. For example:
<topicref href="branchParent.dita">
<ditavalref href="parent.ditaval">
<ditavalmeta>
<dvrResourcePrefix>parentPrefix-</dvrResourcePrefix>
</ditavalmeta>
</ditavalref>
<!-- additional topics or layers of nesting -->
<topicref href="branchChild.dita">
<ditavalref href="child.ditaval">
<ditavalmeta>
<dvrResourcePrefix>childPrefix-</dvrResourcePrefix>
</ditavalmeta>
</ditavalref>
</topicref>
</topicref>
In this situation, the resource branchChild.dita is given a
prefix based on both the reference to parent.ditaval and the
reference to child.ditaval. The value "childPrefix-" is
specified in the ditavalref that is nested more deeply
within the branch, so it appears closer to the original resource name. The resource
branchChild.dita would result in
parentPrefix-childPrefix-branchChild.dita. Suffixes (if
specified) would be added in a similar manner, resulting in a name like
branchChild-childSuffix-parentSuffix.dita. Note that the
hyphens are part of the specified prefix; they are not added automatically.
Handling resource name conflicts
It is an error if ditavalref-driven branch cloning results
in multiple copies of a topic that have the same resolved name. Processors SHOULD report an error in such
cases. Processors MAY recover
by using an alternate naming scheme for the conflicting topics.
In rare cases, a single topic might appear in different branches that
set different conditions, yet still produce the same result. For example, a topic
might appear in both the admin and novice copies of a branch but not contain content
that is tailored to either audience; in that case, the filtered copies would match.
A processor MAY consider this
form of equivalence when determining if two references to the same resource should
be reported as an error.