When map branches are cloned by a processor in order to support multiple condition sets, processors must manage conflicting resource and key names. The ditavalref domain includes metadata elements that authors can use to specify how resource and key names are renamed.
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
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.
Metadata within the
<ditavalref> element makes it possible to
control changes to resource names and key scope names, so that each distinct filtered copy can be referenced in a predictable
For example, the previous code sample can be modified as follows to create predictable resource names and key scopes for the copy of the branch that is filtered using the conditions that are specified in admin.ditaval.
<topicref href="productFeatures.dita" keys="features" keyscope="prodFeatures"> <ditavalref href="novice.ditaval"/> <ditavalref href="admin.ditaval"> <ditavalmeta> <dvrResourcePrefix>admin-</dvrResourcePrefix> <dvrKeyscopePrefix>adminscope-</dvrKeyscopePrefix> </ditavalmeta> </ditavalref> <topicref href="newFeature.dita" keys="newThing"/> </topicref>
The novice branch does not use any renaming, which allows it to be treated as the default copy of the branch. As a result, when the topics are filtered using the conditions that are specified in novice.ditaval, the resource names and key names are unmodified, so that references to the original resource name and key name will resolve to topics in the novice copy of the branch. This has the following effect on topics that are filtered using the conditions specified in admin.ditaval:
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.
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.
Return to main page.
Standards Track Work Product
|Copyright © OASIS Open 2015. All Rights Reserved.||17 December 2015|