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.
<chapter>
element that references a DITA
map. This scenario could take several forms:<topicref>
element<topicref>
element is processed as if it were the
<chapter>
element.<topicref>
elements<topicref>
element is processed as if it were
a <chapter>
element (the referencing element).<appendix>
element<appendix>
element is processed as it were a
<chapter>
element.<part>
element, with nested
<chapter>
elements.<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<topicref>
element is processed as if it were
a <chapter>
element.