New topic about "Map-to-map cascading"

When a DITA map is referenced by another DITA map, by default, certain rules apply. These rules pertain to the cascading behaviors of attributes and metadata elements.

Cascading of attributes

When a <topicref> element references a DITA map, the referencing map sets certain attributes. For example, consider the following code snippet from test.ditamap:

<map>
    <topicref="a.ditamap" format="ditamap" toc="no"/>
    <topicref="b.ditamap" format="ditamap" audience="developer"/>
    <topicref="c.ditamap" format="ditamap" scope="peer"/>
    <topicref="d.ditamap" format="ditamap" print="no"/>
</map>

When test.ditamap is processed, the following behavior occurs:

The DITA topics that are referenced by a.ditamap do not appear in the navigation generated by test.ditamap.
The DITA topics that are referenced by b.ditamap are treated as if they have an @audience attribute that is set to "developer".
The DITA topics referenced by c.ditamap are treated as if they have a @scope attribute that is set to "peer."
The DITA topics that are referenced by d.ditamap are not generated when the map is transformed to printed output.
In each case, the value of the attribute that is set in test.ditamap (the referencing DITA map) cascades; it overrides the attribute value that is set in a.ditamap, b.ditamap, c.ditamap, and d.ditamap (the referenced DITA maps).

Other attributes set in the referencing map do not override those specified in the referenced DITA map. These attributes include all attributes that (by definition) do not cascade.

DITA attribute	Comment
@conref	Is evaluated separately from the map reference
@class	Additional behavior described below
@copy-to	Has no defined purpose in this context
@collection-type	Has no defined purpose in this context
@format	?
@navtitle	Provides the author a hint to the title of purpose of the referenced DITA map
@xtrf	Has no defined purpose in this context
@xtrc	Has no defined purpose in this context

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 example, consider the following code snippets:

Figure 1. 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. 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 behavior 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 b-1.dita topic and b-2.dita topics 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 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 simple maps this is straight-forward; a <topicref> element references a DITA topic, and a <mapref> element references a DITA map.

However, consider the scenario of a <chapter> element that references a DITA map. This scenario could take several forms:

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.
Map contains multiple top-level <topicref> elements: Each top-level <topicref> element is processed as if it were a <chapter> element (the referencing element).
Map contains a single <appendix> element: The <appendix> element is processed as it were a chapter element.

In each of the above cases, resource referenced by the <chapter> element is treated as a like element. In situations where this should not happen, the non-default behaviour should be clearly specified. As an example, a <mapref> element is a convenience element; the top-level <topicref> elements in the map referenced by a <mapref> element should not be processed as if they are <mapref> elements.

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

dita message

Map-to-map cascading behaviors

Cascading of attributes

Cascading of metadata elements

Cascading in specialized maps