Example: Key definitions in nested key scopes
Consider the following DITA map:
<map> <title>Root map</title> <!-- Root scope --> <keydef keys="a" href="topic-1.dita"/> <!-- Key scope A --> <topicgroup keyscope="A"> <keydef keys="b" href="topic-2.dita"/> <!-- Key scope A-1 --> <topicgroup keyscope="A-1"> <keydef keys="c" href="topic-3.dita"/> </topicgroup> <!-- Key scope A-2 --> <topicgroup keyscope="A-2"> <keydef keys="d" href="topic-4.dita"/> </topicgroup> </topicgroup> <!-- Key scope B --> <topicgroup keyscope="B"> <keydef keys="a" href="topic-5.dita"/> <keydef keys="e" href="topic-6.dita"/> <!-- Key scope B-1 --> <topicgroup keyscope="B-1"> <keydef keys="f" href="topic-7.dita"/> </topicgroup> <!-- Key scope B-2 --> <topicgroup keyscope="B-2"> <keydef keys="g" href="topic-8.dita"/> </topicgroup> </topicgroup> </map>
The key scopes in this map form a tree structure.
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 overridden 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 overridden by a key definition in an ancestor scope. For example, key "a" in key scope B.
Arrows point 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.
Key scope A-2
| Key reference | Resource to which the key resolves |
|---|---|
| a | "a", defined in the root map:
topic-1.dita
|
| d | "d", as defined in the immediate key scope:
topic-4.dita
|
| A-2.d | "d", as defined in the immediate key scope:
topic-4.dita
|
| 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.
The key name resolves to
topic-3.dita
|
| 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.
The key name resolves to
topic-3.dita
|
Key scope B
| Key reference | Resource to which the key resolves |
|---|---|
| e | "e", defined in the immediate key scope:
topic-6.dita
|
| a | "a", as defined in the
root key scope. (While a key definition for "a" exists in
the immediate key scope, it is overridden by the key definition that occurs in
the parent key scope.)
The key name resolves to
topic-1.dita
|
| 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. The key name resolves to
|
| 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:
topic-8.dita.
|