Authoring Windows Help Files for Performance (74937)

SUMMARY

The Windows Help Compiler allows an application developer to create hypertext documentation, richly annotated with color and graphics. This article discusses methods to author help files to achieve maximum performance when the file is used. These comments apply to Windows Help versions 3.06 and later.

This information is subject to change in future versions of the Help Compiler and of the Help application as new technology is incorporated into these products.

There are four major suggestions:

Use OPTCDROM=1 for all files destined for CD-ROM (compact-disk read-only memory), and potentially on files where up to an additional 10K of size is not significant.
Use bitmaps placed with data for small bitmaps that are referenced only once or infrequently in the help file.
Use bitmaps not placed with data for large bitmaps, all bitmaps referenced frequently, or bitmaps referenced by two or more topics that generally will be viewed in succession.
Use segmented hypergraphics to generate graphics with multiple hot spots, rather than several bitmaps positioned next to each other.

Coincidentally, suggestions 2, 3, and 4 are also generally space-saving techniques as well.

MORE INFORMATION

Use OPTCDROM=1 for files destined for CD-ROM.

When OPTCDROM is placed in the [OPTIONS] section of the .HPJ file, the topic information in the help file is aligned on 2K boundaries. This option is aimed at maximizing performance on CD-ROM drives, where reading aligned information can be significantly faster.

Estimates indicate that sequential reads from CD-ROM can be up to twice as fast when aligned. While reads are not always sequential, a high percentage can be, depending on how the help file is authored. Minor improvements have also been noted on magnetic media.

This option can cause up to 10K of additional file space to be used.
Store small bitmaps with data.

Placing bitmaps with data keeps the graphical and textual information in the same location in the help file. This avoids reading from different locations on disk to display a topic. Seeks to different locations are exceptionally time consuming on CD-ROM, and can be time consuming on magnetic media. Bitmaps with data also help maximize the effects of the OPTCDROM option.

Up to 12K of compressed topic text is buffered in memory. Since bitmaps are kept with the topic text, they take advantage of this buffering. Thus, topics under 12K in compressed size generally do not need to be reread when the window is resized or redrawn.

Note that large bitmaps kept with data may cause performance to become worse. Topics may be laid out twice as part of scroll bar removal. Topics over 12K in size will be read, laid out, and then reread as they are laid out a second time before display. Bitmaps are often the cause of exceeding the 12K size. Bitmaps NOT kept with data are buffered elsewhere (see #3 below), and if the remaining textual data is less than 12K, the topic will be read from disk only once.

Bitmaps with data cost space only when the same bitmap is used more than once in the help file. If a bitmap is used frequently, not placing it "with data" may be more appropriate, unless the performance benefit is determined to outweigh the size hit.
Store large and frequently accessed bitmaps separately.

The 50 most recently accessed bitmaps not stored with data are cached in memory. This means that the bitmap may have to be read from disk only once if two successively displayed help topics reference it. Unlike bitmaps stored with data, these cached bitmaps only have to be reread if they are bumped out of the cache by the subsequent display of 50 more bitmaps, or by low memory conditions.

Cached bitmaps not stored with data cost some speed when they are typically displayed by the user only once in a session. Since they are stored in a different portion of the help file from the topic text, an additional seek is required to locate them. This cost, if incurred, is generally negligible on disk, and high on CD-ROM. Note, however, that this cost MAY be less than the cost of reading the topic twice, if the topic is laid out twice as a result of not needing scroll bars, and is larger than 12K.
Use segmented hypergraphics.

Segmented hypergraphics is the term used to describe the ability to take a single bitmap, and define several regions that are hot spots. Hot spots can overlap, and can each perform different actions.

The primary benefit of using segmented hypergraphics is that a single bitmap can be used. Previous techniques utilizing several bitmaps carefully placed in the topic text to generate a single image have the drawback of requiring several bitmap-locating operations at display time, which can translate to several disk seeks and reads. On CD-ROM, especially, this can be quite significant.

The only cost involved in using segmented hypergraphics is that the segmented hypergraphics editor must be used to define the hot spots within the bitmaps.

In summary, there are a few simple authoring techniques that can improve performance of help files. While especially significant for CD-ROM hosted help files, they are of benefit to disk-based help files.