2.1.3.3.1 Links within maps

DITA maps serve primarily to define a navigation hierarchy of topics and non-DITA resources. Through relationship tables, maps may also define arbitrary topic-to-topic relationships such as "related links". Maps may also link to topics or non-DITA resources to establish dependency relationships without binding the linked resource into the navigation tree.

By default, the topic references within a map but not within a relationship table establish a navigation tree rooted at the root map within a map tree. A topic reference contributes to the navigation tree when it specifies a navigation title or references a topic or non-DITA resource. The @collection-type attribute of the <topicref> element determines the relationships established between the topicref and its parent, sibling, and child topicrefs, as well as among its child topicrefs.

A <topicref> or <navref> element that references a map does not bind the map to the navigation tree but acts as a form of use-by-reference link to the direct subelements of <map> and the relationship tables of the referenced map.

Maps may also contain relationship tables (<reltable>). Relationship tables establish navigation links among sets of topics and non-DITA resources. A given relationship table defines one or more links of a specific relationship type. See reltable. A map may include any number of relationship tables. Within a map tree, the effective set of relationship tables is the union of all the relationship tables in all the maps in the map tree.

Topic references that specify a @processing-role value of "resource-only" establish dependencies from the map to the associated resource but do not bind the resource to the navigation tree. Resource-only topic references are typically used for key definitions where the key is not intended to represent a specific navigation tree location and for topics that hold elements used only for content reference or that otherwise should not be reflected in the navigation tree.

Topic references in the navigation tree can further control whether or not they are included in tables of contents using the @toc attribute. A topic reference that specifies "no" for the @toc attribute and is not a resource-only topic reference still contributes to the navigation tree. In particular, any relationships determined by the value of the @collection-type attribute are created.

Topic references in the navigation tree can use the @linking attribute to control how links created by the effective @collection-type value apply to the topic reference's associated resource. See topicref-atts, topicref-atts-no-toc, and topicref-atts-without-format attribute groups.

The <navref> element links to an otherwise independent map and indicates that the integration of that map's navigation structure into the larger navigation tree is deferred so that it can be performed as a final step in any delivery of the rendered content. Maps referenced by <navref> do not contribute to the key space of the map tree from which they are referenced. The map referenced by <navref> need not be available for processing at the time the referencing map is processed.