The @keyscope attribute

The @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:

  • Each <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>.
  • Within the first <topicgroup>, content uses keyref="a" will resolve to the key in that branch (defined on the element with id="def1").
  • Within the second <topicgroup>, content uses keyref="a" will resolve to the key in that branch (defined on the element with id="def2").