HTMLHelp

Creating Help Files Using HTMLHelp

A couple of years ago I wrote a tutorial on creating Help Files using WinHelp, this time around we will be creating help files using HTMLHelp. Like WinHelp HTMLHelp is free from Microsoft and you can download the file at the link below. You will also need HTML editor, while you can use notepad or any text editor, it's a lot easier if you use an WYSIWYG HTML editor. For those of you that do not have a HTML editor the link below has several free HTML editors, I cant recommend one over the other since I have not tested them. I my self use HomeSite.

HTMLHelp

HTML Editors

This month we will learn how to create a basic help file and how to add that file to your program. Once you compile your help file it can be used with either a VB, C++ or Delphi programs for Windows. The first thing you will notice that creating help files using HTML Help is a lot easier then using WinHelp, a LOT easier! So kick back and lets get started.

Setting Up Your Topics

Before you can use HTMLHelp we need to create topics and files and in order to do that we need a program. We will be using an old program of my called Personal Banker. This program allows you to keep your checking account in balance, PB has 3 main topics.

We will base our help file on the above topics. The first thing we will do is create 3 HTML files one for each of the main topics. With in each main topic will be a link for each of the submenus under the main topics. Figure 1-Figure 2

You will notice that the help topics are setup just as if you were creating a web site. Just like a web page every time you click on a link it will bring up that specific page. If we were to click on the Backup Database Topic then "Backup Database" help topic will be displayed.Figure 3

You will need to create HTML files for each of the sub topics in the 3 main topics. Example on the "File" main topic there could be 4 links, however I only created 3 topics links since everyone knows what Exit is so there's no need for instructions on that. (see figure 1)

Adding Images

Now that we have created our topics and help files there is one thing that was not explained in "Setting Up Your Topics". The one good thing about adding images to your help files is that it's very simple. If you are using a WYSIWYG it's as easy as clicking on a icon or you can use the IMG tag and enter the image by hand. Figure 4, Figure 5.

There's on thing that you should be aware of when adding images using your HTML editor, it will put the path that the image came from in the IMG tag code. Remember to remove this and only have the image name, the reason for this is that when you compile the help file while you may be able to view your help file the end user will not. They will get a error message telling the that the image can not be found. When you remove the full path and just use the image name then the compiler assumes that the image is the same path as the help file, which should be the case. Figure 6

HTML Help Workshop

Now that we have create our HTML files we will now compile them in to a help file. We will first go over the HTML Help Workshop software and familiarize ourselves with the interface. Figure 7

New - This will allow you to create the actual help file project. When you click "New" it will give you 5 choices, Project, Text, HTML File, Table of Content and Index.

Project - As stated selecting this will allow you to create your HTML Help project. It will also let you convert your WinHelp help file in to a HTMLHelp file. This will save you a lot of time if you want to create new help files from the old help files. It will ask you to name the project, in our case I named it PB. It will then as if you if you already created the files you want in the help file then specify. Since we already created our files we would check the HTML_files (.htm) box. It will then as you to add the files, so you would click the add button. Go to the directory where you save the html file you created select them and click ok, it will add all the files, then you would click the finish button. Figure 8

Text - This option will give you a notepad type interface.

HTML File - This will allow you to create a HTML file it will basically give you an HTML template so in fact you can use the HTML Workshop to create not only the final help file but to create your topics. Figure 9

Table of Content - That is just as the name states, it will create a table of content that will displayed on the left hand portion of the help screen. Figure 10

Index - This is what you would use to create A key word index, when you click on a key word it will take you to that topic.

Additional Features

Yesterday we went over the features that you are given when you create a New project. Today we will go over Compile, Decompile and CHM Information.

Compile - This option will compile your help project in to a Help file. It will compile the project when you select this option you will be presented with a dialog box asking for the project file to compile. You can also use the icon on the left hand side of the glasses, this will also bring up the compile dialog box. Figure 11

Decompile - This option does exactly what the name implies. If you lost all the files you use to create your Help file but you still have the CHM file then this will extract all the html files and images used in the construction of the help file.

CHM Information - This will give you all the information about your help file including the names and sizes of the html file used in the help file and when it was compiled. Figure 12

As this is a basic tutorial on creating help files these are the only options we well be concerned with at this time. But please take some time to get to familiarize yourself with the rest of the features in HTML Help Workshop.

Creating our Help File

Ok, we have created the HTML pages that will be our help file topics we have added the images we needed. Now it's time to put it all together and compile our help file.

Creating A Project

Start the HTMLHelp Workshop and under file select "New", then select "Project" click the next button since we will not be converting WinHelp help file. Use the Browse button to find the directory where you placed the help file topics that we created, type PB then click "Open". Since we already have our files created we will check the HTML_file(.htm) box and click the next button. We are now going to add our help topics to our help file, so click the add button and select all the help file topics and click "Open". The files you selected will be displayed in the listbox (Figure 13) then click next then click finish. The files will be added to the project and you will be ready to create your contents list. However before we do that we will set a default topic that the user will see when they first open the help file. When the program first compiles it will set the first html file on the list as the default, in our case it's reports.html. Now we can use one of the file topics we already have or create a starter page. I myself have a quick start guide that is displayed when you first open the help file, but it's really up to you. To make things simple we will use the filemenu.html as the default topic. So under "Options" double click on the "Default topic" then under the "Default file" combo box select "filemenu.html" then click ok. At this point you can compile the help file and when you launch the help file it will show the File Menu help topic. Figure 14

The Table of Content

Now that we have our help file compiled we now need a table of content. The way it is now there is now way to view the other topics since we did not have a start page with links to the other topics. However that could be another alternative, but we are going to create a table of content just so you will know how to do so in the future.

Now load the HTML Help Workshop, and load the PB.hhp project, it should look like this. Now click on the "Contents" tab, a dialog box will pop up asking you if you want to create a new contents file or open an existing one, select new and click ok. The "Save As" dialog box will pop up name the contents file and click save, name the file pb.hhc. On the left had side is a series of buttons, click the second button that has the file folder icon. A dialog box will popup in the "Entry title" text box type; Post Payments (Figure 15). Then click the "Add" button in the list box select "Post Payments" ( Figure 16) and click ok, then click ok again and it will add that to your table of content. Do this for the Post Payment, Post Deposit and Balance Account topics, when you done it should look like this. Figure 17

Now compile the file it should look like this. You will notice our table of content list, clicking on any of the topics will take you to that help file. You will also notice that the File Menu is displayed when the help file first opens, this was the file we set as our default.

Adding Key Words

Adding key words is as easy as adding a table of contents. To add key words click on the Index tab A dialog box will pop up asking you if you want to create a new index or edit an existing one, check the new option and the index dialog box will open (Figure 18). Now click on the "Key" icon a dialog box will pop up, enter the key word you want to add the click the "Add" button and select the topic that has the key word included. One example would be the key word "Post Check", you can select the "Post" topic so that if the end user enters a key word search for post check it will take them to the Post Payments topic (Figure 19 Figure 20).

You can make the key words detailed by creating key word topics and selecting them when, this way instead of viewing the full topics you can only view the key word topic.

The Completed Help File

We have created our topics using HTML, we have gone over the features of the HTML Help Workshop. We have created out table of contents and our key word searches and now it time to compile and complete our help file.

Open the HTML Help Workshop, and load the PB.hhp file. At the top of HTML Help is a group of icons, faucet and glasses to compile and view our help file. Now click on the faucet the program a dialog box will pop up asking you if you want to create a compiled file, find the PB.hhp file and click "Open". then click the "Compile" button, it will compile the help file and it will look like this. As you can see it will give your all the information about your help file, including how many topics, links and images you have.

You can download this project at the link below, it will have all the topics and images used to create this help file including the help file itself.

HTML Help Project

Adding your help file to your application

Now that we have created our help file we need to include it in our application. There are several ways to add the help file to your application, I will show you one for VB. However the links below has tutorials on adding the help file to your application if your using VB, C++ or Delphi.

Adding Help to VB Application

This code assumes that you have a menu item for help.

Private Sub mnuhlp1_Click()
Dim RetVal
RetVal = Shell("Hh.exe " & App.Path & "\PB.chm", 1)
End Sub

http://www.smountain.com/resource/VBHTMLHelp.pdf

Add Help to C++ Application

http://www.smountain.com/resource/CPPHTMLHelp.pdf

Add Help to a Delphi Application

http://www.helpware.net/delphi/index.html

Other HTMLHelp Resources

http://www.helpmaster.de/hh-authoringtools.htm

http://helpware.net/

Conclusion

This will conclude our Hands On HTMLHelp, I hope it was informative and help full.