Common DITA map attributes and metadata

DITA maps have many of the same common attributes as DITA content, but also have some additional ones for controlling the way relationships are interpreted for different output purposes.

Because DITA maps may encode structures that are wholly or partially specific to a particular medium or kind of output (for example, hyperlinked web pages or printed books), DITA maps contain attributes to help processors interpret the map for each kind of output. These attributes (such as print and toc) are not available in DITA content: individual topics, once separated from the high-level structures and dependencies associated with a particular kind of output, should be entirely reusable across multiple media.

Linking attributes

The collection-type and linking attributes affect how related links are generated for topics described in the map.

collection-type

The collection-type attribute indicates how a particular set of sibling topicrefs relate to each other. The collection-type attribute is set on the container element for the sibling topicrefs. The collection-type value can indicate whether to generate links among the siblings, and what kind of links to generate (for example, next and previous links for a sequence, or sibling links for a family). The collection-type attribute can also indicate how the parent topic should link to its children (for example, showing the child links as a numbered list when the collection-type is sequence).Where the collection-type attribute is available on elements that cannot directly contain topicrefs (such as reltable and relcolspec), the behavior of the attribute is reserved for future use.

linking

By default, relationships between topics in a map are reciprocal: children link to parents and vice versa; next and previous topics in a sequence link to each other; topics in a family link to their siblings; topics in table cells of the same row in a relationship table link to each other. This default behavior can be modified using the linking attribute, which lets a topic modify how it participates in a relationship:

A topic reference with linking="none" does not exist in the map for the purposes of calculating links
linking="sourceonly" means that the topic will link to its related topics but not vice versa
linking="targetonly" means that the related topics will link to it, but not vice versa
linking="normal" is the default, and means that linking will be reciprocal (the topic will link to related topics, and they will link back to it)

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

Figure 1. Simple linking example

<topicref href="A.dita" collection-type="sequence">
  <topicref href="A1.dita"/>
  <topicref href="A2.dita"/>
</topicref>
<reltable>
  <relrow>
    <relcell>A.dita</relcell>
    <relcell>B.dita</relcell>
  </relrow>
</reltable>

A: links to A1, A2 as children; links to B as related
A1: links to A as a parent; links to A2 as next in the sequence
A2: links to A as a parent; links to A1 as previous in the sequence
B: links to A as related

Figure 2. Linking example with the linking attribute

<topicref href="A.dita" collection-type="sequence">
  <topicref href="B.dita" linking="none"/>
  <topicref href="A1.dita"/>
  <topicref href="A2.dita"/>
</topicref>
<reltable>
  <relrow>
    <relcell>A.dita</relcell>
    <relcell linking="sourceonly">B.dita</relcell>
  </relrow>
</reltable>

A: links to A1, A2 as children; (no links to B as a child, no links to B as related)
A1: links to A as a parent; links to A2 as next in the sequence; (no links to B as previous)
A2: links to A as a parent; links to A1 as previous in the sequence
B: links to A as related

Parent topic: DITA maps

Previous topic: Why DITA maps?

Next topic: DITA map structure

Navigation, media, and chunking attributes

There are standard attributes available for identifying output-media-specific content and for rechunking topics.

toc, navtitle, locktitle

Authors can exclude entries from navigation output (such as an online table of contents, or a Web site map) using the toc attribute. By default, hierarchies are included in navigation output, and tables are excluded.

Authors can provide a shorter version of the title for use in the navigation using the navtitle attribute. By default the navtitle attribute is ignored, and used only to help the author keep track of the target topic's title. The locktitle attribute can be set to ensure that the navtitle takes effect and overrides any title values in the target topic, or defined elsewhere in the topic reference metadata.

print, search

You can set attributes on a topic to indicate whether it should be included in printed output and search indexes.

chunk

When a set of topics is transformed using a map, multi-topic files can be broken into smaller files, and multiple individual topics can be combined into a single larger file, using the chunk attribute. There is no default value for the chunk attribute, but a default for an entire map may be established by setting the chunk attribute on the map element or a specialization. For a detailed description of the chunk attribute and its usage see Chunking.

copy-to

When a set of topics is transformed using a map, duplicate topic versions can be created using the copy-to attribute. The copied topic will have a new file name or location as provided in the copy-to attribute, and the map can override the default title and shortdesc for this particular copy by providing values for them in the map using the topicref's navtitle and shortdesc. For information on how the copyto attribute can be used with the chunk attribute see Chunking.