2.3.4.10.8 Example: Key definitions in nested key scopes

In this scenario, the root map contains nested key scopes, each of which contain duplicate key definitions. The effective key definition depends on key-scope precedence rules.

Consider the following DITA map:

<map>
  <title>Root map</title>
  <!-- Root scope -->
  <keydef keys="a"/>
  
  <!-- Key scope A -->
  <topicgroup keyscope="A">
    <keydef keys="b"/>
    
    <!-- Key scope A-1 -->
    <topicgroup keyscope="A-1">
      <keydef keys="c"/>
    </topicgroup>

    <!-- Key scope A-2 -->    
    <topicgroup keyscope="A-2">
      <keydef keys="d"/>
    </topicgroup>
  </topicgroup> 

  <!-- Key scope B -->  
  <topicgroup keyscope="B">
    <keydef keys="a"/>
    <keydef keys="e"/>

    <!-- Key scope B-1 -->     
    <topicgroup keyscope="B-1">
      <keydef keys="f"/>
    </topicgroup>

    <!-- Key scope B-2 -->
    <topicgroup keyscope="B-2">
      <keydef keys="g"/>
    </topicgroup>
  </topicgroup>
</map>

The key scopes in this map form a tree structure.

Figure 1. Graphical representation of the key scopes

Diagram of a complicated DITA map that contains multiple key scopes

Each box in the diagram represents a key scope; the name of the key scope is indicated in bold with upper-case letters. Below the name of the key scope, the key definitions that are present in the scope are listed. Different typographic conventions are used to indicate where the key definition occurs:

No styling
The key definition occurs in the immediate key scope and is not overriden by a key definition in a parent scope. For example, key "a" in the root map.
Parentheses
The key definition occurs in a child scope. For example, keys "A-1.c" and "A-2.d" in key scope A.
Brackets
The key definition occurs in the immediate key scope, but it is overriden by a key definition in an ancestor scope. For example, key "a" in key scope B.

Arrows points from child to parent scopes.

Assume that each key scope contains numerous key references. The following tables demonstrate how key references resolve in key scopes A-2 and B. The first column shows the value used in key references; the second column shows the resource to which the key resolves.

Table 1. Key scope A-2
Key reference Resource to which the key resolves
a "a", defined in the root map
d "d", as defined in the immediate key scope
A-2.d "d", as defined in the immediate key scope
c Undefined
A-1.c "A-1.c", as defined in key scope A-1. This key name is available because it exists in the parent scope, key scope A.
A.A-1.c "A-1.c", as defined in key scope A-1. This key name is available because it exists in the root key scope.
Table 2. Key scope B
Key reference Resource to which the key resolves
e "e", defined in the immediate key scope
a "a", as defined in the root key scope. (While a key definition for "a" exists in the immediate key scope, it is overriden by the key definition that occurs in the parent key scope.)
B.a

"a", as defined in the immediate key scope. Because the key reference uses the scope-qualified names, it resolves to the key "a" in scope B.

g Undefined. The key "g" is defined only in key scope B-2, so no unqualified key named "g" is defined in scope B.
B-2.g "g", as defined in key scope B-2.

Return to main page.