Cascading of roles from map to map

When specialized topicref elements (such
as chapter or mapref) reference a map, they
typically imply a semantic role for the referenced content.

The semantic role reflects the class hierarchy of the
referencing topicref element; it is equivalent to having the
class attribute from the referencing topicref
cascade to the top-level topicref elements in the referenced map.
Although this cascade behavior is not universal, there are general guidelines for when
class values should be replaced.

When a topicref element or a specialization of a
topicref element references a DITA resource, it defines a role for that
resource. In some cases this role is straightforward, such as when a
topicref element references a DITA topic (giving it the already known
role of "topic"), or when a mapref element references a DITA map (giving
it the role of "DITA map").

Unless otherwise instructed, a specialized topicref element that
references a map supplies a role for the referenced content. This means that, in effect, the
class attribute of the referencing element cascades to top-level topicref
elements in the referenced map. In situations where this should not happen - such as all elements
from the mapgroup domain - the non-default behavior should be clearly specified.

For example, when a chapter element from the bookmap specialization
references a map, it supplies a role of "chapter" for each top-level
topicref element in the referenced map. When the
chapter element references a branch in another map, it supplies a
role of "chapter" for that branch. The class attribute for
chapter ("- map/topicref bookmap/chapter ") cascades to the
top-level topicref element in the nested map, although it does not
cascade any further.

Alternatively, the mapref element in the mapgroup domain is a
convenience element; the top-level topicref elements in the map
referenced by a mapref element MUST NOT be processed as if they are mapref
elements. The class attribute from the mapref element
("+ map/topicref mapgroup-d/mapref ") does not cascade to the referenced map.

In some cases, preserving the role of the referencing element might result in out-of-context
content. For example, a chapter element that references a bookmap might
pull in part elements that contain nested
chapter elements. Treating the part element as
a chapter will result in a chapter that nests other chapters, which is
not valid in bookmap and might not be understandable by processors. The result is implementation
specific; processors MAY choose to treat
this as an error, issue a warning, or simply assign new roles to the problematic elements.

Example of cascading roles between maps

Consider the scenario of a chapter element that references a DITA
map. This scenario could take several forms:

Referenced map contains a single top-level topicref
element

The entire branch functions as if it were included in the bookmap; the top-level
topicref element is processed as if it were the
chapter element.

Referenced map contains multiple top-level topicref
elements

Each top-level topicref element is processed as if it were
a chapter element (the referencing element).

Referenced map contains a single appendix element

The appendix element is processed as it were a
chapter element.

Referenced map contains a single part element, with nested
chapter elements.

The part element is processed as it were a chapter element.
Nested chapter elements might not be understandable by
processors; applications MAY
recover as described above.

chapter element references a single
topicref element rather than a map

The referenced topicref element is processed as if it were
a chapter element.