Clarify referencing behavior of topicref that points to other maps.
<topicref href="a.ditamap" product="a" scope="peer" toc="no"/>
<chapter href="b.ditamap"> <topicmeta><audience type="administrator"/></topicmeta> </chapter>
This behavior needs to be clarified so that DITA implementations will know what to do with these values.
A new DITA implementation wishes to support map referencing. The developers of the application currently must come up with their own rules for treatment of metadata, which may not meet the rules of many or all other implementations. If the spec defined the meaning of these values, implementations would not have to spend time coming up with their own definitions, and would not risk creating behaviors that are incompatible with other products.
A user wishes to reference a map from within another map. Currently there is no clear definition of how to set metadata for the nested map, so the user must come up with something that seems reasonable. One user's solution may not work in most DITA implementations, or it may even cause some implementations to break due to undefined behavior. Defining the behavior will ensure that there is a proper method for the user to set values, and will provide predictable input for DITA implementations.
Update to specification.
Medium impact to the TC - some time to agree on behavior and update the language specification. Implementations that wish to support complex inheritance will require some updates, which could be trivial or could be major, depending on current level of support.
This portion of the DITA specification is poorly defined, leading to diverging interpretations and implementations. Clearly defining the behavior will ensure that tools are better able to work together, and will ensure that users can more easily discover how to get their expected behavior.
When referencing a map from a topicref, the topicref may set many attributes that apply to the target map.
Elements within <topicmeta> cascade in the same way that they do between a map and its children.
Metadata specified on a referenced map applies to the nested topicref elements using normal rules for cascading metadata. It may be combined with metadata specified on the reference, as described in the previous section.
When a topicref references an item, it defines a role for that reference. In the case of a generic topicref element, the role is simply that of a topic. In the case of a specialized topicref, the reference may define a more specific role, such as that of a chapter. When the specialized reference is to a map, that role will generally be preserved for the topics within a map.
An example of this behavior is the <chapter> element. In an ordinary case, this element will reference a chapter, and in doing so it defines a particular role for that topic: in this context, the topic itself is the root (or entirety) of a chapter. When a chapter element references a map, the same role is defined; that map takes on the role of a chapter.
This casting of the map as a chapter is relatively straightforward when the map contains only a single top-level topicref element. In that case, the entire branch functions exactly as if it was included in the bookmap, beginning with a chapter element.
If the target map contains more than one top-level topicref, the casting is slightly more complex. Each top level topicref is in effect pulled in to the position of the reference. In effect, this means that each top-level topicref in the target map takes on the role of the reference, which in this example means that each top-level topicref becomes a chapter.
This preservation of the role is true whether the reference is to a generic topicref element or to a specialized element. If a chapter element points to a generic map with a single top-level topicref element, that top-level topicref should be treated as a chapter; if a chapter element points to a bookmap with a single top-level appendix element, that appendix will also be treated as a topic.
Note that this default behavior may not be appropriate for all specialized elements. For example, a generic <mapref> element may be defined as a shortcut to reference the contents of another map; there is no real change in meaning above that of the generic topicref, aside from an indication that the target is a map. In that case the top-level references in the target map should not themselves be cast as mapref elements; instead they will likely retain the role originally given by their own map context. Elements that function in this manner when pointing to a map should declare that behavior as part of their definition. In other words - specialized elements may legitimately require special behaviors different than the defaults, but those additional behaviors should be clearly defined if processors are to make use of them.
Map references may point to a branch within a map by specifying an ID as part of the reference. The format attribute should still be set to ditamap.