ditavalref

The ditavalref element references a DITAVAL document that
specifies filter conditions that can be used to process a map or map branch. Other
DITAVAL-reference domain elements can be used to imply multiple copies of the map branch that
contains them and so apply a different set of conditions to each copy.

When a ditavalref element is included in a map, the conditions in
the referenced DITAVAL document are used to filter the elements in the branch. The branch
includes the parent element that contains the ditavalref element,
any child elements, and all resources that are referenced by the parent element or its
children. While there is no technical restriction that forces
ditavalref to appear before peer topic references, placing them
first is considered a best practice and all examples in the specification will use this
convention.

The filtering conditions specified in the conditions.ditaval file
apply to the following:

The topicref element that references
sampleBranch.dita and all child elements:
topicmeta, navtitle, and
topicref elements

The sampleBranch.dita topic

The insideBranch.dita topic

When more than one ditavalref element is specified in the same
branch at the same level, the effective result is one copy of the branch for each
ditavalref element. If the example above contains a reference to
otherConditions.ditaval as a peer to the existing
ditavalref element, the rendered version of this map would
reflect two copies of "Sample branch", each reflecting the conditions that are specified in
the corresponding DITAVAL document. One copy is created using the conditions in
conditions.ditaval, while the other copy uses the conditions from
otherConditions.ditaval. Map authors can use specific elements from
the DITAVAL reference domain to indicate how resources are
renamed, or processors can recover from naming collisions by
using an alternate naming scheme. See Limitations
below for more information.

If DITAVAL conditions are specified at multiple levels within a single branch, "exclude"
conditions that are specified at a higher level take precedence. In the following branch, assume alternate rules are specified for the condition
audience="novice", with the value set to "exclude" in
highLevel.ditaval and "include" in
lowLevel.ditaval. In that case, the "exclude" condition specified
in highLevel.ditaval takes precedence and so applies to the entire
branch. This is true regardless of how the "exclude" condition is specified within
highLevel.ditaval. That is, there might be a specific rule for audience="novice"; alternatively,
the audience attribute might be set to
"exclude" by default, with no specific condition specified for the value
audience="novice".

If a ditavalref element is used that does not specify the
href attribute, the element is still processed but no additional
filtering is applied. This can be used to create an unfiltered copy of a map branch
alongside other filtered copies; other aspects of the ditavalref
(such as any specified key scope or modified resource name) will still be applied to the
branch.

Limitations

The following limitations apply when using the ditavalref element;
these limitations cannot be enforced in a DTD or other XML grammar files.

When the use of the ditavalref element results in multiple copies
of a branch, resource names within that branch can be controlled with sub-elements of the
effective ditavalref. For situations where resource names are
relevant, it is an error condition for multiple ditavalref elements
to result in conflicting resource names for different content. For example, the following
map fragment would result in two distinct copies of the c.dita topic
with the same file
name:

Inheritance

Example

Attributes

The following attributes are available on this element: Universal attribute group (except for conkeyref,
which is removed for all elements in this domain) and the attributes defined below.

href

Provides a reference to a DITAVAL document. If the href attribute is
unspecified, this ditavalref will not result in any new
filtering behavior, but other aspects of the element are still evaluated. See The href attribute for general information on the format and
processing implications of the href attribute.

format

Format of the target document, which MUST be a DITAVAL document. The default value for this element is "ditaval".
See The format attribute for more information.

processing-role

The processing role defaults to "resource-only" for DITAVAL documents, which are only
used for processing and do not contain content. There is no other valid value for this
attribute on this element.