When a DITA map (or branch of a DITA map) is referenced by another DITA map, by default, certain rules apply. These rules pertain to the cascading behaviors of attributes, metadata elements, and roles assigned to content (such as the role of "Chapter" assigned by a <chapter> element). Attributes and elements that cascade within a map generally follow the same rules when cascading from one map to another map; this topic covers the exceptions and additional rules that apply.
The @class attribute does not cascade within a map, but is used to determine processing roles that cascade from map to map. See Cascading of roles in specialized maps for more details.
As with values that cascade within a map, the cascading is additive if the attribute permits multiple values (such as @audience). When the attribute only permits one value, the cascading value overrides the top-level element.
<map> <topicref href="a.ditamap" format="ditamap" toc="no"/> <mapref href="b.ditamap" audience="developer"/> <topicref href="c.ditamap#branch1" format="ditamap" print="no"/> <mapref href="c.ditamap#branch2" platform="myPlatform"/> </map>
Elements that are contained within <topicmeta> or <metadata> follow the same rules for cascading as apply within a single DITA map. For a complete list of which elements cascade within a map, see the column "Does it cascade to child <topicref> elements?" in the topic Reconciling topic and map metadata.
For example, consider the following code snippets:
<map> <topicref href="a.ditamap" format="ditamap"> <topicmeta> <shortdesc>This map contains information about Acme defects.</shortdesc> </topicmeta> </topicref> <topicref href="b.ditamap" format="ditamap"> <topicmeta> <audience type="programmer"/> </topicmeta> </topicref> <mapref href="c.ditamap" format="ditamap"/> <mapref href="d.ditamap" format="ditamap"/> </map>
<map> <topicmeta> <audience type="writer"/> </topicmeta> <topicref href="b-1.dita"/> <topicref href="b-2.dita"/> </map>
<topicmeta> <audience type="programmer"/> <audience type="writer"/> </topicmeta>
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 OASIS-supplied "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 element in the referenced map. When the <chapter> element references a branch in another map, it supplies a role of "chapter" for that branch. In effect, the @class attribute for <chapter> ("- map/topicref bookmap/chapter ") cascades to the top-level topicref 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 may not be understandable by processors. The result is implementation specific; processors may or may not choose to treat this as an error, issue a warning, or simply assign new roles to the problematic elements.
Return to main page.
OASIS DITA Version 1.2 -- OASIS Standard, 1 December 2010
Copyright © OASIS Open 2005, 2010. All Rights Reserved.