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
- 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.