2.1.2.2.4 DITA map attributes

Attributes unique to DITA maps

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 @print and @toc, are designed to help processors interpret the DITA map for each kind of output. 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. The @collection-type and @linking attributes affect how related links are generated for topics that are referenced in the DITA map.

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. Where the @collection-type attribute is available on elements that cannot directly contain elements (such as <reltable> or <relcolspec>), 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 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

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 without making copies.

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.

Attributes shared by DITA maps and DITA topics

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