DITA map elements

A DITA map describes the relationships among a set of DITA topics. The DITA map and map group elements organize topics into hierarchies, groups, and relationships; they also define keys.

Map and map group elements

A DITA map is composed of the following elements:

map

The <map> element is the root element of the DITA map.

topicref

The <topicref> elements are the basic elements of a map. A <topicref> element can reference a DITA topic, a DITA map, or any non-DITA resource. A <topicref> element also can have a title, short description, and the same kind of prolog-level metadata that is available in topics.

The <topicref> elements can be nested to create a hierarchy, which can be used to define a table of contents (TOC) for print output, online navigation, and parent/child links. Hierarchies can be annotated using the @collection-type attribute to define a particular type of relationship, such as a set of choices, a sequence, or a family. These collection types can affect link generation, and they may be interpreted differently for different outputs.

reltable

Relationship tables are defined with the <reltable> element. Relationship tables can be used to define relationships between DITA topics or between DITA topics and non-DITA resources. In a relationship table, the columns define common attributes, metadata, or information type (for example, task or troubleshooting) for the resources referenced in that column. The rows define relationships between the resources referenced in different cells of the same row.

The <relrow>, <relcell>, <relheader>, and <relcolspec> elements are used to define the components of the relationship table. Relationships defined in the relationship table also can be further refined by using the @collection-type attribute.

topicgroup

The <topicgroup> element defines a group or collection outside of a hierarchy or relationship table. It is a convenience element that is equivalent to a <topicref> element with no @href attribute or navigation title. Groups can be combined with hierarchies and relationship tables, for example, by including a <topicgroup> element within a set of siblings in a hierarchy or within a table cell. The <topicref> elements so grouped can then share inherited attributes and linking relationships with no effect on the navigation or table of contents.

topicmeta

Most map-level elements, including the map itself, can contain metadata inside the <topicmeta> element. Metadata typically is applied to the element and its descendants.

topichead

The <topichead> element provides a navigation title; it is an convenience element that is equivalent to a <topicref> element with a navigation title but no @href attribute.

anchor

The <anchor> element provides an integration point that another map can reference in order to insert its navigation into the current navigation tree. For those familiar with Eclipse help systems, this serves the same purpose as the <anchor> element in that system. It may not be supported for all output formats.

navref

The <navref> element represents a pointer to another map which should be preserved as a transcluding link rather than resolved. Output formats that support such linking will integrate the referenced resource when displaying the referencing map to an end user.

keydef

Enables authors to define keys. This element is a convenience element; it is a specialization of <topicref> that sets the default value of the @processing-role attribute to resource-only. Setting the @processing-role attribute to resource-only ensures that the resource referenced by the key definition is not directly included in the navigation that is defined by the map that includes the key definition.

mapref

Enables authors to reference an entire DITA map, including hierarchy and relationship tables. This element is a convenience element; it is a specialization of <topicref> that sets the default value of the @format attribute to ditamap. The <mapref> element represents a reference from a parent map to a subordinate map.

topicset

Enables authors to define a branch of navigation in a DITA map so that it can be referenced from another DITA map.

topicsetref

Enables authors to reference a navigation branch that is defined in another DITA map.

anchorref

Enables authors to define a map fragment that is pushed to the location defined by an anchor.

Example of a simple map with a relationship table

The following example contains the markup for a simple relationship table:

<map>
...
<reltable>
  <relheader>
    <relcolspec type="concept"/>
    <relcolspec type="task"/>
    <relcolspec type="reference"/>
  </relheader>
  <relrow>
    <relcell>
      <topicref href="A.dita"/>
    </relcell>
    <relcell>
      <topicref href="B.dita"/>
    </relcell>
    <relcell>
      <topicref href="C1.dita"/>
      <topicref href="C2.dita"/>
    </relcell>
  </relrow>
</reltable>
</map>

A DITA-aware tool might represent the <reltable> graphically:

type="concept"	type="task"	type="reference"
A	B	C1 C2

When the output is generated, the topics contain the following linkage:

A: Links to B, C1, and C2
B: Links to A, C1, and C2
C1, C2: Links to A and B

Example of a simple map that defines keys

The following example illustrates how keys can be defined:

<map>
	<keydef keys="dita-tc" href="dita_technical_committee.dita"/>
	<keydef keys="dita-adoption" href="dita_adoption_technical_committee.dita"/>
	...
</map>

The map also could be tagged in either of the following ways:

<topicref> element with @processing-role attribute set to "resource-only"

<map>
	<topicref keys="dita-tc" href="dita_technical_committee.dita" processing-role="resource-only"/>
	<topicref keys="dita-adoption" href="dita_adoption_technical_committee.dita" processing-role="resource-only"/>
	...
</map>

<topicref> element with @toc, @linking, and @search attributes set to "no"

<map>
	<topicref keys="dita-tc" href="dita_technical_committee.dita" toc="no" linking="no" search="no"/>
	<topicref keys="dita-adoption" href="dita_adoption_technical_committee.dita" toc="no" linking="no" search="no"/>
	...
</map>

Example of a simple map that references another map

The following code sample illustrates how a DITA map can reference another DITA map:

<map>
	<title>DITA work at OASIS</title>
	<topicref href="oasis-dita-technical-committees.dita>
		<topicref href="dita_technical_committee.dita"/>
		<topicref href="dita_adoption_technical_committee.dita/>
	</topicref>
<mapref href"oasis-processes.ditamap"/>
...
</map>

The map also could be tagged in the following way:

<map>
	<title>DITA work at OASIS</title>
	<topicref href="oasis-dita-technical-committees.dita>
		<topicref href="dita_technical_committee.dita"/>
		<topicref href="dita_adoption_technical_committee.dita/>
	</topicref>
<topicref href"oasis-processes.ditamap" format="ditamap/>
...
</map>

With either of the above examples, during processing, the map is resolved in the following way:

<map>
	<title>DITA work at OASIS</title>
	<topicref href="oasis-dita-technical-committees.dita>
		<topicref href="dita_technical_committee.dita"/>
		<topicref href="dita_adoption_technical_committee.dita/>
	</topicref>
<-- Contents of the oasis-processes.ditamap file -->
<topicref href"oasis-processes.dita>
	...
</topicref>
...
</map>

Example of maps that use the <anchor> element and the @anchorref attribute

In this example, an anchor is defined with an ID of "a1".

<map>
  <title>MyComponent tasks</title>
  <topicref navtitle="Start here" href="start.dita" toc="yes">
    <navref mapref="othermap2.ditamap"/>
    <navref mapref="othermap3.ditamap"/>
    <anchor id="a1"/>
  </topicref>
</map>

The id on <anchor> can be referenced by the anchorref attribute on another map's <map> element. For example, the map to be integrated at that spot would be defined as follows.

<map anchorref="a1">
  <title>This map is pulled into the MyComponent task map</title>
  ...
</map>

2.1.2.2.3 DITA map elements

Map and map group elements

Example of a simple map with a relationship table

Example of a simple map that defines keys

Example of a simple map that references another map

Example of maps that use the <anchor> element and the @anchorref attribute