In DITA, cross-references are links that connect different topics and content within a documentation set. To ensure a seamless user experience, DITA provides mechanisms for resolving these cross-references.

The primary goal of cross-references is to enhance the navigation and readability of documentation. DITA supports several types of cross-references, such as links to other topics (using <xref>), links to elements within the same topic (using <xref> and IDs), and key references (using <keyword> or <keyref>). Cross-references can be external, pointing to content in different topics, or internal, linking to elements within the same topic.

The resolution of cross-references in DITA is handled by processors and authoring tools. It involves determining the target of a cross-reference and rendering it appropriately in the output. The resolution process typically includes locating the target topic or element, retrieving the referenced content, and generating a link or reference in the final output format.

The <xref> element is commonly used for cross-referencing. It includes attributes like href, format, and scope to define the target and context of the reference. Key references, created using the <keyword> or <keyref> elements, provide a way to link to specific entries in a glossary, abbreviation list, or key definitions in the DITA map.

Example:

A DITA documentation set contains a topic on “System Requirements,” which references a related topic called “Installation Guide.”

System_Requirements.dita:

<topic id="system-reqs">
  <title>System Requirements</title>
  <p>This document provides an overview of the system requirements for our software.</p>
  <p>For detailed installation instructions, please refer to the <xref href="Installation_Guide.dita"/>.</p>
</topic>

Installation_Guide.dita:

<topic id="Installation_Guide">
  <title>Installation Guide</title>
  <p>This guide explains how to install our software on various platforms.</p>
  <p>Make sure to review the <xref href="system-reqs.dita"/> for system requirements before proceeding with the installation.</p>
</topic>

In this example:

• The <xref> element in the “System Requirements” topic references the “Installation Guide” topic.
• Similarly, the “Installation Guide” topic includes an <xref> that links back to the “System Requirements” topic.