DITA map attributes

DITA maps have unique attributes that are designed to control the
way that relationships are interpreted for different output purposes. In
addition, DITA maps share many metadata and linking attributes with DITA
topics.

DITA maps often encode structures that are specific to a particular medium or output,
for example, Web pages or a PDF document. Attributes, such as
deliveryTarget and toc, are designed to help
processors interpret the DITA map for each kind of output. Many of these attributes
are not available in DITA topics; individual topics, once separated from the
high-level structures and dependencies associated with a particular kind of output,
should be entirely reusable regardless of the intended output format.

collection-type

The collection-type attribute specifies how the children of
a topicref element relate to their parent and to
each other. This attribute, which is set on the parent element, typically is
used by processors to determine how to generate navigation links in the
rendered topics. For example, a collection-type value of
"sequence" indicates that children of the specifying
topicref element represent an ordered sequence
of topics; processors might add numbers to the list of child topics or
generate next/previous links for online presentation. This attribute is
available in topics on the linklist and
linkpool elements, where it has the same
behavior. Where the collection-type attribute is available
on elements that cannot directly contain elements (such as
reltable or topicref),
the behavior of the attribute is reserved for future use.

linking

By default, the relationships between the topics that are referenced in a
map are reciprocal:

Child topics link to parent topics and vice versa.

Next and previous topics in a sequence link to each other.

Topics in a family link to their sibling topics.

Topics referenced in the table cells of the same row in a
relationship table link to each other. A topic referenced within a
table cell does not (by default) link to other topics referenced in
the same table cell.

This behavior can be modified by using the linking
attribute, which enables an author or information architect to specify
how a topic should participate in a relationship. The following values
are valid:

linking="none"

Specifies that the topic does not exist in the map for the
purposes of calculating links.

linking="sourceonly"

Specifies that the topic will link to its related topics but not
vice versa.

linking="targetonly"

Specifies that the related topics will link to it but not vice
versa.

linking="normal"

Default value. It specifies that linking will be reciprocal (the
topic will link to related topics, and they will link back to
it).

Authors also can create links directly in a topic by using the
xref or link
elements, but in most cases map-based linking is preferable, because
links in topics create dependencies between topics that can hinder
reuse.

Note that while the relationships between the topics that are referenced
in a map are reciprocal, the relationships merely imply
reciprocal links in generated output that includes links. The rendered
navigation links are a function of the presentation style that is
determined by the processor.

toc

Specifies whether topics are excluded from navigation output, such as a Web
site map or an online table of contents. By default,
topicref hierarchies are included in navigation
output; relationship tables are excluded.

navtitle

Specifies a navigation title. This is a shorter version of the title that is
used in the navigation only. By default, the navtitle
attribute is ignored; it serves only to help the DITA map author keep track
of the title of the topic.

Note: The navtitle
attribute is deprecated in favor of the
navtitle element. When both a
navtitle element and a
navtitle attribute are specified, the
navtitle element should be used.

locktitle

If locktitle is set to "yes", the
navtitle element or
navtitle attribute is used if it is present.
Otherwise, the navtitle element or
navtitle attribute is ignored and the navigation
title is retrieved from the referenced file.

Note: The navtitle
attribute is deprecated in favor of the
navtitle element. When both a
navtitle element and a
navtitle attribute are specified, the
navtitle element should be used.

print

Specifies whether the topic should be included in printed output.

Note: Beginning with DITA 1.3, the print attribute is
deprecated. It is replaced with a conditional processing attribute:
deliveryTarget. See deliveryTarget for more
details.

search

Specifies whether the topic should be included in search indexes.

chunk

Specifies that the processor generates an interim set of DITA topics that
are used as the input for the final processing. This can produce the
following output results:

Multi-topic files are transformed into smaller files, for example,
individual HTML files for each DITA topic.

Individual DITA topics are combined into a single file.

Specifying a value for the chunk attribute on a
map element establishes chunking behavior
that applies to the entire map, unless overridden by
chunk attributes that are set on more specific
elements in the DITA map. For a detailed description of the
chunk attribute and its usage, see Chunking.

copy-to

In most situations, specifies whether a duplicate version of the topic is
created when it is transformed. This duplicate version can be either
literal or virtual. The value of the copy-to attribute
specifies the uniform resource identifier (URI) by which the topic can
be referenced by a conref attribute,
topicref element, or
xref element. The duplication is a
convenience for output processors that use the URI of the topic to
generate the base address of the output. The keys
and keyref attributes provide an alternative
mechanism; they enable references to topics in specific-use
contexts.

The copy-to attribute also can be used to specify the
name of a new chunk when topics are being chunked; it also can be used
to determine the name of the stub topic that is generated from a
topicref element that contains a title but
does not specify a target. In both of those cases, no duplicate version
of the topic is generated.

For information on how the copy-to attribute can be used
with the chunk attribute, see Chunking.

processing-role

Specifies whether the topic or map referenced should be processed normally
or treated as a resource that is only included in order to resolve key or
content references.

processing-role="normal"

The topic is a readable part of the information set. It is
included in navigation and search results. This is the default
value for the topicref element.

processing-role="resource-only"

The topic should be used only as a resource for processing. It
is not included in navigation or search results, nor is it
rendered as a topic. This is the default value for the
keydef element.

If the processing-role attribute is not specified
locally, the value cascades from the closest element in the containment
hierarchy.

cascade

Specifies whether the default rules for the cascading of metadata attributes in a DITA map
apply. In addition to the following specified values, processors also MAY define additional
values.

cascade="merge"

The metadata attributes cascade; the values of the
metadata attributes are additive. This is the
processing default for the cascade
attribute and was the only defined behavior for DITA
1.2 and earlier.

cascade="nomerge"

The metadata attributes cascade; however, they are not
additive for 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).

Defines a new scope for key definition and resolution, and gives the scope one or more
names. For more information about key scopes, see Indirect key-based addressing.

Attributes in the list above are used exclusively or primarily in maps, but many important map
attributes are shared with elements in topics. DITA maps also use many of the
following attributes that are used with linking elements in DITA topics, such as
link and xref:

format

href

keyref

scope

type

The following metadata and reuse attributes are used by both DITA maps and DITA
topics:

product, platform,
audience, otherprops,
rev, status,
importance

dir, xml:lang, translate

id, conref, conrefend,
conkeyref, conaction

props and any attribute specialized from
props (such as deliveryTarget)

search

When new attributes are specialized from
props or base as a domain, they can be
incorporated into both map and topic structural types.