The topichead element

The topichead element in the ditamap provides a title-only node in the hierarchy, into which normal topic references are nested. Although technically valid, this element should not be used because it results in inconsistent output.

The topichead element in the ditamap provides a way of creating a parent node in the hierarchy section without needing to have a corresponding topic.

You should avoid using topichead elements for your final ditamap. However, you might find them useful when drafting or planning your collection structure.

There are two main reasons why topichead elements should be avoided.

The first is that it conflicts with the notion of the separation of content and form, and the separation of data and metadata. All content (data) in a document should reside in the topics, not in the map. The ditamap should only contain metadata. If you use topichead as an alternative to a title-only topic, you are effectively placing non-reusable content, or data, in the ditamap.

The second reason is more practical. If you are transforming a ditamap to a hypertext output format with a TOC, such as to Eclipse Help, the topichead elements will be transformed to unlinked parent nodes in the TOC. When the user clicks on such a node, the content pane will not display an associated topic, as it will for other nodes in the TOC. This inconsistency appears to the user to be an error. The unlinked node in the TOC will also cause inconsistencies or malfunctions in the way breadcrumbs function, and the way sequences (previous and next topic links) function.