The Help Compiler in Detail

In many ways the process of creating a hyperbook for Windows is taxing. First, it is necessary to make copious annotations in the source document. This is a time-consuming and monotonous task, though intelligent use of macros can aid greatly. Indeed, a small market has sprung up around this demand. Doc-to-Help is one product which attempts to remove the drudgery of annotation.

The following discussion provides supplementary comments on the five steps outlined in the node Windows Help Compiler.

1. Though any fonts may be used at design time, the same fonts must be available when the reader opens the book. In effect, this limits the choice to those which come with Windows. Most formatting, including special characters, is ignored by the compiler.
2. Each paragraph can only be 64 KB in size. While sufficient for text, this limits the size of graphics. Also, though graphics can be directly included in the word processor file, there are several disadvantages to this:
• text cannot wrap around the graphic
  
• if the graphic is changed, it must be manually replaced in the document by its most recent copy.
  
• the size of the text file increases dramatically, especially if more than one instance of the graphic is used
  
• graphics may not be used as anchors
  
• Microsoft Word for Windows must be used as the word processor
  

The only advantage is the fact that the graphics may be viewed on-screen with the text while writing.

3. Commands may be run when a hyperbook is first opened, when a particular topic is selected, or when a link is activated. Macros may add to the menu and button bar, trigger most menu functions, and run custom DLLs. These commands by no means constitute a language, as there are no control structures, variables, or means of getting user input.
4. Maintaining the project file for a large hyperbook can be quite a task. The most annoying restriction is that this must be an ASCII file. This necessitates either switching between a word processor (for the document) and a text editor (for the project file), or continually having to specify saving each file in the correct format.

Most of the options available through the project file will rarely be used, though a few deserve mention:

• the compress option helps to minimize the size of the hyperbook.
• the copyright option may be used to add a short (35-75 characters) message to the "About" dialogue. We would have preferred enough room for title, copyright, authors, and address--several lines at least.
• the errorlog option must be used if compilation errors are to be saved. It is hard to understand why this is optional.
• the title option gives the main window a label of up to 50 characters.
5. The Help Compiler must be run from a DOS box in Windows or DOS itself under an appropriate memory manager. After compiling, error messages are displayed to the screen as quickly as they can be written. If there are more than a few, most will scroll off the screen and be lost (hence the need for the errorlog option). This forces the question: Why is the Help Compiler not a Windows application?

By necessity, the compiler is picky--a single character out of place in the source file and the editing-compilation cycle must be repeated. This is a familiar routine to programmers; authors may have to adjust.

Microsoft has produced a serviceable product with enough rough edges to make us question their competence in system integration. Similar criticisms have been made of their Windows development systems, which are also run from DOS.

[1995 update: Though their other development systems have improved, the Windows Help Compiler has not changed in the last two years. However, innumerable third-party products have been released to make up for its lack.]