DITA map elements

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

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 a 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 might be interpreted differently for different outputs.

<reltable>

Relationship tables are defined with the <reltable> element. Relationship tables can be used to define relationships among DITA topics or among DITA topics and non-DITA resources. In a relationship table, the columns define common attributes, metadata, or information types (for example, task or troubleshooting) for the resources that are referenced in that column. The rows define relationships between the resources 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 without an @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 an element and its descendants.

<ux-window>

The <ux-window> element enables authors to define windowing information for the display of output topics that are appropriate to the delivery platform. Window management is important in user assistance and help system outputs, as well as for other hypertext and electronic delivery modes.

<topichead>

The <topichead> element provides a navigation title; it is a convenience element that is equivalent to a <topicref> element with a navigation title but no associated resource.

<anchor>

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

<navref>

The <navref> element represents a pointer to another map which is preserved as a transcluding link in the result deliverable rather than resolved when the deliverable is produced. Output formats that support such linking can 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.

<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 the current map or in another DITA map.

<anchorref>

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