Key scopes
Key scopes enable map authors to specify different sets of key definitions for different map branches.
A key scope is defined by a <map>
or <topicref>
element that specifies the @keyscope
attribute. The @keyscope
attribute specifies the names of the scope, separated by spaces. The
legal characters for a key scope name are the same as those for keys.
A key scope includes the following components:
- The scope-defining element
- The elements that are contained by the scope-defining element, minus the elements that are contained by child key scopes
- The elements that are referenced by the scope-defining element or its descendants, minus the elements that are contained by child key scopes
If the @keyscope
attribute is specified on both a
reference to a DITA map and the root element of the referenced map, only one scope is created;
the submap does not create another level of scope hierarchy. The single key scope that results
from this scenario has multiple names; its names are the union of the values of the
@keyscope
attribute on the map reference and the root element of the submap.
This means that processors can resolve references to both the key scopes specified on the map
reference and the key scopes specified on the root element of the submap.
The root element of a root map always defines a key scope, regardless of whether a
@keyscope
attribute is present. All key definitions and key references exist
within a key scope, even if it is an unnamed, implicit key scope that is defined by the root
element in the root map.
Each key scope has its own key space that is used to resolve the key references that occur within the scope. The key space that is associated with a key scope includes all of the key definitions within the key scope. This means that different key scopes can have different effective key definitions:
- A given key can be defined in one scope, but not another.
- A given key also can be defined differently in different key scopes.
Key references in each key scope are resolved using the effective key definition that is specified within its own key scope.
Example: Key scopes specified on both the map reference and the root element of the submap
Consider the following scenario:
Only one key scope is created; it has key scope names of "A" and "B".