DITA maps can reference topics from external sources, enabling the incorporation of content located outside the immediate map structure. This feature allows for content reuse and integration from various repositories or locations.

Using External Sources

Using external sources in DITA maps facilitates external content inclusion, involves using the href and scope attributes, and promotes content centralization and reuse.

External Content Inclusion

DITA maps enable the inclusion of content that is not directly stored within the immediate map structure. This content can reside in external repositories, on separate servers, in content management systems, or in other directories. The key feature that facilitates this is the <topicref> element, which serves as a reference to an external topic.

href Attribute

The <topicref> element includes an href attribute that specifies the location or path of the external topic file. This attribute can include a URL, file path, or other location reference. It allows the DITA map to establish a connection to the content located outside the map’s context.

scope Attribute

To indicate that a referenced topic is external, the scope attribute of the <topicref> element is set to “external.” This attribute is essential for distinguishing between topics that are part of the immediate map and those that are external to it. By setting the scope to “external,” the DITA framework understands that the content is located outside the current map and should be retrieved from the specified source.

Content Centralization and Reuse

The ability to reference topics from external sources is particularly valuable for content centralization and reuse. Organizations can maintain common content, such as legal disclaimers, product specifications, or regulatory information, in a centralized repository or system. DITA maps can then reference this content from the external source, ensuring consistency and simplifying updates. If changes are needed, they can be made in one central location, and all referencing DITA maps will reflect these updates.

Example

An organization creates a user manual for its software product using DITA. The map for this manual includes four DITA topics, one of which comes from an external source.

<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map>
  <title>Product User Guide</title>
  <topicref href="introduction.dita" />
  <topicref href="installation.dita" />
  <topicref href="external/licensing-terms.dita" scope="external" />
  <topicref href="troubleshooting.dita" />
</map>
    

In this example, the DITA map references an external topic, “licensing-terms.dita,” using the <topicref> element. The scope attribute is set to “external” to indicate that this topic is located in an external source. This allows the DITA map to integrate content from an external location seamlessly, ensuring that the user guide contains information about licensing terms without duplicating the content. External references like this enhance content reuse and maintainability within a DITA-based documentation framework.