Controlling the top node (default topic)

DITA publishing tools sometimes process the hierarchy of a ditamap slightly differently for different target output formats. A workaround can be used to achieve greater consistency between different outputs to avoid confusing readers.

When a ditamap file is processed into a Help format, the first topic in the ditamap hierarchy becomes the first (or default) topic displayed. In some Help outputs, it also becomes the topic displayed when the Home button in the tri-pane navigation panel is selected.

Some Help formats allow for the nomination of a topic other than the first topic as the default page, and perhaps yet another topic as the Home topic. DITA currently has no facility to record such an alternative Home topic in the ditamap.

In Eclipse Help outputs, the TOC generated from the ditamap includes the map element as its top node. This can cause some confusion to the user, because the title highlighted in the TOC is different from the title of the displayed topic.

In the first example following, an Eclipse Help system is displaying an information set using the collection's home address. The TOC is highlighting the ditamap's map element title, while the topic associated with the first topicref in the ditamap is displayed. The second example shows the same document, open at the home address, in Microsoft HTML Help format. In this type of output, the map element in the ditamap is ignored when the TOC is generated.


Screen capture showing unlinked node at top of TOC in Eclipse Help output

Example of map title (with no associated topic) displaying in Eclipse Help TOC


Screen capture showing normal linked node at top of TOC in HTML Help output

Example of first topic title displaying in HTML Help TOC

One workaround is to structure the ditamap so that the first node is a "childless" topicref element with its toc attribute set to no, and ensuring that the title of the map element is the same as that first topic. This will result in the first topic not appearing in the TOC, creating the illusion that the top node links to the topic. The mark-up for the map would therefore follow this pattern:
<map title="Introduction to World Time Pro">
  <topicref href="c_WorldTimePro.dita" toc="no"/>
  <topicref href="c_CalculatingTime.dita">
    <topicref .... />
    <topicref .... />
    ....
  </topicref>
  <topicref href="c_FractionConverter.dita" />
  ....
</map>

Although this workaround will deliver a good result, take care that focussing on the output format (the form) doesn't result in compromises to the information design (the content), so that the separation of content and form is honoured.