Introduction | Help Project | Tools | Help Compiler | Compiling | Pictures | Character Sets | Macros | SHED | Text Editors | Word 2000 | Notes | Bitmap & WMF | Drawings | DLLs | Conclusion | Notice | home page

r_harvey

Windows Help Files

Introduction

I'm often asked for a quick overview of how to make a help file. It surely cannot be that difficult; after all, HTMLcat is simple and easy to use, so it couldn't be that complicated. Well, it is.

And it's more difficult than the previous paragraph led you to believe.

And even more difficult than that.

Ironically, the poorest documented, and therefore least understood, part of programming is creating online help. Wait a minute -- documentation is undocumented? Yes. That's why most programs have truly awful online help.

Project planning begins with a few considerations:

• Know your audience.
• Know what you want to say.
• Know how you want to say it.
• Know the target platform. Will the computer be dedicated to the task?
• Know your budget.
• Know how your product will be distributed.
• Know your limitations. Decide if it is worth a big investment in learning new processes and tools.

From the user's point of view, which is the only view that really counts, help files are very nice places to work. Most projects are compromised by selecting tools and processes to make them easier to complete, instead of easier to use.

The Help Project

Are you sure you want to use a help file?

• Will data be frequently changed or added? Dynamic data is appropriate for Help files only if it is maintained by a custom DLL and shown in an embedded window.
• Is there a lot of data? This is as much an issue of distribution media as the quantity of data. Depending on complexity and computer performance, compiling help files may take several minutes per megabyte of data. The practical limit for a single help file is about 10 megabytes (yes, they can be larger than that, but is it practical?).
• Decide on the most appropriate data format. Your choices are not limited to just HTML, compiled HTML (Microsoft HTML Help), PDF, or Help files. A proprietary solution, perhaps using HTML or RTF and a program that calls Windows™ API functions, may be best for very large projects.
• Decide on the tools to use. If the tools are not available, too expensive, or too difficult to learn, you may have to back-up a couple of steps.
• How do you really want to do it? If you hate HTML but love Microsoft Word, you'll love help files; if you hate Microsoft Word, you will never be comfortable with help files.

The issue is further clouded by HTML, which is a much nicer and more portable way to write and design than Windows help files. HTML requires every computer user to have an Internet browser installed, and know how to use it. Standard HTML offers no document security, and control over page layout requires style sheets.

HTML Help
Microsoft HTML Help makes versatile, flexible, modern documents easier than standard Windows help files, and easier to use than a browser, though the viewer is relatively slow and memory-intensive, which restricts the product to higher-powered computers. Even though the user doesn't see it, Internet Explorer is still required, plus many, many support files. To ensure that readers have the required software, you will have to distribute at least 20MB of Microsoft files with your finished HTML Help project, or restrict it to Windows 98 or later.

Adobe PDF™
Adobe's page-description file format is an excellent alternative for distributing large, heavily-formatted documents like manuals and brochures. PDF viewers are available for several operating systems, making the documents truly portable. Many complain that PDF viewers are slow and perhaps a bit clumsy to use. PDF is a powerful platform, which means that it requires a good computer with lots of memory and storage space.

PDF is commonly used as a distribution format for documents that will be printed. You can embed fonts and high-resolution images, to create master documents that print accurately, without concern about the output device.

Summary
If the goal is producing a polished, professional product with minimal investment in training and experimentation, and you have no background in or interest in producing help files, consider using HTML. If you're writing online help for an application that must run in any version of Windows older than Windows 95, it should be a Help file. Other solutions are difficult to integrate with an application, and any HTML or PDF solution requires the user to install many megabytes of additional files. Besides, the document you're now reading is about making help files.

Help File Tools

Many software developers begin with good intentions, planning to create commercial tools to aid making help files. Somewhere along, every developer comes to realize that there is little market, and a lot that needs to be done. Some, realizing that they will sell literally 20 units (plus a thousand illegal copies) over the life of the product, drop it. Others turn it into a hobby, and release partly-finished tools, free of charge. Help file developers are left with undocumented (or incorrectly documented) processes, and unfinished tools. There are a couple of high-priced help tools around, but nothing offers automated ways to exploit the full potential of help files.

RTF Tools
Help file projects begin as one or more Rich Text Format (RTF) documents, usually edited with Microsoft Word for Windows version 6 or 7 (for 16-bit help files) or version 9 (for 32-bit help files). The word processor must support manual page breaks, keep-lines-together, keep-with-next, double-underlining, footnotes, and hidden text. For the best-looking, most-consistent help files, the word processor should also support style sheets.

The RTF file format describes a text formatting language. Pictures are not usually placed in the document, but referenced by special tags (which turn a visual word processor into a code-based monster). The help compiler program reads commands in the help project file (HPJ file type) that tell it how to combine the words and pictures into the HLP file.

Start with RTF documentation, and hope you never need it:

• gc0165.exe Rich Text Format (RTF) Specification v. 1.5.
• gc1282.exe Microsoft(R) Word 97 Rich Text Format (RTF) Addendum.
• Study well HCW.HLP, furnished with the Help Workshop (discussed later). This help file is loaded with vital information, but it's difficult to navigate and presented in 8pt MS Sans Serif type, so read it several times, and read it slowly.

Now look for tools:

• rtffix1.exe Corrects line numbering in HLP Files.
• rtfmod.txt describes rtfmod.zip, a tool to clean messy codes in RTF documents, but it doesn't remove extra fonts.
• Full text searching may be available in WinHelp Full-Text Search Interface June 22, 1995.
• Image Edit and BitEdit, furnished with older Microsoft 16-bit developer tools. The funny little Image Edit program does one thing well: it creates bitmap pictures without screen resolution information (necessary to keep help viewers from scaling pictures). BitEdit Version 1.0c makes it easy to reduce color depth and customize the palette.
• Look for the files nobody uses from the Microsoft Windows Software Development Kit. Those are MRBC.EXE and SHED.EXE.

Help Compiler
The help compiler translates RTF documents into HLP files:

• The 16-bit help compiler is furnished with programming tools from Borland, Microsoft, Powersoft, and others.
• helpshop.exe is version 4.02 of the 32-bit Help Workshop; you will need this if you use Microsoft Word 97 or later. Many software development packages included version 4.01.0950. If you don't need support for 16-bit Windows, use the 32-bit Help Workshop instead of the stand-alone help compiler.
• The Win32 Platform SDK, about a 12MB download, includes version 4.03 of the Help Workshop.
• Microsoft Multimedia Viewer is a full-featured version of the help compiler, requiring yet another help viewer. This 16-bit application has been used to create multimedia encyclopedias, but no 32-bit version was ever released. Microsoft has stopped selling it, stopped supporting it, and never really documented how to use it. You can download the tools (Media Viewer 11859KB), but it is now outdated, and not recommended. You wouldn't write with Microsoft Word 1.1, so why would you want to use a help viewer that old?

Compile the Help Project

This topic is worthy of a book all by itself. Here it is, in a tidy little bulleted list:

• Create a document in Microsoft Word for Windows. Save the file in the standard DOC file format. Get used to Word's styles, footnotes, hidden text, tab stops, manual page breaks, paragraphs formatted as keep-with-following, and so forth.
• Export the word processor document in the RTF file format. You will probably want to use a separate utility to clean-up bad codes or innefficiencies (like references to fonts that are not used in the document).
• Create bitmap pictures. If the pictures contain hot-spots, use SHED.EXE to convert the BMP or DIB files into SHG pictures. Use MRBC.EXE to combine pictures for different screen resolutions.
• Create the separate HPJ file. This text file is a list of codes that describe the project and tell the help compiler how to work. A help project can include multiple RTF documents and several pictures; commands in the HPJ list these components.
• Compile the help file by specifying the HPJ file on the command line. The best 16-bit DOS-based help compiler is called HCP.EXE.

If you are using the 32-bit Help Workshop to maintain the help project, most HPJ details are taken care of automatically, and RTF incompatibilities are fixed as-needed.

Browsing Help Files
Often called Help Author Mode, add the following lines to WIN.INI:

[Windows Help]
SeqTopicKeys=1

After you restart your computer, these new keystroke combinations will work in all help files:

Using Pictures

Carefully designing bitmap pictures reduces file sizes significantly. For instance, a pattern of long horizontal lines compresses down to almost nothing at all, while long patterns of vertical lines don't compress at all. This technique, by the way, also works with GIF pictures, used with Internet documents.

Here are some notes about bitmap pictures:

• Reuse pictures. Instead of embedding bitmap pictures in your documents, reference them with the {bmc} tag. This is a terrible way to visualize how a help file will look after it's compiled, so use descriptive picture names; for instance, {bmc --------.bmp} is an awful name for a file, but it's a descriptive way to reference a picture of a horizontal line, in a word processor.
• Bitmaps are limited to 16-colors for 16-bit help files, or 256-colors for 32-bit help files. You can use custom DLLs to extend help files to view any kind of pictures, but file size and compatibility are compromised.
• 256-color bitmap pictures are twice as large as 16-color bitmap pictures.
• You can embed 256-color bitmap pictures within WMF pictures, but neither 16- nor 32-bit help viewers restore the color palette in WMF pictures, resulting in distorted or flashing color if you change to another application then back to the help file.
• If you embed a 256-color bitmap in a WMF picture, the help viewer will scale the bitmap for the current screen resolution.
• I often simulate more than 16 colors by combining patterns of similar colors to create intermediate values, such as dark blue with dark cyan or dark red with dark magenta.
• Most 256-color pictures really only need a few colors--just not the standard Windows 16-colors. We can use custom palettes in 4-bit (16-color) pictures in 32-bit help files. The custom palettes replace Windows colors with colors of our choice, and we still have the efficiency of 4-bit pictures.
• You can change the palette in 16-color bitmaps for 16-bit help files. The Windows 3.1 help viewer will ignore palette changes, but the 32-bit help view will display the correct colors.
• Use Microsoft's Bitmap Edit utility program (BITEDIT.EXE) to convert between BMP and DIB, and to customize the palette.
• The 32-bit help compiler doesn't support WMF files as well as Windows 3.1. It's quite easy to crash the operating system by viewing a page from a compressed help file that contains several WMF files--while the same help file compiled with the 16-bit help compiler works reliably under any Windows operating system.
• If you are willing to put in the work, you can do amazing things with embedded windows. In HTMLcat, for instance, we use Windows Tab controls embedded within the document for navigation aids. Other embedded windows pop-up floating menus that allow the user to jump to topics listed in the menus.
• A well-written embedded window containing a picture can be as fast to display as using a bitmap plus a link, and likely with lower memory requirements. In HTMLcat 5, we replaced hundreds of WMF color swatches, with live swatches drawn in embedded windows by a DLL, and saved about 100K.

Ostensibly a portable document specification, Windows help files often do not display correctly on Macintosh computers (especially if they contain WMF pictures), and help files that call functions in 16-bit DLLs don't operate correctly under Windows NT, 2000 or XP.

Character Sets

• Use "Arial", "Symbol", "Times New Roman", "MS Sans Serif", and "MS Serif" only, for Windows 3.x compatibility. The "Wingdings" font doesn't work with the 16-bit help viewer. You can use any font with Windows 95, even if you use the 16-bit help compiler. The 16-bit help viewer will substitute the default font when it displays the file.
• Avoid using the "MS Sans Serif" and "MS Serif" fonts in paragraphs that use high-order characters. These fonts don't have characters 127-159.
• Bulleted lists don't export correctly from Word for Windows. Manually create a paragraph with a hanging-indent, add the bullet manually, and always make sure there is a tab stop set in the same position as the indent.
• The Apple Macintosh character set is not quite the same as Windows ANSI, so smart quotes display as the wrong character.

Word Processor Macros

Special symbols are exported by Word for Windows using proprietary mnemonic tokens. The problem is, the 16-bit help compiler doesn't recognize these shortcuts, so it deletes the characters. That's why hyphenated words run-together, and quotation marks are missing.

You can turn-off smart quotes, and stop using em dashes, or you can use a program to fix the proprietary codes.

After exporting the document to RTF, load it back into the word processor as a text file, then search and replace these characters, or write a macro to do the work for you. The macros look for strings that begin with a backslash and the following Word for Windows RTF tokens:

These characters are translated by Word for Windows in the RTF. The help compiler doesn't know the characters, so it ignores them. Replace the WinWord text with the codes, and the characters will work correctly.

Changing "\~" to "\'a0" fixes the non-breaking space problem.

Only tokens that fall within one line (one paragraph) in the RTF are seen by macros. The codes must fall within the first 260 characters of a paragraph. One work-around is to use short paragraphs (a good idea, anyway). In practice, most codes do not fall at the end of a line--bullets, for instance, are at the beginning of the line.

SHED Notes

This program creates rectangular hotspots within pictures (bitmaps or Windows Metafiles).

• You can browse hotspots by pressing TAB or SHIFT+TAB. If the hotspots are haphazardly created, the selection jumps around the image.
• For smooth keyboard navigation, create hotspots from last to first. The last hotspot you create will be the first link.
• Change the order of a hotspot by deleting it, then undoing the delete. Plan a sequence, and the last hotspot you delete then undelete will become the first hotspot.
• Replace the "Hotspot 1" string on every field with something shorter. This text is in the picture file, and shortening it saves space in the help file. The text is rarely useful, so I delete it all.
• Hotspots can reference macros, pop-ups, or jumps. If a hotspot references macros that aren't built-in (such as a Windows DLL call), SHED will display warnings when you enter the macro, but it will work correctly in the help file.
• Use SHGREZ.EXE to remove resolution information so the image won't be scaled when using large/small fonts.
• The Windows 3.1 help compiler puts resolution information back into BMP files when compiling. Turn the picture into a SHG file without hotspots, then run SHGREZ.EXE to eliminate resolution information.
• SHED can use WMF pictures as well as BMP, and there is no resolution information (image are scaled correctly).

Text Editor Notes

If you edit the RTF document directly, some text editor settings affect how the document is saved.

• In text editors, disable the option to "Remove trailing spaces when saving". All blanks are significant in RTF.
• Keep the DOC file as your master document. Treat the RTF as an intermediate file that can be discarded. In that way, you can add extra stuff to your Word document that won't be exported.
• To create the help file, save your DOC, then Save-As, and select Rich Text Format. After the document is exported, close the RTF file in Word for Windows.
• Now load the file into your text editor (you may be able to keep it loaded in your text editor as you work, just remember to re-load it after Word for Windows overwrites the original).
• The contents of RTF files are ugly, but they are plain text. All lines in the RTF file are 260 characters or shorter, and only characters 32-126 are used. RTF codes begin with "{" and end with "}". The backslash is the escape character. For instance, to enter a literal "{" you will see "\{", so when you enter "{bmc picture.bmp}", the RTF contains "\{bmc picture.bmp\}".
• If you are using the 16-bit help compiler, extra font declarations in the RTF file will inflate the size of your help file by 2-4KB. You can eliminate the extra fonts from the file now. If you make a mistake, the help compiler will quit with an error, and you will have to make a new RTF file (that's why we use the DOC file as the master). If you delete a font that is needed, the help compiler uses the default font. Look for a section, near the start of the file, that begins with "{\fonttbl" Now delete every font not referenced by the document. Each font description is within curly braces, like this:
  "{\f4\froman\fcharset0\fprq2 Times New Roman;}"
• While fonts are numbered, the number doesn't matter--it's an index into a list, and it will be fixed by the help compiler. After the final font declaration, there's an extra right-curly }. As in
  "{\f999 ... LastFont;}}"
  Don't remove the extra curly from the end! But you can remove the last font.
• Save the RTF file. You don't have to close the file now, but it is probably large, and if memory is low, performance may suffer.
• Run the help compiler. I use a Windows Explorer shortcut associated with the 16-bit help compiler.

Microsoft Word 2000

I've used Word daily since 1986, eagerly anticipating every upgrade. It may be surprising that I stopped upgrading in the spring of 1995, with a beta version, then the retail release of, Microsoft Word 7.0 (also known as Word 95). Besides the problems reported of Word 97, it had a deserved reputation for exporting RTF that was incompatible with 16-bit help compilers.

In May of 2001, I finally chose Word 2000 (version 9.0.3821 SR-1). Yes, it's a bit late, since Microsoft Office XP is available. The version I bought is the last one to install without mandatory product activation. I'm investigating moving to Sun's StarOffice for compatible RTF files (see the Links page).

The 32-bit help compiler works with Word 2000 RTF files, though it complains about some unexpected font information. I've yet to get any 16-bit help compiler to accept Word's latest RTF files, and the fix would take a big macro.

The latest version of the help compiler can handle Word's capricious RTF changes without problems; if you can't get a copy, try this fix. However, the word processor in Microsoft Works 6.0 does export compatible RTF files -- well nearly, anyway, because at least I could quickly correct the problem. Load the DOC into Microsoft Works, then export to RTF. Be sure not to edit or save the DOC file within Works, because some of your formatting may be lost. Works uses incomplete font descriptions within the \fonttbl section of the RTF header:

{\f0\fcharset0 Arial;}

You can correct the error by adding the missing portion of every font description:

{\f0\froman\fcharset0 Arial;}

Load the RTF document in a text editor, and replace every occurrence of \fcharset0 with \froman\fcharset0, then save the file. Remember, the DOC file is the master document, the RTF is just a discardable intermediate file.

Help Compiler Notes

• You can use the 16-bit help compiler to create help files for 32-bit applications. If you do 16-and 32-bit applications, you can settle on just one help file for both. Add an optional CNT file for the 32-bit version, if you like, but always put a good table of contents in the help file.
• If you us lots of WMF pictures, 16-bit help files seem to be more stable than 32-bit help files. This is true whether you are using the 16- or 32-bit help viewer.
• If you use the 16-bit help compiler, be sure to use the latest (and last) version, 3.10.505. The HCP.EXE version seems to work well with Windows 95/98.
• The 16-bit help compiler doesn't like RTF files created by Word for Windows version 8 or later, in Office 97 or later. You must use Word for Windows 2, 6 or 7 (in Office 95).
• If you use the 32-bit help compiler, you will have to use Word for Windows 7 if you use the early 32-bit help compiler (version 4.01.0950). Version 4.02 supposedly supports Word for Windows 8, and it solves several mysteries.
• If you're creating both 16- and 32-bit help files, you must use Word for Windows 7.
• If you use WMF pictures, performance with 16-bit help files seems better if you use {bmcwd}, {bmlwd} or {bmrwd} to reference the illustrations.

If you've tried Borland's "Creating Windows Help" help file, you're probably very confused. For example, they think that {bmc} inserts a centered picture. (Borland uses RoboHELP now.) At one time, you could go to http:\\www.helpuniversity.com to look for better documentation, but this link is probably broken. They also had a help decompiler, which I don't want to recommend (but you can use techniques in help files that make decompiled help files tough to recompile cleanly).

Bitmap and WMF Notes

You can use 24-bit bitmaps in 16-bit help files by placing them in WMF. But that's a terrible waste of space. If possible, use WMF (Windows Meta-file) instead of bitmaps. Here are some things to consider when deciding to use WMF:

• Is it large?
• Does it need text.
• Does it need special colors or more than 16-colors.

There are several reasons to use WMF instead of bitmaps. First, you can get more colors. Second, the picture automatically scales for the screen resolution. Third, files are much smaller--I've replaced 12K bitmaps with 800 byte WMFs that look better. There are a few disadvantages: performance is slower than bitmaps, Macintosh help viewers can't handle WMF, and if you are using 16/256-colors, you have to use a very limited palette to minimize ugly dithering. You can experiment to get a smooth palette; I use about 58 colors that look good on any screen.

• Use a limited WMF color palette. You can get a copy of ASCIIcat free of charge from the home page. It includes color swatches of compatible WMF colors (and more tools for help file writers).
• Avoid using curves in WMF. Curves display slowly. Some drawing programs turn curves into hundreds of very short straight lines, which makes files very large. Try to use straight lines and simple polygons.
• Nobody talks about it, but you can use WMF with SHED.EXE, to create vector drawings with hot-spots! There were lots of them in HTMLcat 4 (replaced by dynamically created embedded windows in HTMLcat 5).
• If you want to use fonts other than Times New Roman, Arial and Symbol in Windows 3.1x help files, use them in the WMF! The code that displays WMF supports any installed font in Windows 3.1, even though the rest of the help file is limited to just a few fonts.

Drawing Programs

We use RTF as an intermediate file, never the master, since a new one is created by the word processor whenever we change a document. In the same way, WMF files are intermediate files that are exported by drawing programs. Save the master picture in the program's proprietary drawing file format, then export the file (or a small piece of it) to WMF when the design changes.

I've had good luck with Micrografx Designer 7.1. That is, once I got it patched. Go to http://www.mgxsupport.com to get the 7.1 patch. And whatever you do, never select text and then CTRL+drag to copy it to a new place, then immediately double-click on the copy (you'll probably try it once -- just once).

Designer 7.0 correctly exported WMF, but Designer 7.1 defaults to something incompatible. You can patch Designer 7.1 by following the instructions in this message from Micrografx support staff:

"Thank you for your post. Under which version of Windows do you have the software installed? We have reproduced this under Windows NT 4.0. You should change the GDIWMFFILTER to = 1 (Tools/Options/Registry tab/Translation Key) and use the file type "Microsoft WMF" for the Export, and this should help."

Be careful, because there's a second WMF file type listed, and it doesn't work. (And why, after they've confirmed that it doesn't work anyway, do they need to know the Windows version?) There are two kinds of WMF files: standard (much like a stand-alone drawing), and placeable (like an OLE embedded object); the help viewer supports only placeable WMF.

Always save the picture as a Designer DSF document, and only export as you need. Don't try to import WMF back into Designer -- their import filter is quite limited!

If you use the Windows Clipboard to insert Designer drawings into Word for Windows, use Paste Special, and select Picture.

Designer 7.1 no longer adds an extra transparent rectangle around exported objects, which is nice. But it adds an unnecessary "Created by..." record to every WMF; this inflates every WMF file by about 58 bytes. There's a work-around, if you want to use a binary editor:

Manually edit the WMF and delete the message. The unneeded record begins with (these are decimal character values):

29 0 0 0 38 6 15 0 47 0

Followed by the copyright string:

MGXI: created by Micrografx, Inc. Mgxgre v1.00

Next, two null bytes:

0 0

Followed by:

4 0 0 0

Remove everything except the trailing 4 0 0 0. Now save the WMF, and try to import it back into Designer. If it's scaled incorrectly or otherwise scrambled, try again. Note that Designer does not import WMF correctly, so fonts, tab stops, and some other objects will be inaccurate -- but the picture should load without errors.

Note: There may be another 29 0 0 0 section before the one we want--don't touch that one! This patch applies only to Designer 7.1 meta-files!

Here's an unrelated Designer 7.0 fix. If you don't like font style previews in font lists, (slow, and wipes-out the disk cache), add the following registry numeric key (use the Designer Tools.Options.Registry tab to make it easier).

Preferences/PreviewFontCombo    0

After all that, Designer has dropped from the radar, and Micrographx is now a division of Corel. I would be extremely surprised to see Designer ever regain the stature it held in the early '90s.

Corel Draw
Old versions of Corel Draw have problems exporting WMF. Corel Draw 9 appears to export WMF files correctly, including font names, and without extraneous data fields in the file. It's perhaps the best solution to the WMF problem, even though it has horrific memory leaks that expand every time you export another file to WMF. Reboot the computer after exporting a half-dozen files.

Adobe Illustrator
Version 8 of Adobe Illustrator does not export WMF, other versions through 9 make good WMF, but only if you don't use any fonts; unfortunately, we usually need fonts in illustrations. The problem is that Illustrator uses the PostScript name for fonts, even TrueType fonts, which makes font names unrecognizable by the help viewer. I've had some luck by saving the document as EPS, then manually editing the EPS to correct the font names, then loading the file back into Illustrator, and then doing the WMF export (well, that's convenient). Be careful using Illustrator 9.0 for WMF export, because while it appears to format fonts correctly, it's very likely to turn the font into a bitmap (a design decision which I suppose is rationalized as better than no font at all). Get the 9.0.2 patch, and experiment with Illustrator's export settings to find a compromise that suits you.

Other Drawing Programs
You can also use MS Draw (which is WinWord's built-in picture editor) to place vector drawings directly in the document. This is the most compatible method, but it means the illustrations are not reusable and they cannot have hot-spots. If you must use MS Draw to create WMF, try compiling the pictures into a temporary help file, then decompile the help file to extract the WMF (that's even less convenient than Illustrator for making WMF).

Dynamic Link Libraries

There are many limits to what a help file can do when calling a DLL (Dynamic Link Library). It's a challenge to extend help files without resorting to replacing the help viewer -- in many ways, that's exactly what we do when we create embedded windows.

• You can call 32-bit DLL functions from Microsoft Windows 3.1 help files, as long as you use the 32-bit help viewer and a 32-bit operating system. We used this method in HTMLcat 4, which includes a single help file, but both 16- and 32-bit DLLs. There is little market today for 16-bit Windows applications; for simplicity, we are now supporting only 32-bit Microsoft Windows, which offers more features and an easier and more consistent programming model.
• The Microsoft Windows NT, 2000, XP help viewer does not support 16-bit DLLs. We can work around this limitation by distributing the 16-bit help viewer with our applications, or better yet, recompile the DLL for 32-bits.
• If the help file must call 16-bit DLL functions and you cannot rewrite the DLL, perhaps because you do not have the source code or the company is no longer supporting the product, all is not lost. Search the Microsoft Developer Network for information on "Thunking" or "Thunking layer." This is a process that allows code from a segmented (16-bit) memory model to call code written in the flat (32-bit) memory model -- or the other way around, and you can write the functions in high-level languages, without resorting to Assembly language. The process works, albeit slowly, but it is no substitute for true 32-bit code.
• Functions in DLLs use WINAPI calling conventions. In 16-bit DLLs, this is equivalent to Pascal, and in 32-bit DLLs it is the same as StdCall. We recommend using PROTO high-level declarations, and INVOKE when writing Assembly language functions, to hide the differences in calling conventions.
• Function names are case-sensitive in 32-bit Microsoft Windows and use the StdCall calling convention. If the function is named GlobalAlloc, use that capitalization.
• StdCall adds a leading underscore and an at sign followed by a number at the end of the function, describing the number of bytes passed to it. GlobalAlloc is represented as "_GlobalAlloc@8" because it takes two arguments that each requires four bytes. This mechanism ensures that the correct number of bytes are passed to functions, but it does not ensure that the values themselves are correct, and once the functions are linked in the DLL, the underscore and number are removed. The mechanism works by using a LIB file to resolve the names, which the linker then converts to the short form.
• The DLL is not an application. This simple concept is easy to forget about, and it can cause difficult to track-down problems. The DLL has no main window or message loop; you can pass the internal hwndApp variable from the help file to DLL functions, or call the GetActiveWindow() function. If, for example, you want to pop-up a dialog box that is stored in your DLL, the main window is owned by the help viewer program, but the dialog box resource is owned by your DLL (slow down, breathe normally, it really does work).
• The DLL can use internal resources directly by number, without the shenanigans required by applications. This makes it simple to reference icons, sounds, or other data added to the DLL by the Resource Compiler. Use the HINSTANCE passed to your DllMain function, and the constants defined in Resource.h to locate resources.

HPJ Issues
If the [CONFIG] section of your help project file (HPJ) uses very long macros and lots of them, you're likely to have problems. The help viewer (especially the 16-bit help viewer) will crash when loading the help file, or perhaps menu items or keys created by macros will not work.

The first step is to make the macro lines as short as possible. While macros can generally be aproximately 200 characters long, try to keep them shorter than 150 characters.

There is apparently a common memory pool used by the help viewer when starting a help file; temporary storage is at one end, and permanent storage is at the other. We run into problems when temporary storage (the currently-executing macro) overwrites permanent storage (key assignments, menus, and such). Organize items in the [CONFIG] section in the following order to minimize conflicts:

• Declarations, using the RegisterRoutine function.
• Long macros that do not change menus or keys.
• Macros that change menus or keys.
• Short macros.

Following this sequence, a help file can execute 30-40 macros when it starts. Keep in mind, however, that macros are interpreted text, not compiled programs, and they run quite slowly; the fewer macros you use when the help file loads, the quicker the help screen will appear.

We can reduce some startup overhead by moving initialization from the HPJ file to the DLL. We can do some initialization within the DLL without even calling it from the help file, by adding code to the DllMain function. DllMain cannot change the appearance of windows, because the windows may not have been created when it loads.

Register Routine Limitations
There is no limit on the number of DLL functions a help file can call, but it's impractical (or sometimes impossible) to use all of the functions we would like.

We can minmize the number of functions in a DLL by having the same function perform several tasks. This is a poor programming practice for general applications, since magic numbers make programs difficult to read and maintain, and prone to errors that are nearly impossible to track-down. In a complex help file, there is no other way. HTMLcat, for example, calls DLL functions more than 2,500 times, but there are only a few functions in the DLL. Designing the function to accept a numeric sub-function number, or a string describing the task, makes it possible to reuse a function, with only a single call to the RegisterRoutine macro.

String Arguments
Say your function requires a file name with a path, so you pass the string from your help file to the DLL, but it never seems to work right. The problem is that some characters are reserved in help files. If, for instance, you need to enter a backslash character, you need to use two of them. Here are the special symbols:

These reserved symbols mean that strings will not appear as you want unless you follow these conventions. If the string is delimited by quotation marks and you want a quotation mark in the string, use \"; if it's delimited by apostrophes, but you need an apostrophe in the string, use \':

!MyFunc("This is in \"quotation\" marks")
!MyFunc('This is in "quotation" marks')

Note, too, that there is no way to enter carriage returns and line feeds in the text -- if you try, the help compiler will display the message "Warning 4753: Hidden paragraph," and then quit. You can pass tab characters to functions by placing tabs within the quoted strings.

Strings passed to 16-bit DLLs can be approximately 512 characters long. 32-bit macros can be about 16K long, but the help compiler still limits the length of strings.

Testing DLL Functions
When viewing a help file, you can press CTRL+SHIFT+J to open a small dialog box, then type a keyword, and jump to it. For instance, in HTMLcat, you could type "B" to jump to information on the B tag.

This dialog box simplifies the the task of writing and testing DLLs. Instead of having to write custom text and compile the help file for each test, you can compile just once, making sure the function names are declared in the HPJ, then simply call them. CTRL+SHIFT+J lets you try macros directly by typing "!" followed by the macro name. In HTMLcat, for example, the function named CA() copies text to the Clipboard; this example uses CA():

!CA("Hello, Clipboard.^pThe second line of text.")

Notice that CA() works-around the problem of passing carriage returns and line feeds to DLLs by interpreting "^p" as these characters.

Some DLL functions and macros that depend on the position or state of a window will not work correctly within this pop-up dialog box.

A Sample Problem

When we strive to get more from a technology, we sometimes push it beyond its intended use. Here is a typical scenario.

In HTMLcat 5, we replaced the button bar with a custom navigation bar (tool bar) and live buttons. The navigation bar is managed by the DLL, which tracks the mouse and handles jumps.

When we don't use the BrowseButtons() macro (which would enable the standard button bar), several keys are disabled; for instance, < and > no longer work for navigation, and these keys cannot be re-assigned.

We added a context-sensitive pop-up help topic to the top of every page, with a small "(i)" icon on the navigation bar. When the user clicks the icon, the DLL tells the help file to open a pop-up window (which, itself, requires undocumented code). What if the user doesn't want to use the mouse? We can call the AddAccelerator() macro to assign a macro to the ? key. We would have to change the accelerator on every page in the help file, to ensure that the context-sensitive help topic is used. Or we could call AddAccelerator() once, when the help file loads, and have the macro call the DLL to ask for the current help context. It could look like this:

PopupContext("HTMLCAT.HLP",GetPC())

The GetPC() function in the DLL, returns the current context-sensitive help topic. This method works in 16-bit help files, but the command interpreter in 32-bit help files changed. Arguments to help macros in 32-bit help files cannot contain calculated results from function calls. You can interract with hot keys, embedded windows, and context-sensitive pop-up help windows--we do it all the time in custom help files, but that's a very, very long tale, of dark passages, secret messages, and call-back functions.

Conclusion

This is more information than you wanted, but less than you need. We can see that programs and help files are not magical things that just seem to work without human intervention. They are the result of education, design, and way too much work.

This is all the free help on help we have to offer; it's quite a lot, really. Our consulting services can solve your help file problems and create custom solutions for you.

Notice

© Copyright 2007 R. E. Harvey, All rights reserved.
P.O. Box 10086
Glendale AZ 85318-0086 USA
E-mail: .
Home page: http://ourworld.compuserve.com/homepages/r_harvey.

Top | Notice | Home | | © Copyright 2007 R. E. Harvey, All rights reserved.