Certain map-level attributes cascade throughout a map, which facilitates attribute and metadata management. When attributes cascade, they apply to the elements that are children of the element where the attributes were specified. Cascading applies to a containment hierarchy, as opposed to a element-type hierarchy.
The following attributes cascade when set on the <map>
element or
when set within a 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
@cascade
@cascade
attribute is set to avoid adding values
to attributes. For attributes that take a single value, the closest value defined on
a containing element takes effect. In a relationship table, row-level metadata is considered
more specific than column-level metadata, as shown in the following containment
hierarchy:<map>
(most general)<topicref>
container (more specific)<topicref>
(most specific)<reltable>
(more specific)<relcolspec>
(more specific)<relrow>
(more specific)<topicref>
(most specific)The @cascade
attribute can be used to modify the additive nature of
attribute cascading (though it does not turn off cascading altogether). The attribute has
two predefined values: "merge" and "nomerge".
@cascade
attribute and was the only defined behavior for DITA
1.2 and earlier.<topicref>
elements that specify a different value
for a specific metadata attribute. If the cascading value for an attribute is already
merged based on multiple ancestor elements, that merged value continues to cascade until
a new value is encountered (that is, setting cascade="nomerge"
does not
undo merging that took place on ancestors).Implementers MAY define their own custom, implementation-specific tokens. To avoid name conflicts between implementations or with future additions to the standard, implementation-specific tokens SHOULD consist of a prefix that gives the name or an abbreviation for the implementation followed by a colon followed by the token or method name.
@audience
attribute. The
following rules apply:@cascade
attribute MUST precede any
implementation-specific tokens, for example, cascade="merge
appToken:audience"
.@cascade
value. In that case, the syntax for specifying those values
consists of the implementation-specific token, followed by a parenthetical group that
uses the same syntax as groups within the @audience
,
@platform
, @product
, and @otherprops
attributes. For example, a token that applies to only @platform
and
@product
could be specified as cascade="appname:token(platform
product)"
.@cascade
attribute in useConsider the following code examples:
<map audience="a b" cascade="merge">
<topicref href="topic.dita" audience="c"/>
</map>
<map audience="a b" cascade="nomerge">
<topicref href="topic.dita" audience="c"/>
</map>
For map A, the values for the attribute are merged, and the effective value of the
@audience
attribute for topic.dita is "a b c". For
map B, the values for the attribute are not additive, and the effective value of the
@audience
attribute for topic.dita is "c".
In the following example, merging is active at the map level but turned off below:
<map platform="a" product="x" cascade="merge">
<topicref href="one.dita" platform="b" product="y">
<topicref href="two.dita" cascade="nomerge" product="z"/>
</topicref>
</map>
In map C, the reference to one.dita has effective merged values of "a
b" for @platform
and "x y" for @product
.
The reference to two.dita turns off merging, so the explicit
@product
value of "z" is used (it does not merge with ancestor values).
The @platform
attribute is not present, so the already-merged value of "a b"
continues to cascade and is the effective value of @platform
on this
reference.
When determining the value of an attribute, processors MUST evaluate each attribute on each individual element in a specific order; this order is specified in the following list. Applications MUST continue through the list until a value is established or until the end of the list is reached (at which point no value is established for the attribute). In essence, the list provides instructions on how processors can construct a map where all attribute values are set and all cascading is complete.
For example, in the case of <topicref toc="yes">
,
applications MUST stop at item 2 in the list; a value is
specified for @toc
in the document instance, so @toc
values
from containing elements will not cascade to that specific <topicref>
element. The toc="yes"
setting on that <topicref>
element will cascade to contained elements, provided those elements reach item 5 below when evaluating
the @toc
attribute.
@conref
and @keyref
attributes
are evaluated.<topicref>
element with the
@toc
attribute set to "no" will use that value.@toc
attribute on the <reltable>
element has a
default value of "no".toc="yes"
when no @toc
attribute is specified. However, a processor-supplied
default of toc="yes"
MUST not override a value of
toc="no"
that is set on a referenced map. If the
toc="yes"
value is explicitly specified, is given as a default
through a DTD, XSD, RNG, or controlled values file, or cascades from a containing
element in the map, it MUST
override a toc="no"
setting on the referenced map. See Map-to-map cascading behaviors for more details.