220.127.116.11 Branch filtering: Impact on resource and key names
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="prodFeatures.features", there is no way for a processor to
distinguish which filtered copy is the intended target.
Metadata elements in the DITAVAL reference domain
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
- Enables a map author to specify a prefix that is added to the start of resource names for each resource in the branch.
- Enables a map author to specify a suffix that is added to the end of resource names (before any extension) for each resource in the branch.
- Enables a map author to specify a prefix that is added to the start of key
scope names for each key scope in the branch. If no key scope is specified
for the branch, this can be used to establish a new key scope, optionally
combined with a value specified in
- Enables a map author to specify a suffix that is added to the end of key scope names for each key scope in the branch.
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:
- The prefix
admin-is added to the beginning of each resource name in the admin branch.
- The resource productFeatures.dita becomes admin-productFeatures.dita
- The resource newFeature.dita becomes admin-newFeature.dita
- The prefix
adminscope-is added to the existing key scope "prodFeatures".
- The attribute value
keyref="adminscope-prodFeatures.features"refers explicitly to the admin copy of productFeatures.dita
- The attribute
keyref="adminscope-prodFeatures.newThing"refers explicitly to the admin copy of newFeature.dita
- The attribute value
adminscope-prodFeatures.featureswill always refer explicitly to the instance of productFeatures.dita filtered against the conditions in admin.ditaval, regardless of whether a processor has performed the filtering yet. References that use the URI productFeatures.dita or admin-productFeatures.dita could resolve differently (or fail to resolve), as discussed in Branch filtering: Implications of processing order .
Renaming based on multiple
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.