DITA linking

DITA depends heavily on links. The purposes for which it provides links include defining the content and organization of publication structures (DITA maps), topic-to-topic navigation links and cross references, and reuse of content by reference. All DITA links use the same addressing facilities, either URI-based addresses or DITA-specific indirect addresses using keys and key references.

At its most general, a link establishes a relationship among two or more objects. In DITA, relationships are among DITA elements and either other DITA elements or non-DITA resources, such as Web pages. Relationships may be explicitly typed in some cases (relationship tables and subject scheme maps for example) but are not always associated with a specific relationship type.

Note: For example, a <keyword> element that uses a key reference to link to the definition of the keyword can be considered to be establishing a "mention-of" relationship from the <keyword> element to the definition and a "definition-of" relationship from the definition to the <keyword> element. But those link types are not formally defined either in the DITA definition of <keyword> or in the markup for the <keyword> element itself. While DITA enables the formal definition of typed relationships for some types of link elements, it does not require that all links be formally typed and does not provide a general mechanism for associating explicit link types with links.

In the abstract, link relationships may be explicit, defined directly by some type of markup in the source data, or implicit, implied by properties of the content that a processor uses to infer relationships (for example, matching the content of a <keyword> element to the title of a topic of a specific topic type). DITA formally defines only explicit links, although processors may implement implicit links.

A link may establish either a navigation relationship or a use-by-reference relationship (e.g., content references). Navigation relationships are used primarily to enable navigation from one element to another, although they may also be used for other purposes, such as classification, or association of metadata. Use-by-reference relationships establish the effective structure and content of the information set.

An element that establishes one or more such relationships is a "link-defining element". Some element types, such as <link> and <xref>, are always link-defining elements. Other element types become link-defining elements when they use specific link-defining attributes.

Almost any element may become a use-by-reference link by using the @conref or @conkeyref attribute to establish a content reference (conref) relationship to another element or set of elements (see Use by reference). Elements such as <term> and <keyword> may become navigation links by using the @keyref attribute to establish a relationship to another DITA element or non-DITA resource.

In general, elements within topics that take both the @href and @keyref attributes always act as elements that define a navigation link, while elements that take @keyref but not @href act as elements that define a navigation link only when they specify @keyref.

A given link-defining element may establish more than one relationship. For example, an element may establish both a content reference link and a navigation link. A single row in a relationship table may establish a number of distinct relationships among the topics referenced in the different cells of the relationship table. A topic reference within a hierarchy of topic references establishes not only a use-by-reference relationship from the map to the topic, but also hierarchical relationships from the referenced topic to other topics in the navigation hierarchy (parents, siblings, and children).

DITA defines two forms of addresses for use in defining links, direct URI-based addresses and indirect key references. In all cases, the nature of the relationships established is independent of the form of address used. For example, a cross reference that uses a key reference to address the target of the cross reference is functionally equivalent to having addressed the same target by URI reference, in that the final processing result should be the same in both cases. However, the two forms of address have different practical and intermediate processing implications. See DITA addressing.

Links from maps to other maps, topics, or non-DITA resources establish explicit dependencies from the map containing the links to the associated resources. Links from maps to maps create a "map tree". The set of dependencies for a root map is the union of the dependencies of all the maps in the map tree.

Links from a topic to other topics, maps, or non-DITA resources establish explicit dependencies from the topic containing the links to the associated resources, and implicit dependencies from any maps that use that linking topic to its dependencies.

For the purposes of determining the set of dependencies for a given map tree, processors may ignore any implicit dependencies created by links within topics that are not also established by explicit dependencies in the map tree. In the case where a map includes a topic that includes a topic-to-topic link, where the linked topic is not explicitly included in the map, and the processor considers only dependencies that are explicitly defined in the map, the processor may fail to resolve the topic-to-topic link. This case can be avoided by using a resource-only topic reference in the map tree to establish the dependency explicitly. If the resource-only topicref also defines a key, the link within the topic can then be changed to use a key reference (@keyref or @conkeyref) instead of a URI reference (@href, @conref). See Key-based (indirect) addressing.

Navigation links have an associated "scope" indicating the closeness of the relationship of the linking element to associated resources. See The scope attribute.

Most navigation links have an associated "link text", which is the text used to render the link so that it can be used. For all elements that allow or require link text, the link text may be specified as part of the linking element or, if unspecified, should be taken from the referenced resource. The details for how the link text for a given element should or may be generated are defined for that element type and may also be determined entirely by a rendition processor.

In the specific case of cross references created using <xref> and related links using <link>, the potential set of rules for constructing link text is essentially unbounded. Processors may, for example, define conventions for the value of @outputclass by which authors can indicate the details of how the link text should be constructed, or they may provide appropriate configuration options for controlling or customizing the construction of link text in cross references.

2.1.3.3 DITA linking