Introduction to HTMLHelp

This article introduces what Microsoft provides for creation of help files, including how to get started.

There are two versions of Help available for use with Microsoft Windows: HTML Help and the Assistance Platform Client. The original help system, Windows Help (WinHlp32.exe) that used files with a hlp extension, is deprecated. The hlp files cannot be used in current versions of Windows without downloading and installing WinHlp32.exe separately.

The MSDN says that "The Assistance Platform client can only be used to display Windows Help content" .... "customized by OEMs, system builders, and enterprise customers under license agreement, but cannot be used by third-party programs." Which means that most of us cannot use it.

The remainder of this article is a brief introduction to the use of HTML Help.

To create and maintain HTML Help fles, you either use the "HTML Help Workshop" from Microsoft or other software from third parties. As far as I know, all third-party tools cost extra. The HTML Help Workshop is probably installed with Visual Studio but if not then see the references at the bottom of this article for downloading and installing it.

HTML Help files have a chm extension. More specifically, the files that are created for use by the user have a chm extension. HTMLHelp help files are called Compiled Help Module files since they are actually many files gathered ("compiled") and compressed together. Most of the files are HTML files but not all are. Therefore most of the content of a CHM file can be created using a HTML editor. We use the "HTML Help Workshop" to specify what files to include in the CHM file and to compile everything together.

Creating a HTMLHelp Project

Creation of a compiled HTMLHelp file includes creation of the HTML files and a HTMLHelp project. The project defines other files (such as Table of Contents and Index) required for the compiled help file and how they all fit together. A HTMLHelp project is not the same as a Visual Studio project; they are totally different. For convenience, it is hepful to have the HTMLHelp project in a subdirectory of the Visual Studio project directory of the application that the help is for. So the first thing to do is to create directories for the HTMLHelp project and the files.

In the Visual Studio Solution Explorer, right-click on your Visual Studio project. Select "Add" | "New Folder" from the context menu. Give it the name "Help". Then right-click the Help folder and create the "HTML" sub-folder. The "Help" directory will be the main directory for your HTML Help project. It is useful but not required to have the HTML files in a separate directory, and the HTML directory is for doing that. An advantage of using a separate folder is that you can then use the option to automaticlly include the HTML files in your HTMLHelp project; otherwise you must manually add each file.

For the remainder of this article, "project" refers to the HTMLHelp project unless it is qualified as the Visual Studio project.

Note that the HTML Help Workshop seems to think that all files it shows is changed and therefore asks if you want to save the changes. So you might use HTML Help Workshop to open a file just to look at it and then it will ask you if you want to save the changes. I always answer no if I know there are no changes.

Creating HTML Files

I think it is easier to create at least one HTML file (in the HTML directory created previously) before creating the HTMLHelp project; it is however not required to do that. The first file created can be and should be the default file that will contain the text of the first page shown. For the file name use the name of your application (whatever you prefer), with a htm or html extension. In the HTML file, you should create a header using a H1 tag and at least one paragraph to start with. Then later you can specify that filename in the project options; that is, the "Default file" in the General tab of the HTMLHelp project options.

You can use whatever HTML editor you prefer but for this article I will use Visual Studio. To do that, right-click on the HTML folder that was created previously, then select "Add" | "New Item..." then select "HTML Page" and give it the name you want to use for the default file. When the document opens, create a header (use h1 tags). Also set the page's title to the text used in the heading. Then enter whatever text you want to. Then save the document.

Using HTML Help Workshop

Then execute the HTML Help Workshop. Go to the Start menu and look for "HTML Help Workshop". Assuming it is there, execute "HTML Help Workshop", then from "File | New" select "Project". A "wizard" will appear and the first dialog will be:

Just leave the default, which is for creating a project. Click "OK". Next a "New Project" dialog will be shown, which looks as:

Again use the default, since you do not need to convert a WinHelp Project. Click "Next >". Next the "New Project -- Destination" dialog will be shown, which looks as:

For this, specify the Help directory created previously and the new filename of the project file. The extension of the project file will be "hhp" but you do not need to provide the extension. Next the "New Project -- Existing Files" dialog will be shown, which looks as:

Since we already created a HTML file, we have an existing HTML file, so check the checkbox for "HTML Files (.htm)". Since we have an existing HTML file, the next dialog will be "New Project -- HTML Files". Click on the "Add..." button and select the HTML file that you created previously in the HTML folder. The window will look as:

Then click "Next >". Next the "New Project -- Finish" dialog will be shown, which looks as:

Just click on "Finish". Then the HTML Help Workshop window will look like:

HTML Help Workshop Window

Then the project file will be created. There will be tabs for the Project, Contents and the Index. Along the left (vertically) are buttons; the buttons depend on which tab is selected. In the Project tab are the following buttons:

1.  Change project options
2.  Add/Remove topic files
3.  Add/Modify window definitions
4.  HtmlHelp API information
5.  View HTML source
6.  Save project, contents, and index files
7.  Save all files and compile

Modifying the Project

Click on the Contents tab and a contents file will be created. Then click on the Index tab to create an index file. The Contents and Index files should be in the project directory but not in the HTML directory so be sure to use the correct directory when the file open dialog boxes are shown for them.

Then click on the Project tab to set options for the project. The top button on the left is the "Change project options" button; click it. In the Options window there are four tabs; on the General tab specify a title. The "Default File" text box should already have the filename of the first HTML file you listed for inclusion in the help file, as in the following:

Then click on the Files tab. You will see that the file names for the contents and index files created previously are already specified. I recommend selecting the option for "Automatically create contents file (.hhc) when compiling"; if the HTML files were created as I described previously then the contents will be generated automatically. The remaining project options (such as "Include keywords from HTML files") can be set later. The Files window should look as in the following:

The project can then be compiled. In the vertical row of buttons on the left the bottom button will "Save all files and compile"; click it. Then, assuming the compile works, you can view the compiled help file using another button that is in the toolbar along the top that has glasses as an icon.

Create a Window

It is not necessary to create a "window" but substantial customization of HTML Help windows is possible so you might want to do this. Windows within the help system can be customized in many ways and specifying a window to be used for the default window allows customizations that will affect the way the help window is shown. Click the "Add/Modify window definitions" button (the third in the vertical row on the left); a dialog box will prompt for a window name; I used "Main help". Next there will be a Window Types dialog box where you can customize the window in many ways. Then in the Project Options you need to specify the default window, but when there is one and only one window type then that type is used as the default. To provide a "Search" tab this window will be customized slightly.

Creating an Index

Creating an Index is a bit tricky but I hope it is easy using the following. Click on the Index tab in the project. The second button in the vertical toolbar on the left will have a key icon and will be for "Insert a keyword".

Click the insert keyword button and in the Keyword text box enter a line to be shown in the Index. Enter it as you want the line to appear in the index; it can be a single keyword but it can also be a phrase as is seen in other HTMLHelp files. Then click on the "Add" button and in the dialog box that is shown the only thing that is needed is to select the HTML filename of the page that the index item is to be associated with. You can add that file by clicking on "Ok" and then add another file by clicking on the "Add" button again. Note that if you list more than one file this way then when the reader of the help file selects that index item there will be a dialog box shown to select from.

If you need to have an index item with sub-items then you need to create an item with one or more pages associated with it, then create another item (to be a sub-item) with one or more pages associated with it and then simply use the button to indent the sub-item.

There is an undocumented way that Microsoft uses to create index entries automatically. If you put lines such as the following into the header portion of your HTML files then the help compiler will automatically create an index entry for the specified keyword for the page it exists in. There must be one line per keyword but each line will result in an entry in the index.

<meta Name="MS-HKWD" content="keyword">

Creating a Search Tab

To create a search tab:

• Create a stop list and add it to the project; see the documentation about that. The stop list is optional and to retain compatibility with all versions of HTML Help, the stop list must be less than 512 bytes in size.
• Select (check) the "Compile full-text search information" option in the Compiler tab of the project options.

Note that when the help is shown there will not be anything shown in the list of topic (results) until something is searched for.

References

Microsoft HTML Help 1.4

MSHelpWiki