Topics are referenced or included in a DITA map through the use of <topicref> elements. These elements specify the location of individual topic files and define their order and attributes within the map, allowing authors to create structured and organized content hierarchies.

In a DITA map, topics are referenced or included using <topicref> elements. These elements serve as pointers to individual DITA topic files and play a vital role in structuring and organizing content within the map.

Topic References

A <topicref> element is used to reference an individual DITA topic file. It typically includes the href attribute, which specifies the location or path of the topic file within the content repository. This is how the map “links” to the content in the topic file.

Order and Attributes

The order in which <topicref> elements appear within the map determines the sequence in which the topics will be presented. Authors can control the presentation order by arranging the <topicref> elements accordingly. Additionally, <topicref> elements can include attributes like keyref, scope, and locktitle that affect the presentation and behavior of the topics.

Nested Hierarchies

DITA maps can also create nested hierarchies by placing <topicref> elements within other <topicref> elements. This allows for the creation of chapters, sections, or subsections within the map, offering a way to structure content hierarchically. Authors can build complex information structures by nesting <topicref> elements to reflect the desired organization.

Example

An organization creates a user manual for its software product using DITA. The map for this manual includes four DITA topics.

<!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="operation.dita" />
  <topicref href="troubleshooting.dita" />
  <topicref href="appendix.dita" />
</map>
    

In this example, the DITA map has a title, “Product User Guide,” and contains multiple <topicref> elements, each referencing an individual topic file. The order of the <topicref> elements determines the order in which the topics will appear in the user guide. The map serves as a container that organizes and presents the referenced topics in a structured and meaningful way, creating a cohesive document.