Overview
The new help format, recommended by Microsoft, is based on HTML files. The output is a file with CHM extension. New Microsoft products, for instance newer versions of MS-Office, use this help format.
The main advantage of this new help format, in my opinion, is that it is much easier to create than the old HLP help files. Its main disadvantage is that support for this format has to be installed separately - support for the old HLP format came included with Windows, even before Windows 95.
The program required to convert the HTML files to a CHM file is included on the Visual FoxPro 6 CD. It can also be downloaded for free from Microsoft. The steps required to create the help file include creating HTML files, creating or obtaining images, creating a table of contents, including your individual help files into the help system, compiling, and testing. I did my testing in VFP 6 only.
This article describes technical aspects only. The - undoubtedly important - issues of planning your help system, good writing style, etc., are not treated here.
A quick tutorial
Let's start by building a small help system. First, we must create an empty help project:
The next step is to create a table of contents, and include the files you just created. The HTML file for the Main Menu will be included as a "heading", the two submenus as "pages" under this heading. (Using the buttons in the Help Compiler, it is very simple to create additional levels of headings.)
We are almost finished now. To test your project, you can click on "Compile" (the third button on the top toolbar). If there are no errors, you can now click on "view compiled file" (if it didn't appear automatically), and see the result.
One little problem is that no files appears initially selected. Go back to the Help Compiler, select the "Project" tab, and click on the "Properties" button (the first in the vertical toolbar). Under the "General" tab, click on "Default file", and type "MainMenu.htm". Recompile, and check the result.
Creating the HTML files
Since the entire help system is based on HTML files, one of our major tasks is to create the HTML files - one for each help topic. If you ever used a word processor, you already have most of the required skills.
As you saw in the previous tutorial, the HTML Help Compiler has a built-in text editor. A pleasant feature is that when you create a new HTML file with it, some important HTML keywords are already inserted. Of course, you can edit an HTML file with any other text editor, too, including Microsoft Word (opening and saving as "Text only").
If you feel more comfortable with a WYSIWYG editor, which hides most of the HTML codes from you, you have several options:
HTML Codes
In case you want to learn to code HTML yourself, I will include some of the most important HTML concepts. Otherwise, you may want to skip this section. Please note that some of these codes are also very useful when writing messages in the Universal Thread.
An HTML document is a text-only document - any special codes required can be inserted and read with any text editor.
All HTML codes are enclosed within angle brackets. For instance, to start bold, you use the <B> symbol.
Many HTML codes come in pairs. For instance, to indicate the end of the bold text, use </B>. You can understand this as "end bold". However, not all codes have to come in pairs.
An HTML document starts with <HTML> and ends with </HTML>.
The document is divided into two main sections: the header, and the body.
The header starts with <HEAD> and ends with </HEAD>. Within the header, you have a title between <TITLE> and </TITLE>, that will be displayed as a window title in the browser, if the HTML document is opened independently. (It seems that this text is not really relevant for a help system, which supersedes this title with a title you choose, throughout the entire help system.)
The body contains your main text, tables, references to graphics, etc.
Every paragraph starts with <P>. The end-of-paragraph code, </P>, is optional. Note that if you press ENTER in your text, this will not start a new paragraph - the browser will combine the lines. The only way to start a new line is with the <P> symbol, or with some other special HTML codes, for instance, headings.
<PRE> and </PRE> is used for "pre-formatted text" - in normal paragraphs, spaces and line breaks are not respected, in pre-formatted text, they are. Also, a fixed-width font is used, and word-wrap is turned off. All this makes pre-formatted text ideal for showing program code. (You should always use this code when posting program code in a Universal Thread message, to make it more readable.)
A few additional codes will be introduced later, in their corresponding sections.
Images
Being based on HTML, the help system can use both JPG and GIF images. Both are useful for different purposes:
GIF images are compressed images. No quality is lost in the compression, but a GIF image can only have 256 different colors. GIF images are excellent for screenshots.
JPG (or JPEG) images use lossy compression. That means that in most programs, some quality is lost when saving an image to JPG. This helps save space. The loss in quality is usually imperceptible in a photograph. (When saving to JPG, most image-editing programs allow you to adjust the amount of quality lost; this means choosing between more quality vs. a smaller file.) A JPG file can use millions of color simultaneously. All this makes JPG files ideal for photographs.
For obtaining screenshots, you need some screen capture utility. Without additional software, you can press PrtScr (equivalent of "Copy to Clipboard", for the image of the entire screen), or Alt-PrtScr (current window only), and edit the resulting image in Paint - for instance, cut out the rectangular region that you want to include in your help file.
The HTML Help Compiler installation includes an screen capture and graphic conversion utility, which you can use instead.
Whether the final destination be a Website or a CHM file, in HTML, images are stored as separate graphic files. In your HTML text, include a code like <IMG SRC="MyScreenshot.gif">. Or use the "Image" button of your favorite HTML editor, and fill in the options in the dialog.
Hyperlinks
Hyperlinks provide a way to jump to related topics. Use the hyperlink button of your HTML editor, and fill in the options in the dialog, or use HTML code like <A HREF="AnotherHelpFile.htm">User Sees This Text</A>. (Hint: In the Universal Thread, you can use this code to put a hyperlink into your dynamic signature.)
Note that it is also possible to jump to a specific place in a document, using bookmarks. For instance, I use this feature for glossary terms. I usually leave the details to my HTML editor.
Context-sensitive help
The idea of context-sensitive help is that if the user presses the help key (F1), he will see a help topic relevant to the form that is currently on top, or even to the individual object that has the focus.
It is up to the developer to decide what level of detail he wants (form, or individual objects).
I will assume, in the following explanation, that you have one HTML help file for each form only.
For each form, you need to follow these steps:
To open the correct topic from a Visual FoxPro form, I use a command like HELP ID ThisForm.HelpContextID.
Installing Help
The main problem with the new help format (CHM), as explained previously, is that the support for help is not included in the operating system.
The easiest way to install help support is with the Visual FoxPro Setup Wizard. In Step 2 of the setup wizard, simply mark the checkbox for HTML Help Engine.
The setup program you create will check whether Internet Explorer is installed. Internet Explorer version 4 or later is required for the help system to work. Internet Explorer doesn't have to be the default browser, but it has to be installed - other browsers can't open the CHM file.
Summary
I hope this brief introduction helped you get an overview over creating help files. Help files in the new CHM format are relatively easy to create, and easy to use for the end-user. And a decent documentation is an important part of a complete computer system.
