|DITA map files / Topic hierarchy|
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.
Example of map title (with no associated topic) displaying in Eclipse Help TOC
Example of first topic title displaying in HTML Help TOC
<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.