18.9.6 Providing mid-topic contents links in HTML Help

If you provide mid-topic links in the TOC, you lose contents tracking of your current location in the Help system. And if you specify a binary TOC in HTML Help Workshop (which you must do to enable certain HTML Help features), mid-topic entries in the TOC become relatively useless. These are known HTML Help problems; DITA2Go cannot fix them.

Why not to include mid-topic links in the TOC

Providing mid-topic links in the TOC is generally not a good idea, for the following reasons:

No binary TOC with mid-topic links

If you specify a binary TOC in HTML Help workshop, and you have mid-topic links in the TOC, the name of the last TOC link to a given topic file becomes the name of all links to the file, unless you use the following settings for all but the first heading:

[HTMLParaStyles]
Midtopichead=Contents NoContLink

However, with this setting the mid-topic entries are no longer active links, which is likely to annoy users.

If you must have mid-topic links in the TOC

If you are willing to give up synchronization to get drill-down, and your project does not require a binary TOC, do the following:

  1. In [HTMLParaStyles], assign property Split only to H1-level heading formats; assign property Contents to other heading formats.
  2. Set the following option:

    [MSHtmlHelpOptions]
    ; ContentsNamesFileOnly = Yes (default, allows tracking)
    ; or No (allows direct mid-topic jumps to points within files,
    ; but disables tracking)
    ContentsNamesFileOnly=No

  3. Avoid HTML Help features that require a binary TOC, and make sure your help project file (.hhp file) does not specify Binary TOC=Yes.

TOC entries reference points inside .htm files (that is, the links have #place suffixes), so you can drill down into the file via the TOC; but TOC entries no longer synchronize with topic content.

Previous Topic:  18.9.5 Configuring contents entries for HTML Help

Next Topic:  18.9.7 Making the TOC track index links in HTML Help

Parent Topic:  18.9 Generating contents and index for HTML Help

Sibling Topics:

18.9.1 Choosing how to generate HTML Help contents and index

18.9.2 Choosing whether to generate binary contents or index

18.9.3 Generating contents and index with HTML Help Workshop

18.9.4 Generating contents and index with DITA2Go

18.9.5 Configuring contents entries for HTML Help

18.9.7 Making the TOC track index links in HTML Help

18.9.8 Customizing contents and index for HTML Help

Table of ContentsIndex