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 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.

collection-type, linking

The containment structure in a map can be used to generate related links or references on output. The author can annotate the containment structure to identify a particular set of siblings as being part of a specific type of collection, such as a family or sequence. The collection-type value for a group of siblings 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). 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).

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 neighboring table cells link to each other, and so on. 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)

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, A3 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

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, copy-to

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.

New topic versions can be created using the copy-to attribute. The copied topic will have a new file name, and the map can override the default title and shortdesc by providing values for them in the map.

Shared attributes

DITA maps use the same metadata and reuse attributes that DITA topics use:

product, platform, audience, otherprops, rev, status, importance, xml:lang, translate
id, conref

DITA maps also use many of the same attributes that are used with link or xref elements in DITA content:

format, scope, href, keyref, type, query

Shared metadata elements, and the lockmeta attribute

You can associate topic metadata with a topic or branch of topics in a map. By default metadata in the map supplements or overrides metadata in the topic. If the lockmeta attribute is set to "no", then the metadata in the map will not take precedence over the metadata in the topic, and conflicts will be resolved in favor of the topic.

The metadata elements in a map are the same as those in a topic, although they may be in a separate order. The map also includes a short description and alternate titles, which can override their equivalents in the content. In sum, the map can override or supplement everything about a topic except its content (in the topic's body element).