Using the HTML Help Workshop
A help file can be used either for interactive help, or as an online manual. In this article, I will give an overview over creating help files in the new help format (CHM), for Visual FoxPro 6 and later. This article is introductory and assumes no prior knowledge of the Help Compiler, or of HTML coding.
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:
- Install the HTML Help Compiler. You can find it in folder HTMLHELP, on your Visual FoxPro CD.
- In Windows Explorer, create a folder c:\MyHelpFolder.
- Start the Help Compiler.
- Select "File | New". Select "Project".
- Leave the checkbox "Convert WinHelp project" blank (we want to create a new project for now), and click on "Next".
- Under "Specify the name of your project file, and where you would like it to be created", specify a folder and a project name: c:\MyHelpFolder\MyHelp. Click on "Next".
- Under "existing files", leave everything blank; we didn't create the required files yet. Click on "Next".
- Click on "Finish".
- In the HTML Help Compiler, select "File | New". Select HTML file. For the title, write "Main Menu", and click "OK". Write some text between <BODY> and </BODY>. Be sure to start each paragraph with <P> - the HTML code for a new paragraph. The text should describe the main menu.
- Save the file: "File | Save". Call it MainMenu.htm.
- Repeat the previous steps, and write some short text to describe the "File" menu. Save as FileMenu.htm.
- Repeat for the "Edit" menu, and save as "EditMenu.htm".
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.)
- Click on the "Contents" tab. Confirm that you want to create a new table of contents, and accept the suggested name ("Table of Contents.hhc").
- Click on the button "Insert a heading" (the second from the top, on the vertical toolbar). Under "title", write "Main Menu" (this is the text the user will see in the table of contents). Click on the "Add" button, followed by the "Browse" button, select the file "MainMenu.htm", and click on the two "OK" buttons.
- Click on the button "Insert a page" (the third from the top, on the vertical toolbar). You will be asked whether you want the entry at the beginning of the Table of Contents. Answer "No". Under "Entry title", write "File Menu". Click on "Add" and "Browse", select file "FileMenu.htm", and click on "OK" twice.
- Repeat for the Edit menu.
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:
- While Microsoft Word can save in HTML format, it inserts so many unneeded codes, that it becomes very cumbersome to later edit those same files with any other programs. The extra codes can also adversely affect the way the HTML page looks on screen. I found that MS-Word has some additional problems with HTML files, too. Therefore, I definitely do not recommend using it as a WYSIWYG HTML editor. (Using it as a text editor, where you insert all the HTML codes and then save as text-only, is quite a different issue - here, you can benefit from features like spell-checking, multiple undo, and others.)
- FrontPage Express comes free with some versions of Internet Explorer. However, it is not included in the default installation.
- Or, you can go to download sites like www.download.com, and search for popular HTML editors.
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.
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 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.
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:
If you didn't do so already, write the HTML file to describe the form, as described previously. For this example, call it MyForm.htm.
To activate the header file, in the Help Compiler click on the fourth button on the vertical toolbar (HtmlHelp API information), and in the map section select the header file (context.h). This has to be done only once.
Open the project file as a text-file (open it with NotePad), find or create the [ALIAS] section, and include a command like: IDH_MYFORM = MyForm.htm. According to a KnowledgeBase article, you can get into trouble if you try to add an alias through the HTML Help Compiler - therefore, I always open the project in text mode.
Open the project file in the Help Compiler, and add the help topic to the Table of Contents (as outlined above).
Compile and test.
- In an include file (I call it context.h), add a line like #DEFINE IDH_MYFORM 1. The constant should start with "IDH_". Both the named constant and the number must be unique for each form.
- Include this include file (or another include file, which references it) in the form.
- In the form, include the following statement in the Init() method: This.HelpContextID = IDH_MYFORM.
To open the correct topic from a Visual FoxPro form, I use a command like HELP ID ThisForm.HelpContextID.
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.
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.