Map-to-map cascading behaviors

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.

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:

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

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>

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.