Chapter 2, Section 1.2.3.5. Map-to-map cascading behaviors

1.2.3.5. Map-to-map cascading behaviors

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.

Cascading of attributes from map to map

The following attributes cascade within a single map:

@audience, @platform, @product, @otherprops, @rev
@props and any attribute specialized from @props
@linking, @toc, @print, @search
@format, @scope, @type
@xml:lang, @dir, @translate
@processing-role

Of these, the following attributes do not cascade from map to map:

@format: this attribute must be set to "ditamap" in order to reference a map or a branch of a map, so it cannot cascade through to the referenced map.
@xml:lang and @dir: cascading behavior for xml:lang is defined in The @xml:lang attribute. The @dir and translate attributes work the same way.
@scope: the @scope value describes the map itself, rather than the content. A @scope value of "external" indicates that the referenced map itself is external and unavailable, so the value cannot cascade into that referenced map.

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.

Example of attributes cascading between maps

For example, assume the following references in test.ditamap:

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

The map a.ditamap is treated as if toc="no" is specified on the root <map> element. This means that the topics that are referenced by a.ditamap do not appear in the navigation generated by test.ditamap (except for branches within the map that explicitly set toc="yes").
The map b.ditamap is treated as if audience="developer" is set on the root <map> element. If the audience attribute is already set on the root <map> element within b.ditamap, the value "developer" is added to any existing values.
The element with id="branch1" within the map c.ditamap is treated as if print="no" is specified on that element. This means that the topics within the branch with id="branch1" do not appear in the printed output generated by test.ditamap (except for nested branches within that branch that explicitly set print="yes").
The element with id="branch2" within the map c.ditamap is treated as if platform="myPlatform" is specified on that element. If the @platform attribute is already specified on the element with id="branch", the value "myPlatform" is added to existing values.

Cascading of metadata elements

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:

Figure 2-4. `test-2.ditamap`

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

Figure 2-5. b.ditamap

<map>
    <topicmeta>
        <audience type="writer"/>
    </topicmeta>
    <topicref href="b-1.dita"/>
    <topicref href="b-2.dita"/>
</map>

When test-2.ditamap is processed, the following behaviour occurs:

Because the <shortdesc> element does not cascade, it does not apply to the DITA topics that are referenced in a.ditamap.
Because the <audience> element cascades, the <audience> element in the reference to b.ditamap combines with the <audience> attribute that is already specified at the top level of that map. The result is that the b-1.dita topic and b-2.dita topic are processed as if they each contained the following child <topicmeta> element:
```
<topicmeta>
    <audience type="programmer"/>
    <audience type="writer"/>
</topicmeta>
```

Note

It is possible that a specialization might define metadata that should replace rather than add to metadata in the referenced map, but DITA (by default) does not currently support this behavior.

Cascading of roles in specialized maps

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.

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

‣ Parent topic: Section 1.2.3. DITA metadata

‣ Previous topic: Section 1.2.3.4. Cascading of attributes and metadata in a DITA map

‣ Next topic: Section 1.2.3.6. Reconciling topic and map metadata