There are three Windows help systems:
WinHelp is the original help system from 16-bit Windows. WinHelp help files have a HLP extension. Writing the source for a WinHelp help file is especially cumbersome; the source files must be in a RTF file format and must use specific word processing tags in specific ways and in ways that are not obvious or consistent with expectations.
HTMLHelp Version 1 files have a CHM extension. HTMLHelp help files are called Compiled Help files since they are actually many files gathered ("compiled") and compressed together. Usually most of the files are HTML files but not all are.
HTMLHelp Version 2 is new for .Net.
The remainder of this article is a brief introduction to using HTMLHelp.
The HTMLHelp SDK is not provided with Visual Studio, at least not version 6. So if you have not installed it separately then you need to. Go to Microsoft HTML Help 1.4 SDK to download the SDK and for much more information about the SDK.
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.
The first thing to do is to create directories for the project and the files. For VC programmers the conventional directory structure is:
VC Project directory
Debug
Help
HTML
Release
res
Where "VC Project directory" is whatever name your project is called. I assume that this will be similar for VB programmers but I am not sure. The "Help" directory is the main directory for your HTMLHelp project. It is conventional but not required to have the HTML files separate in the HTML subdirectory. If you use FrontPage to edit HTML files then you can make the HTML directory a web.
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.
I think it is easier to create at least one HTML file (in the HTML directory) before creating the HTMLHelp project; it is not required to do that though. If you are using FrontPage and want to use a web then create a web using the HTML directory as the web. The first file created can be and should be the default file that will contain the text of the first page shown. You should create a header using a H1 tag and at least one paragraph to start with. Then when that is created you can specify that filename in the project options; that is, the "Default file" in the General tab of the HTMLHelp project options.
Assuming you want a Table of Contents that appears as:
Application Name
Overview
Also, the "Application Name" page is the "Default file". Then the "Application Name" page will need to have a heading of "Application Name" with a H1 tag and "Overview" will have a heading of "Overview" with a H2 tag, all in the same page (file). Also the titles of the HTML pages need to be set to the text used in the headings.
If you want the Overview to be shown in a page separate from the default page, then you can make it a separate file, but it is more convenient to create the additional (non-default) pages after creating the project as described below.
Then execute the HTML Help Workshop. From "File | New" select "Project" from the list. Create the project in the "Help" directory.
A Wizard will:
Then the project file will be created. There will be tabs for the Project, Contents and the Index. 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. There is a vertical row of buttons on the left; the top one is for setting options for the project. In the options there are four tabs; on the General tab specify a title. The "Default File" text box should already have the filename of the first file HTML you listed for inclusion in the help file. 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 describe previously then the contents will be generated automatically. The remaining project options (such as "Include keywords from HTML files") can be set later. The project can then be compiled. In the vertical row of buttons on the left the bottom button will "Save all files and compile". 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.
It is not necessary to create a "window" but there is lot than can be done to customize HTML Help windows 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 I think that 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 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 probably 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.
I do not know how to create an index item without a page associated with it; I am as much of a beginner as you are for that.
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">
There is a way to create multilevel entries this way but I have not done that yet. If you search the internet you can probably find a description of doing that.
I am not sure how to do this. The following I think works. To create a search tab:
Note that when the help is shown there will not be anything shown in the list of topic (results) until something is searched for. Silly me, I thought the search tab was not working until I realized this.
I found the following that might also help but I have not read them yet.
The following are not Microsoft sites but have a lot of help with help.
See my Visual C++ Programmer Stuff page for more C++ stuff.