Processors can generate a table of contents (TOC) based on the hierarchy of the elements
in a DITA map. By default, each <topicref>
element in a map represents a
node in the TOC. These topic references define a navigation tree.
When a map contains a topic reference to a map (often called a map reference), processors should integrate the navigation tree of the referenced map with the navigation tree of the referencing map at the point of reference. In this way, a deliverable can be compiled from multiple DITA maps.
<topicref>
element that references a map contains child
<topicref>
elements, the processing
behavior regarding the child <topicref>
elements is undefined.The effective navigation title is used for the value of the TOC node. A TOC node is generated
for every <topicref>
element that references a topic or specifies a
navigation title, except in the following cases:
@processing-role
attribute that is specified on the
<topicref>
element or an ancestor element is set to
"resource-only".@print
attribute is specified on the <topicref>
element or an ancestor element, and the current processing does not match the value set by the
@print
attribute. For example, print="printonly"
and the
output format is XHTML-based, or print="no"
and the output format is PDF. (Note that the @print
attribute is deprecated in DITA 1.3; it is
replaced by the @deliveryTarget
attribute.)<topicgroup>
element, even if it specifies a navigation
title.To suppress a <topicref>
element from appearing in the TOC, set the
@toc
attribute to "no". The value of the @toc
attribute cascades
to child <topicref>
elements, so if @toc
is set to "no" on
a particular <topicref>
, all children of the
<topicref>
element are also excluded from the TOC. If a child
<topicref>
overrides the cascading operation by specifying
toc="yes"
, then the node that specifies toc="yes"
appears in
the TOC (minus the intermediate nodes that set @toc
to "no").