### 18.1 Understanding how DITA2Go produces HTML Help

Microsoft HTML Help is specialized for use with Microsoft HTML Help Workshop, which is used to compile the HTML files DITA2Go generates.

Note: HTML Help does not always perform as documented; there are many defects, some pieces are missing, and the software is no longer maintained. These are issues that DITA2Go cannot address.

To produce HTML Help, DITA2Go does the following:

- creates an HTML Help project file
- generates HTML topic files from your DITA document
- optionally runs HTML Help Workshop to compile the HTML Help project.

Initial project file

When you create a DITA2Go HTML Help project, DITA2Go automatically generates a starting Microsoft HTML Help project file. This file is named for your DITA document, with extension .hhp, and placed in the project directory. For example, if you are converting MyDoc.map, DITA2Go creates an HTML Help project file named MyDoc.hhp.

Project file can be regenerated

The HTML Help project file contains the basic information needed to compile your HTML Help project. Once created, DITA2Go does not touch the HTML Help project file again, though you can tell DITA2Go to regenerate it each time you run a conversion; see §18.3.8 Regenerating the HTML Help project file.

Project file can be edited

You can edit the HTML Help project file yourself, either in a plain-text editor such as Notepad, or in HTML Help Workshop. Editing in HTML Help Workshop is risky, because the editing facility has known defects.

Compiled CHM file is the final output

The HTML Help project file and the generated HTML files become input for HTML Help Workshop, which compiles all the HTML topic files into a single “Compiled HTML File” named for your DITA document, with extension .chm. The CHM file is the file you distribute, for use with the Microsoft HTML Help viewer. You can direct DITA2Go to run the compilation, or you can use HTML Workshop yourself to compile.

CHM files must be “unblocked”

Microsoft introduced “security” features that require each CHM file to be explicitly “unblocked”, something you will have to tell your users. To unblock a CHM, right-click its icon in Windows Explorer, select Properties, and click Unblock, then click Apply, then OK. After that, when you double-click the CHM, it opens fine. If you select Properties again, the area where the Unblock button was is now blank.

View compiled file with the viewer

The only way to access all features of HTML Help is to use the HTML Help viewer; you cannot view a CHM file with a Web browser. Neither Internet Explorer nor Firefox is able to display the tri-pane and search windows, although Internet Explorer (but not Firefox) can be persuaded to look inside a .chm on your local system. This is true regardless of the tool used to generate HTML Help.

View uncompiled files with a browser

If you are interested only in viewing HTML topic files, without the Contents, Index, Search, or the toolbar buttons, you can use a browser. If that is your intention, when you use DITA2Go to generate HTML Help, choose configuration options that do not produce <object> tags (which means no pop-ups or secondary windows); those tags appear in Firefox as extra spaces, and do not work as intended. You are better off converting to XHTML (or, if necessary, standard HTML); and adding navigation (see §29. Providing navigation in HTML) to the top and bottom of each output page. Also see §18.6.2 Specifying href link syntax for HTML Help.

Previous Topic: 18. Generating Microsoft HTML Help

Next Topic: 18.2 Understanding why Unicode is not the answer

Parent Topic: 18. Generating Microsoft HTML Help

Sibling Topics:

18.2 Understanding why Unicode is not the answer

18.3 Setting up an HTML Help project

18.4 Customizing HTML Help display features

18.5 Creating pop-ups for HTML Help

18.6 Creating links and hypertext jumps in HTML Help

18.7 Creating related-topic links for HTML Help

18.8 Using secondary windows in HTML Help

18.9 Generating contents and index for HTML Help

18.10 Providing full-text search (FTS) for HTML Help

18.11 Setting up CSH for HTML Help

18.12 Generating HTML Help in non-Western languages

18.13 Compiling and testing HTML Help

18.14 Mapping and merging CHM files