Al is a DDJ contributing editor. He can be reached through the DDJ offices or on CompuServe at 71101,1262.
To be taken seriously, a Windows application must provide online help. Users have come to expect it, and developers have little choice but to provide it. However, like staff meetings, program documentation, and user's guides, it's a task that programmers approach as willingly as they would a root canal. But like it or not, most Windows developers must eventually build a help database. Fortunately, Windows includes WINHELP.EXE, an application that displays online, context-sensitive help in a standard format. You design a help database and build the hooks into the application. WINHELP does the rest.
Building a help database, however, is no easy task. If you're lucky, your boss hires a professional tech writer to do most of it. There is more to the job than writing the words and composing the pictures. You use a number of unrelated tools to convert the help words and graphics into a database format that WINHELP recognizes. You can work with these tools in their native autonomous environments or use a Help authoring tool to integrate them into a project-oriented toolset. This article describes the components of a Windows help database, addresses the manual procedures for building one, and discusses three Help authoring tools that ease the process. One tool, the Windows Help Author, comes as an unsupported application on the Microsoft Developer Network (MSDN) CD. The other two, Windows Help Magician from Software Interphase and RoboHelp from Blue Sky Software, are commercial tools from third-party vendors.
WINHELP is an independent Windows application that comes with Windows. Developers use it to provide online help similar in look and feel to that of other Windows applications. WINHELP displays help text and graphics from databases that conform to a prescribed format. The format supports hypertext links, keyword searches, graphical displays and controls, and navigational controls. Applications programs associate their run-time contexts with specific topics in the Help database. The developer composes the help database, assigns run-time context identifiers to the help topics, and puts the associated context-sensitive hooks in the applications code.
A help database can have text, graphics, motion video, and sound. The text can include highlighted phrases that you click on to pop up informational windows or jump to other topics in the text. Graphical elements such as tool-bar buttons, icons, and screen shots can be displayed and clicked on. The help document can talk, display pictures, play music, and show movie clips. There is an automatic table of contents and a keyword search feature. There are navigation functions that jump forward and backward through the topics. The user can place and retrieve bookmarks in the text. All of these features are implemented by WINHELP based on a database that the developer builds.
Although WINHELP typically provides online help to applications, its hypertext, multimedia, and navigational features make it useful for presenting other kinds of information. You can run WINHELP either from within an application, or as a stand-alone program and command it to display text and graphics from any conforming database. WINHELP is commonly used for online reference and users' documentation for compilers and other applications. When you see a Program Manager group with one or more prominent yellow question-mark icons, there is a good chance that they each run WINHELP to display a different documentation database. There are even "readme" files implemented as help databases.
Building a help database involves several tools. You need a word processor that reads and writes the so-called "rich-text format" (RTF), which is an abominable concoction of embedded ASCII tokens that define how a document should appear. The RTF editor is used to compose the help database. Theoretically, you could use an ASCII text editor to build an RTF document, but it's not advisable. You're better off using a word processor that works with the format and displays comprehensible text on the screen.
A second text editor, such as Notepad, that works with ASCII text maintains the help project file, which describes various components in the database. If your database includes graphics, you need a program to produce bitmap files. If the user is to make selections by clicking on parts of the graphics, you need the Hot-Shot Editor. The Help Compiler reads the project, text, and bitmap files and compiles the help database into the format that WINHELP expects. (The Help Compiler and Hot-Shot Editor are bundled with most Windows software-development environments and are included in the SDK.) Finally, you need your own software-development environment to put help context identifiers into the application.
Among the project components you'll use when building a help database are:
Help Project File. A help database uses an ASCII text project file with the .HPJ filename extension. The project file contains options for the Help Compiler, including the name of the .RTF text files, and the title and size of the help window. It also associates string topic identifiers that you place in the help text with integer context identifiers in the programs.
Help Text. The help text contains the narrative text for the help database, tokens that specify the filenames and position for graphics, topic names and identifiers, and the linkages for hypertext references and keyword associations.
The RTF word processor must be able to encode double-underlined and hidden text and insert footnotes into the document, all by using RTF protocols. Footnotes, which are tagged with $, #, and K characters and appear just ahead of the title for each topic, provide mnemonic identifiers for the topic, titles for the table of contents, and keywords for the search. Underlined text identifies hypertext phrases. Hidden text immediately follows the hypertext phrases and specifies the link's mnemonic identifier. Word for Windows 2.0 and Ami Professional both have these capabilities.
Multimedia. A help database can include graphics, sound bites, and movie clips. You include these elements by putting tokens in the text that identify what they are and their filenames. For example, to insert a bitmap you put the following token into the text at the character position where you want the upper-left corner of the bitmap to show:
{bmc dolly.bmp}The bmc keyword specifies a bitmap. dolly.bmp is the name of the file in this example that contains the bitmap. The Help Compiler uses the token to build the graphic rendering into the database.
If the user clicks on a graphic to jump to another topic, you underline the token and add a hidden topic identifier to link to the topic. If parts of the same graphic point to different jump links, you use the Hot-Shot Editor to identify the coordinates of each jump area. For example, I put a picture of the application's tool bar in the help database and used each tool button to jump to the topic that describes its function. A weakness of the help development system is that graphics in the database slow the Help Compiler down to a crawl when you use the compression options to build the database. A big help file with many large pictures can take hours to compile.
Most help databases support context-sensitive help. If they do not, the user must start at a table of contents or do a keyword search to find a particular help topic. By associating help topics in the database with menu selections, dialog boxes, controls, and other application-specific contexts, you give the user the ability to go directly to the help topic that discusses the currently selected application context. For example, suppose that you assign context identifier 3 to the EDIT_MENU identifier. These are arbitrary values that you decide to use. In your program, you associate the integer 3 with the Edit menu label on the menu bar. In the help text, you associate the EDIT_MENU identifier with the topic in the text that explains the menu. When the user selects that menu and asks for help, winhelp.exe displays the associated topic.
To integrate a help database with an application, you modify the source code to specify the database name and to associate context identifiers with different parts of the application. How you do this depends on the programming language. Visual Basic's Options/Project menu opens the Project Options dialog box where you add the name of the help database. The Menu Design Window includes a HelpContextID field for the numeric value associated with the associated help topic. The Properties windows for the application's controls include similar HelpContextID fields.
A C program that uses the Windows SDK API intercepts the WM_KEYDOWN message and watches for the F1 key, either from the application window's processing module or by using the SetWindowsHookEx function to install a filter function that intercepts messages to dialog boxes. Once the key is pressed, the program calls the SDK's WinHelp function passing the name of the help database and the context identifier number.
Microsoft Foundation Classes programmers associate help contexts with controls using the MAKEHM tool, which constructs topic mnemonics from the source-code control identifiers and assigns context identifiers to them. The message map associates the Windows ID_
HELP message to CWinApp::OnHelp. AppWizard builds this framework automatically when you elect to include context-sensitive help in your application.
The Windows Program Manager has features that help organize the tools into what approaches an integrated fashion. Recently I worked on a help database for a Visual Basic application. I wanted VB and the help-authoring tools available at the same time so that I could put context identifiers in the program while I wrote topics in the help database.
I set up a Program Manager group for the project. An icon runs Visual Basic with the application's makefile on the command line. That takes care of the software-development side of the project. Another icon runs Notepad to edit the help project file. A Word for Windows icon starts Word to edit the RTF text file. An MS-DOS prompt icon starts a DOS batch file that runs the Help Compiler. I used Paintbrush to build and change bitmaps; it has an icon in the Program Manager group. Finally, an icon runs WINHELP itself to view the help document during each stage of its development. These tools sit together as Program Items in a Program Group with the startup subdirectories and command-line document files built into their properties. Thus, not only do I avoid rummaging through all of the groups to find and run them, but they start up with the help files loaded and ready to modify.
The manual approach works, but it is not perfect. Getting into and out of Word involves telling Word each time to convert the RTF format. The help document in Word does not resemble the display that WINHELP uses. You get neither a visual tool nor WYSIWYG. To see the real thing, you must run the Help Compiler and compile the whole database, which can take a long time. Inserting the correct footnote tokens with the correct footnote values is a tedious and error-prone process. Remember that you are using the features of a word processor to create links and chains in a textual database, a text editor to associate the link identifiers with numbers in the project file, and a software-development environment to put the numbers in the source code. There are no built-in integrity checks. Nothing ensures that you properly coordinate the contexts and topic identifiers among the three files. Some, but not all, of these problems go away when you use a help-authoring tool.
The Microsoft Developer Network CD contains an "Unsupported Tools and Utilities" section that includes a program named "Help Author," which is easy to use and well documented. The MSDN CD-ROM includes as a bonus an extensive Help Authoring Guide that covers the creative side of the job.
Help Author has two parts: an application named "Help Project Editor" and a Word for Windows template. The Help Project Editor uses dialog boxes to collect the information for the ASCII project file. You don't have to deal with that file again. It also automates the interface with Word, launching it with the template installed and the RTF file loaded. A help database can contain more than one RTF file, and Help Project Editor keeps them in a list. You can also launch the Help Compiler and WINHELP to view the currently compiled database.
The Word template adds three tool buttons to the Word tool bar. The first one opens a dialog box that lets you change the footnote values in the current topic. You can add, change, and delete the topic's title, context mnemonic string, keywords, browse sequence, and so on, all without having to deal with Word's footnote commands. The second tool button opens a dialog box that lets you insert jump and pop-up links into the database, automatically applying the underlined and hidden text attributes. If you select a phrase that is already in the text, the operation uses it. Otherwise it inserts whatever you put in the dialog box as the link phrase.
The third tool button compiles only the current topic into a temporary help database and calls WINHELP to display it. You preview a topic--text, graphics, sound, and movies--exactly as the user sees it and without recompiling the entire database. What you see in Word and what WINHELP displays is usually quite different. You need to view your progress in small increments, and this feature supports that need. It is Help Author's strongest advantage over the other tools, and anyone who develops a sizable help database wants this capability. The other tools do not have it.
Help Author does not integrate graphics and multimedia tools. You still have to launch them yourself and write their files into the proper subdirectory so that the Help Compiler finds them.
An amusing side to Help Author is that its own help database has context errors. Most of the Help buttons on its dialog boxes link to help topics that do not exist, although there are topics in the database to cover the functions of the dialog boxes. Nonetheless, Help Author smooths several of the wrinkles out of the manual procedure, automates most of the tedium of using Word to build the database, and is well worth trying. As a Windows developer, you should have the MSDN CD-ROM, anyway. Help Author is a bonus.
Windows Help Magician from Software Interphase has some good features, some bugs, and some annoying quirks. Among its quirks is that the setup includes a package called "Bitmap Magician." Its purpose is to let you build a pseudofont by converting the characters in an existing font into bitmaps that you can include in the help database. Help Compiler uses only a few fonts and doesn't accept all of the characters in the fonts it does allow. For example, you can put the trademark character in the text, but the Help Compiler deletes it from the help database. Bitmap Magician solves that problem.
When you run it, Bitmap Magician asks you to select a font. When you do, it says that there was an "overflow" with no explanation of what that means. Next, you learn that you are looking at only a demo version. The dialog advises you how to order the real thing. When you acknowledge that piece of good news, the program changes the mouse cursor to an hourglass and leaves it that way. Most Windows users would think that the system is hung up. Not really. You can use the hourglass cursor as if it were an arrow. Close the program, delete its icons from the Program Manager group and proceed to the Help Magician itself.
The second annoyance is the overall appearance of Help Magician's windows. The design is an example of a designer gone wild with enthusiasm over 3-D sculptured controls but without the design skills to know how to use them. Everything in the application window and all of the menus and dialog boxes are broadly sculptured. I understand that this is a matter of taste, but I have never seen anything quite like this. There is no menu bar, only a big, fat, sculptured tool bar. When you punch it, it pulls down a menu, also sculptured. The menus use tool buttons. There are the usual File, Edit, Options, Help, and other menus, but they are all represented by ugly tool buttons. The real tool bar is sculpted at the bottom of the window. The overall appearance detracts from the program's functionality.
Help Magician works with its own database format while you compose the help information. Then it converts to RTF format to run the Help Compiler. It launches the word processor of your choice but does not provide templates.
Help Magician has its own editor. That's a good idea, but it's not particularly well implemented. Text that you select for titles and links is surrounded by vertical bars. The vertical bars come in pairs and have to be balanced. You cannot distinguish a starting vertical bar from its terminating vertical bar in a pair. You cannot distinguish two sets of different pairs of vertical bars. A help topic with centered or justified text, a title, and some jump links displays with a mélange of pairs of vertical bars. It's hard to read.
I went through the tutorial process and then tried to add a MIDI sound bite to the tutorial's help document. Somehow I messed up the database. Somehow the MIDI insertion upset the balance of the vertical bars in the line of text. I could not build the RTF file or delete the line. Help Magician stubbornly issued error messages no matter what I tried. Finally, I deleted the entire topic, resulting in lost work.
Next I moved to my own project and imported the RTF file that I built using the manual procedure and Help Author. Without making any changes, I tried to rebuild the Help Magician database into a new RTF file. Help Magician reported another unbalanced marker, this time telling me that I could delete it with a Ctrl+bracket key combination. It didn't tell me that before. I don't know where the unbalanced marker came from. I looked at the original RTF file, and everything looked okay. I deleted the unbalanced marker and saved the RTF file.
Help Magician uses a single-font edit box, and your view of the help text is completely unlike what it is going to look like in a help window, far more so than if you are using Word. Centered text is not centered, and margins are not shown. Those distracting vertical bars are everywhere. To move from topic to topic, you have to change the page number in an edit box at the bottom of the screen and press the Enter key.
There is no preview mode. You can test the database, which displays the help in the same single-font, vertical-bar format and lets you exercise the jumps and popups. However, to see the real thing, you must compile the entire database and run WINHELP.
In one place, the RTF import mangled a graphic token. You could see where some of the RTF protocols were exposed as if they were text. The result was that the Help Compiler could not find the bitmap file. I was able to fix the token in the editor, but the graphic lost its text-centered attribute. I found no way in Help Magician to center or otherwise justify text or tokens. Similarly, there seems to be no way to set margins other than to launch Word, do it from there, and import the RTF file again. Not a good idea, given the import mangling. There were several other places where the import mangled the RTF file. I had to fix them in the Help Magician editor, and, once again, had no way to set the margins or control the justification.
I launched Word from Help Magician to look at the saved RTF file. It was different now. All of the link phrases and their context identifiers were displayed with a strike-through font and Help Magician had added a bunch of its own footnotes. Even though I had a copy of Word running, Help Magician launched a new copy. (Help Author's launch was smart enough to use the copy of Word that was already running.) The strike-throughs and new footnotes didn't seem to have hurt anything.
Help Magician launches the Help Compiler, WINHELP, Word, HotShot Editor, Paintbrush, and the Sound Recorder. It installs Microsoft Video playback software and shows you how to add audio, video, animation, and MIDI to a help database. Before you use Help Magician on a real project, however, spend some time with its tutorial and get a feel for how it works and where the bugs are. You might like it, and you might not.
RoboHelp from Blue Sky runs on top of the word processor. The current release supports Word for Windows only, although Blue Sky plans support for other packages. It won't be an easy port because the main part of RoboHelp is implemented as a Word document template with macros written in the WordBasic programming language. There are some other executable utilities, including one that launches a RoboHelp project, but you can just as easily launch it yourself from Word simply by opening a document that includes the RoboHelp template. This implementation is a dramatic example of what a programmer can do with WordBasic.
The RoboHelp template modifies Word's menus and tool bar and adds a floating tool bar that stays on top and to the right of the document while you are editing. The commands open dialog boxes to establish and change the characteristics of the help project. You add topics, jumps, popups, graphics, search keywords, topic titles, and context mnemonics by pressing tool buttons and filling in the dialogs. RoboHelp manages the document and the help project file and does not use its own database format; it uses the Word document format. One tool button writes the RTF file from the Word document. Another runs the Help Compiler to build the help database.
You can preview a topic by pressing a button, but the preview is not much better than what Word is already showing you. For example, it doesn't show graphics. In fact, RoboHelp's topic preview is not as good as viewing the topic in Word. The preview justifies all of the text in the left margin regardless of how you have the margins and paragraphs set up. It shows the graphics-insert tokens just as they appear in the document. It's a feature they could have left out.
There are other things that I would change. When you open a RoboHelp document, its Word template defaults the Edit/Find command to search for hidden text, presumably so you can find the jump and pop-up links. Most of my searches are for text in the document, which is not hidden, so I have to change the Find property every time. The "H" tool button that the template added changes selected text to unhidden, an odd choice for this button. I wouldn't think you'd need this one very often. A better choice would be to toggle hidden text into and out of view. Some of the time you want to see the links; other times you want the text to line up more like it does when WINHELP displays it.
Like Help Magician and unlike Help Author, RoboHelp does not use an existing running copy of Word; it launches its own. Because RoboHelp is a Word template, you can see its source code by opening the macros. Furthermore, if you don't like the behavior that I just described or anything else, you can modify it by changing the WordBasic code. You could even add your own adaptation of Help Author's indispensable topic-preview feature.
RoboHelp builds context-identifier files you can include in C++ and Visual Basic programs. It includes a VBX control that adds a help button to a dialog box and prompts you for the associated context identifier. A Screen Capture utility manipulates pictures from the Clipboard. It runs in the background waiting for you to put some graphics in the clipboard. When you do, it pops up with an image-processing tool that lets you modify what you captured into a bitmap for your help database. There is also an icon-composition tool included with RoboHelp.
It's not hard to pick a favorite from these alternatives. The manual approach worked, but was tedious. I prefer it over Help Magician, however, which seems to be not quite ready for prime time. Help Author is an order of magnitude better than the manual setup, and RoboHelp is far and away the best tool for the job that I've seen.
When I started this project, I went looking for "Visual Help." Although I didn't find exactly that, I am satisfied that there are tools that make the job easier. I do think, however, that a need for such a product exists. It would have all of the best features of the three packages discussed here. In addition, its editor would emulate the WINHELP display--that's the "visual" part. The tool would use RTF as its native database format and could emulate the jumps, popups, and multimedia features of WINHELP. Unlike Word, it would display graphics without taking all day. Such a program would eliminate Help Compiler until the end of the help document development project. This would be a valuable product. If you build it, they will come.
For More Information
Microsoft Developer Network CD Microsoft Corp. One Microsoft Way Redmond, WA 98052-6399 800-759-5474 The Windows Help Magician Software Interphase Inc. 82 Cucumber Hill Rd., #113 Foster, RI 02825 401-397-2340 RoboHelp Blue Sky Software 7486 La Jolla Blvd., Suite 3 La Jolla, CA 92037-9582 800-677-4946
Copyright © 1994, Dr. Dobb's Journal