Map elements in a DITA map are ordered and arranged using <topicref> elements, which define the sequence and hierarchy of topics within the map. The order and nesting of these elements determine how topics are presented and organized in the DITA documentation.

Use of <topicref> Elements

In a DITA map, the primary mechanism for organizing and ordering content is through <topicref> elements. Each <topicref> element references a DITA topic and defines its position within the map.

Order of <topicref> Elements

The order in which <topicref> elements are placed within the map determines the sequence in which topics appear in the final documentation. For example, topics listed earlier in the map will be presented first, followed by those that appear later.

Nesting of <topicref> Elements

<topicref> elements can also be nested within other <topicref> elements to create hierarchies. This nesting establishes chapters, sections, subsections, and other structural elements in the documentation. The order and nesting of these elements provide the map’s structure and organization.

Example

<topicref> elements are used to order and arrange map elements in a DITA map.

<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map>
  <title>User Guide</title>
  <topicref href="introduction.dita" />
  <topicref href="installation.dita" />
  <topicref href="operation.dita">
    <topicref href="operation-basics.dita" />
    <topicref href="operation-advanced.dita" />
  </topicref>
  <topicref href="troubleshooting.dita" />
</map>
    

In this example:

• The <map> element defines a DITA map titled “User Guide.”
• Multiple <topicref> elements reference individual DITA topics, such as “introduction.dita” and “troubleshooting.dita.”
• Nested <topicref> elements are used to create hierarchies within the map. For example, “operation.dita” is a parent topic that contains two child topics, “operation-basics.dita” and “operation-advanced.dita.” The order of the <topicref> elements determines the sequence in which these topics will be presented in the documentation, creating a structured organization for the user guide.