Troubleshooting HTML Help Issues

Following are issues that may occur when generating HTML Help output with Flare.

Index entries are not appearing in generated HTML Help output

Cause

This issue can occur when the binary index option in the skin settings is not selected. Microsoft HTML Help requires that all indexes in merged help systems have a binary index so that they can be properly merged.

Solution

Perform the following steps for each project to ensure that the index is binary.

  1. In Project Organizer, navigate to the Skins folder.
  2. Open your skin and select the HTML Help Setup tab.
  3. Select Index Options.
  4. Check the Binary check box.
  5. Generate your merged HTML Help.

For more information on this process, see Creating a Binary Index.

Search results are missing in HTML Help files

A common issue encountered by Microsoft HTML Help developers is when a "No Topics Found" message appears while searching a CHM file.

Cause

Typically, this is the result of an unregistered dynamic link library (DLL) file on the computer building the Help file. The DLL is named "itcc.dll" and is a component of Microsoft's CHM specification. Its purpose is to supply the operating system running Flare with the ability to build a CHM file with index and search capabilities.

A variety of software vendors (particularly those that develop Help authoring tools) distribute a copy of the itcc.dll file along with their program installation files. Should you happen to install or uninstall program with a copy of this file (e.g., a Help tool or software program from another vendor or another MadCap software tool that requires this file), it is possible for other copies of the itcc.dll file to become unregistered.

Solution

You will need to manually register the DLL using a batch file or the command line utility. After registering the DLL, build your Microsoft HTML Help output again. Then retry your search in the output.

How to register the DLL file using a batch file:

  1. In Windows Explorer, navigate to the Flare installation's \bin directory. Typically, the path is as follows (where [#]= the Flare version number):

    • Windows 7 or 8 (64-bit versions)
      • If you are using Flare 12 or later

        C:\Program Files\MadCap Software\MadCap Flare [#]\
        Flare.app\Resources\Bin

      • If you are using Flare 11 or earlier

        C:\Program Files\MadCap Software\MadCap Flare V[#]\
        Flare.app\Resources\Bin

    • Windows 7 or 8 (32-bit versions)

      C:\Program Files (x86)\MadCap Software\MadCap Flare V[#]
      \Flare.app\Resources\Bin

  2. In the bin directory, double-click the file named RegisterItcc.bat.

    This runs the batch file. If the registration is successful, a message appears telling you so.

How to register the file with the command line utility:

  1. In Windows Explorer, open the computer's System32 directory. The path is C:\Windows\System32.

  2. Right-click the application file named cmd.exe and select Run as administrator from the context menu.

  3. If the User Account Control message appears, click Yes. This allows you to use the command prompt to make changes on the system.

  4. At the command prompt, do the following:

    1. Type cd to change directories and press the SPACEBAR. Then type the path to the Flare \bin directory as shown in this example:

    2. Press Enter.
  5. At the command prompt, type: registeritcc.bat. Then press Enter. This runs the batch file. If the registration is successful, a message tells you so.

  6. Click OK to acknowledge the message.
  7. Close the command prompt.

Multiple versions of the same topic appear in the search results

When you search via a keyword in HTMLHelp output, multiple versions of the same topic appear in the search results.

Cause

This may be caused because topics that are not linked directly or indirectly from the target are being included in the HTMLHelp output.

Solution

There is an option in the Target Editor that will allow you to exclude content (such as topics and images) not directly or indirectly linked from the target. Perform the following steps.

  1. Open the HTML Help target.
  2. Click the Advanced tab of the Target Editor.
  3. Select Exclude content not linked directly or indirectly from the target.

  4. Click to save your work.

For more information on this process, see Excluding Content not Linked Directly or Indirectly from Targets.

Generated CHM files do not open and content does not display

Cause and Solution

This problem can have one of the following causes.