Article sample: makingofhelp.chm
Introduction
Sooner or later you will want to add a help file to your application. You had better do that sooner rather than later if other people are to use your applications. People might not understand your program, even if it's very simple. Things which are painfully obvious to you might very well be a complete mystery to others.
If you don't have the slightest idea what your help file might look like when it's finished, take a look at the one from Internet Explorer for instance. Did you like that? That's great, because yours will look very similar when it's finished.
Before you start
Before you start with this walkthrough, you will need to write your help content on .htm files. Microsoft FrontPage works just fine for this. You can also use Microsoft Word, but then make sure that you save your pages as Web Pages.
You will also have to download and install Microsoft HTML Workshop. It's free, so there's no reason why you shouldn't have this.
Things to remember
I really don't want bore you with this, but help files, including those from large and famous software companies, are often very difficult to understand. Such files don't help much, but they do confuse most users. Since bad writing styles are often repeated, many users don't even bother looking at them.
A help file is not the right place to brag with complicated vocabulary and/or grammar. Ah, you want to brag? Write a novel; you might even get rich with this. Generally speaking, if you can put things across so that even fourth graders can understand it, then you've met the right style. People don't want to think when they're reading a help file; they want to understand, and they want it fast.
It's probably a good idea to think of a help file as an essay. One page should make one topic; similarly to a paragraph in an essay. Don't go off-topic or link to topics which have nothing to do with what you're talking about. If you catch yourself linking to a "related topic", then you have - most probably - gone wrong earlier. It's similar to the essay: you wouldn't tell a reader in paragraph one to look at paragraph five for more information, would you? It makes a really bad impression on most readers, especially if the reader is an English teacher like me. Aside from the bad impression, it makes your help file confusing and of little use.
Creating the Help Project
For this step I assume you're ready to go. That means, you have written several .htm files and have saved them to the same directory (folder). You should also have Microsoft HTML Help Workshop installed.
Click "Start" and open your programs menu. Point to "HTML Help Workshop". On the fly-out menu, make sure you select "HTML Help Workshop" and not "HTML Help Image Editor". The window you will see should look like the one in Figure 01.
(Figure 01)
From the "File" menu, select "New" or click the button shown in Figure 02.
(Figure 02)
The "New" window will appear as shown in Figure 03.
(Figure 03)
By default, "Project" should be selected. If it isn't, click it once to select the item and then click "OK".
This will bring up the wizard as shown in Figure 04.
(Figure 04)
Since we do not have any WinHelp project to convert, click "Next". This will bring you to the "Destination" window as shown in Figure 05.
(Figure 05)
Type the name for your help file in the text box. I've used "Help Sample", but of course you will use something more meaningful for your project. Click the "Browse ..." button and go to the directory where you have saved your .htm files. Type "Help Sample" or whatever you want to call it and then click "Open". The complete path should now be displayed in the text box which reads "Help Sample" in Figure 05.
When you click "Next", you will come to the "Existing Files" window as you can see in Figure 06.
(Figure 06)
Check "HTML files [.htm]" so that these files will be added automatically. You could also add them manually - one by one - later, but to be honest, this is a real pain in the [beep]. Click next to get to the "HTML Files" window as shown in Figure 07.
(Figure 07)
Click "Add ..." and the directory where you have your .htm files should open. If this isn't the case, you will have to browse to get there. Select all the files you want to add and click "Open". All your files should now appear here as you can see in Figure 08.
(Figure 08)
Check that all your files are listed and then hit "Next". You will see the "Finish" window as shown in Figure 09.
(Figure 09)
You still have a chance to make changes. If you're sure that everything's okay, click "Finish". This will take you back to the main window as shown in Figure 10.
(Figure 10)
Take a look at the "Options" and "Files". You most probably will have to change some settings. Click the "Options" button as Figure 11 shows.
(Figure 11)
As you can see in Figure 12, I have changed the "Title", the "Default file", and the "Language" settings. You should also go through the other tabs; maybe you want to change things there, too. I'm not going through all the details as this is a tutorial on how to make a simple help file. Everything beyond that would get a bit large. Besides, programmers are intelligent and independent individuals and don't need to be told every little detail, right?
(Figure 12)
When you're finished with this, click the "OK" button. You should see the changes in the left pane of the main window. Click the "Compile" button as shown in Figure 13. Important: When you recompile your file later, make sure that the compiled help file is closed. Otherwise you will get an error message.
(Figure 13)
In the "Create a Compiled File" window, as shown in Figure 14, you could check both checkboxes depending on which options you prefer. Later, when you create more help files, you should check that the correct project file appears in the combo box.
(Figure 14)
Click "Compile" and take a look at the log file which will be displayed in the right pane. Then click the "View compiled file" button shown in Figure 15.
(Figure 15)
In the "View compiled file" window, shown in Figure 16, click browse and then double click the compiled help file. Click the "View" button to see it.
(Figure 16)
Hmm, it's not yet what I promised you, right? But we've just started and there's still some work to do.
Adding Content
Click the "Contents" tab in the main window. This will bring up another dialog. Make sure the radio button that reads "Create a new contents file" is selected and click "OK". You can accept the default name "Table of Contents" or change it to whatever you think appropriate. When you have done so, click "Save".
Click the "Insert a heading" button shown in Figure 17.
(Figure 17)
The "Table of Contents Entry" window will prompt you to provide an "Entry Title" for your heading. Type something appropriate and click the "OK" button.
When you have your first heading, click the "Insert a page" button shown in Figure 18.
(Figure 18)
A message box will ask you, "Do you want to insert this entry at the beginning of the table of contents?" Click No as we want the entry within our first heading.
In the "Table of Contents" window, click "Add ..." and select a page from the list. Click "OK" and provide an "Entry Title" in the corresponding text box. Click "OK" or just press Enter. Repeat this procedure until you have added all the pages related to the heading. You could then add another heading and repeat the procedure until all your content is added.
When you add the second heading, it will automatically become a subheading. That means it will be indented. If you close your heading, this subheading will be closed, too. If this is what you want, go ahead. Otherwise, use the "move selection right/left" buttons, shown in Figure 19, to adjust this.
(Figure 19)
To adjust the sequence, select a title and use the up/down buttons as shown in Figure 20. Just don't move the pages out of the heading unless this is what you want. You can also move entire folders with these buttons. But then, they might become subheadings again. In this case, refer to my explanation before Figure 19.
(Figure 20)
Compile and view your help file as you did previously. You might have to click the "Show" button in the upper left to see the table of contents. Aha, now we're getting somewhere! If you've done everything right, your little help file could look like the one shown in Figure 21.
(Figure 21)
Adding Index
Click the "Index" tab. The "Index Not Specified" window will come up as you can see in Figure 22.
(Figure 22)
Make sure the "Create a new index file" radio button is selected and click "OK". You will be prompted to save the file. You can accept the default name "Index" or type anything you like. Then save the index.
Click the "Insert a keyword" button as shown in Figure 23.
(Figure 23)
In the "Index Entry" window, click the "Add ..." button to select a file and click "OK". Then enter an appropriate keyword in the corresponding text box. Click "OK" and the keyword should be added. Repeat this until you have added all your files with appropriate keywords. When you add the second keyword, you will be asked - again - if you want to have the entry at the beginning. Here, it doesn't matter what you choose since we will sort the keywords alphabetically when we're done.
When you're finished with adding all your files and keywords, click the "Sort keywords alphabetically" button as shown in Figure 24.
(Figure 24)
Compile and view your help file again. You should now see the index tab will look similar to the one shown in Figure 25.
(Figure 25)
Click the index tab and browse through the entries to make sure everything is as you wanted. Now the help file is finished, but you still have to get it into your program.
Into the program
Copy the compiled help file to the bin folder of your program and get ready to write the code of your choice. There are many different ways to display your help file, and I cannot tell whether there are more possibilities than these. If you know about other ways to display help files, please post a short message.
With the first three possibilities I assume you have inserted a Help Provider. For the example, I have renamed "HelpProvider1" to "hlpHelp". For this to work, you also have to enter your help file name into the Help Name Space property in the Properties window. Since I named my help file "Help Sample", I typed Help Sample.chm into this property.
1. Display the index tab of your help file:
Help.ShowHelpIndex(Me, hlpHelp.HelpNamespace)
2. Display the contents tab of your help file:
Help.ShowHelp(Me, hlpHelp.HelpNamespace)
3. Display the search tab of your help file:
Help.ShowHelp(Me, hlpHelp.HelpNamespace, _
HelpNavigator.Find, "")
Don't worry if your file doesn't have a search tab. This won't throw you an exception.
The newer way to open a help file comes in the following. It's not necessary to insert a help provider.
System.Diagnostics.Process.Start _
(Application.StartupPath & "Sample.chm")
Some older way, known to most VB .OLD programmers, is using Shell. Also here, no help provider is necessary.
Call Shell("hh.exe " & Application.StartupPath & _
"Sample.chm", AppWinStyle.NormalFocus)
This way gives you six different options. These are:
- Hide
- MaximizedFocus
- MinimizedFocus
- MinimizedNoFocus
- NormalFocus
- NormalNoFocus
You can choose one of these ways after AppWinStyle. Just try them all and decide for yourself which one you want to use.
You can download the Help Sample to this tutorial which also includes an appropriate icon in case you don't have one yet.
I hope this helps some people making their simple help files. And, who knows, you could go beyond this very simple beginning and try out things I have not included here. There are tons of options.
Last, but certainly not least, I'd like to thank Ged Mead (XTab) and CanOz for their invaluable contributions.