1. The <map> element

A topic <map> Opens in new window mainly contains:
  • A <title> Opens in new window child element.
  • A <topicmeta> Opens in new window element where you can specify the author of the document, the date of publication, etc.
  • A hierarchy of <topicref> Opens in new window elements.
The <href> attribute of a <topicref> element specifies the URL of a topic which is part of the DITA document. Example:
<topicref href="samples/sample_glossary.dita"/>
If the target XML file contains several topics (not recommended), you'll have to use a fragment to specify the ID of the referenced topic.
<topicref href="samples/sample_glossary.dita#javascript"/>
A map contains a hierarchy of <topicref> elements. What does this mean?
1
2
3
4
5
6
7
8
 
<topicref href="topic.dita">
  <topicref href="topic_structure.dita">
    <topicref href="samples/sample_topic.dita"/>
  </topicref>
  <topicref href="block_elements.dita"/>
  <topicref href="inline_elements.dita"/>
  <topicref href="link_elements.dita"/>
</topicref>
In the case of the above example, this means two things:
  1. The overall DITA document contains this sequence of topics: topic.dita, topic_structure.dita, samples/sample_topic.dita, block_elements.dita, inline_elements.dita, link_elements.dita.
  2. Topics topic_structure.dita, block_elements.dita, inline_elements.dita, link_elements.dita are subsections of topic topic.dita. Topic samples/sample_topic.dita is a subsection of topic topic_structure.dita.
    If you instruct the DITA processing software to generate a Table of Contents for your document and/or to number the topics, the hierarchy of topics appears very clearly.
What follows is the topic map actually used for this tutorial (contents of file tutorial.ditamap Opens in new window):
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
 
<map>
  <title>DITA for the Impatient</title>

  <topicmeta>
    <author>Hussein Shafie</author>
    <publisher>Pixware</publisher>
    <critdates>
      <created date="October 7, 2009"/>
    </critdates>
  </topicmeta>

  <topicref href="introduction.dita"/>
  <topicref href="topics_and_maps.dita"/>
  <topicref href="topic.dita">
    <topicref href="topic_structure.dita">
      <topicref href="samples/sample_topic.dita" toc="no"/>
    </topicref>
    <topicref href="block_elements.dita"/>
    <topicref href="inline_elements.dita"/>
    <topicref href="link_elements.dita"/>
  </topicref>
  .
  .
  .
  <topichead navtitle="Topic maps">
    <topicref href="map.dita"/>
    <topicref href="bookmap.dita"/>
  </topichead>
  <topicref href="conclusion.dita"/>
</map>

The @toc attribute

Specifying attribute toc="no" for a <topicref> element prevents it from appearing in the generated Table of Contents.
1
2
3
 
<topicref href="topic_structure.dita">
  <topicref href="samples/sample_topic.dita" toc="no"/>
</topicref>

The <topichead> element

The <topichead> Opens in new window element provides an author with a simple way to group several topics in the same HTML page and to give this HTML page a title(1).
1
2
3
4
 
<topichead navtitle="Topic maps">
  <topicref href="map.dita"/>
  <topicref href="bookmap.dita"/>
</topichead>
 (1) A less convenient alternative would be to use an actual <topic> having no <body> at all, just a <title>.