@keyscope
attributeThe @keyscope
attribute consists of one or more space-separated key
scope names. Map authors define the boundaries for key scopes by specifying the
@keyscope
attribute on <map>
elements,
<topicref>
elements, or elements that are specializations of
<map>
or <topicref>
. Such elements, their
contents, and any locally-scoped content referenced from within the element, are considered to
be part of the scope. Keys defined within a scope are only directly referenceable from within
the same scope. They can be referenced from the parent scope using the scope's name, followed by
a period, followed by the key name.
All key scopes are contiguous and non-intersecting. Within a root map, two distinct key scopes with the same name have no relationship with each other aside from that implied by their relative locations in the key scope hierarchy. They do not, for example, share key definitions. The only processing impact of a key scope's names is in defining the prefixes used when contributing qualified key names to the parent scope. For example, consider the following map segment:
<map>
<topicgroup keyscope="xyz" id="scope1">
<keydef keys="a" id="def1"/>
<!-- other topic references -->
</topicgroup>
<topicgroup keyscope="xyz" id="scope2">
<keydef keys="a" id="def2"/>
<!-- other topic references -->
</topicgroup>
<!-- lots of other content -->
</map>
This map creates two distinct scopes that happen to use the same name (xyz). This results in the following:
<topicgroup>
sets a scope of "xyz" and includes a key "a".
From outside of those two scopes, references to keyref="xyz.a"
(key "a"
within the scope "xyz") will always resolve to the first instance of that value, which is
in the first <topicgroup>
.<topicgroup>
, content uses
keyref="a"
will resolve to the key in that branch (defined on the
element with id="def1"
).<topicgroup>
, content uses
keyref="a"
will resolve to the key in that branch (defined on the
element with id="def2"
).