DITA Proposed Feature #12055

Clarify referencing behavior of topicref that points to other maps.

Longer description

The specification is not clear about how metadata is passed or inherited when a topicref points to another map. For example, it is not clear what to do with attributes and metadata in the following two samples:

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

Use Cases

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.

Technical Requirements

Update to specification.

Costs

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.

Benefits

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.

New or Changed Specification Language

Note: This item for DITA 1.2 consists entirely of updates to the specification. My expectation is that the overall behaviors should be defined well enough in this proposal that TC members are able to understand them without outstanding questions. The language itself may change slightly in the final version of the DITA 1.2 specification, but that language will still be subject to review with the full specification.

There will be a new topic about metadata inheritance when referencing maps. The general behavior can be defined rather simply:

A topicref indicates that the referenced resource (in this case, a map) is associated with the current context (the referencing map).
Properties on the topicref override or combine with corresponding properties on the referenced map.
When referencing a map or node within a map, overriding some properties has a side effect of cascading through that map, the same way that those properties would if set directly on the target map.

Specific details of each behavior are presented below.

Note: The rules presented here are the default rules to be applied to a map reference, when no other information is present. In some cases it may make sense for a specialized element to apply different rules. For example, a topicref may be specialized into a specific type of map reference, where several othermeta elements are required in order to specify information about the reference itself. In that case those othermeta elements should not cascade as they would in a default map reference. At present there is no way to identify the desired behavior by examining the DTD or Schema; such an identifier would likely be an additional requirement for DITA 1.2 (or later).

Note: Based on input prior to the TC meeting, I have used the term "cascade" instead of "inherit". There will likely be discussion outside of this proposal about whether it is appropriate to refer to the passing of map attributes to descendants as "cascading" or "inheriting". When incorporated into the specification, this content will use the same term as the rest of the specification.

Cascading of attributes

When referencing a map from a topicref, the topicref may set many attributes that apply to the target map.

Attributes that are set when referencing a map apply to the entire set of referenced content. The settings will override equivalent values in the retrieved map content. For example:

<topicref href="a.ditamap" format="ditamap" toc="no"/> means that none of the items in the target map (a.ditamap) should appear in navigation generated by the source map.
<topicref href="a.ditamap" format="ditamap" audience="joe"/> should treat all retrieved content as if it used the attribute setting audience="joe".
<topicref href="a.ditamap" format="ditamap" scope="peer"/> should treat topicrefs from a.ditamap as if they set scope="peer".
<topicref href="a.ditamap" format="ditamap" print="no"/> indicates that a.ditamap should not be used when producing output for print.

Attributes which never cascade in a map, even when set at map level, should NOT cascade to the target map. In addition, the format attribute, which is used to indicate that the target is a map, should not cascade. The following attributes do not cascade when set on a reference to a map:

format (must be format="ditamap" when pointing to a map)
conref (evaluated independently of the map reference)
navtitle (may give the reference author a hint as to the title or purpose of the referenced map)
class (additional behaviors described below)
copy-to (no defined purpose on a reference to a map)
collection-type (no defined purpose on a reference to a map)
xtrf and xtrc (no defined purpose on a reference to a map)

Cascading of metadata

Elements within <topicmeta> cascade in the same way that they do between a map and its children.

If an element does not have a defined purpose when set at the map level (such as shortdesc), it will not cascade through a map reference.
If an element defined on a map typically supplements a matching element in its children, then it has the same effect when used on a map reference. For example, the <audience> element on a map will cascade to topicref children; when a child topicref already has an audience element, both apply equally.
It is possible that a specialization will define metadata that should replace metadata in the target map, rather than adding to it. Currently, there are no elements in the base DITA specification that have this behavior, though it is possible for a specialization to desire this behavior, or for such an element to appear with a new version of DITA. At present there is no way to identify such behaviors by examing the DTD; users may only be able to achieve this behavior by overriding or customizing their tool of choice.

Specialized topicref referencing to a map

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.

Note: In some cases, preserving the role of the referencing element may result in out-of-context content. For example, a chapter that references a bookmap may pull in <part> elements. Those part elements take on the role of chapter, but likely contain additional chapter elements. The result in this case is implementation specific; processors may treat this as an error that prevents further processing, issue a warning, or assign new roles to the descendants without an error or warning.