HTML Help Output

1. Introduction

HTML Help is a file format for documentation. The final documentation can be a single file with an extension .chm (for "compiled html"). It was designed by Microsoft, along with some proprietary tools to create and view it, but a number of cross-platform open-source viewers also exist now.

As the name suggests, the format is based on HTML. Internally, a .chm file is just a collection of HTML files, with some extra information. See Wikipedia and Microsoft documentation for more information.

PasDoc can generate all the files necessary to create the HTML Help documentation. We do not produce a ready .chm file — but we generate all the prerequisites necessary. After generating the files, you can create the final CHM file using tools like hhc or chmcmd.

2. Generating HTML Help files with PasDoc

First, generate documentation using pasdoc with --format=htmlhelp command-line option. In addition to normal HTML files, we will output files docs.hhc, docs.hhk and docs.hhp. You can change the names of these files to something else with --name option.

Once this is done, you can create the final .chm file using one of the tools described below.

3. Creating the final .chm file

3.1. Microsoft HTML Help Workshop (Windows only, proprietary)

One option to create the final .chm file is to use HTML Help Workshop. Unfortunately, the download links (on this Microsoft page) are broken, which has been reported but seems unlikely to be fixed.

Best options to get HTML Help Workshop now:

  1. Get it from the Internet Archive:

  2. Or install it using a Chocolatey, a package manager for Windows. Install Chocolatey itself first, using PowerShell, and then follow installation instructions for html-help-workshop package.

In both cases, after the installation the tools are in C:\Program Files (x86)\HTML Help Workshop directory. You can add it to your $PATH to easily execute hhc from the command line.

To make docs.chm file:

  • Interactively: run the hhw program from the HTML Help Workshop, open generated docs.hhp file, and run "Compile HTML file" from toolbar.

  • Or in batch mode (command line): run hhc docs.hhp.

That’s it! You have docs.chm file.

3.2. chmcmd (cross-platform, open-source)

Another option is to use cross-platform open-source tool chmcmd developed and distributed along with FPC. Call it like this:

chmcmd --no-html-scan docs.hhp

This will again create docs.chm file.

4. Custom help contents

Optionally, if you wish to use a custom help-contents file, you can specify a file name with the --html-help-contents option for PasDoc. Each line of the file specifies an entry in the help contents. Each space or tab character at the beginning of a line increases the level of the item in the contents by 1. The remainder of the line comprises a title for the item, an "=" character, and the link to which the item should be connected. For example: An Item = MyPage.html