2.4.1.1 Table of contents

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.

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:

• The @processing-role attribute that is specified on the <topicref> element or an ancestor element is set to "resource-only".
• Conditional processing is used to filter out the node or an ancestor node.
• The @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.)
• There is no information from which a TOC entry can be constructed; there is no referenced resource or navigation title.
• The node is a <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").