Cascading of roles from map to map

Darwin Information Typing Architecture (DITA) Version 1.3 Part 3: All-Inclusive Edition

version
1.3
author
OASIS DITA Technical Committee

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.