Copyright: Herd Software Development 1995-96


ThinHelp technical reference (main menu)
ThinHelp technical reference

 Technical reference

  What’s new in this version of ThinHelp

  Which ThinHelp DLL should you distribute?

  Custom color palettes in ThinHelp-enhanced files

 A guide to compression, file formats and optimized display insurance

  Issues with Windows font sizes and desktop colors

  Issues relating to WinHelp’s Tab key functions

 Performance and reliability issues for CD-based applications

  Hardware requirements

  Improving JPEG display performance with disk-based bitmap caching

  Memory management via THSetCacheSize()

  Distributing helpfiles with extension DLLs

  Issues relating to Windows versions

  THNHLP.DLL as an import filter

  [BAGGAGE] file size limits

  Maximum allowable simultaneous images

  Copyright issues regarding bitmaps and sounds

  Undocumented features


What’s new
What’s new in ThinHelp since JPANI

What’s new in version 2.0:

 DLL renamed to THNHLP.DLL, product renamed ThinHelp.

 Help expanded and updated.  Many formerly undocumented features are now documented including custom animation sequence syntax and complete display parameter specs.

 Now supports transparent bitmap display using user-selected indices.  The same bitmap can be displayed in separate embedded windows with different transparency indices for each window.

 Mask transparency is now available for both BMPs and JPEGs.  Two color mask-bitmap overlays provide transparent regions for any ThinHelp bitmap.

 Support for watermarks in scrolling regions.

 Occasional problems with the 55-embedded-window limit in WinHelp have been eliminated through better memory reallocation.  ThinHelp can now display virtually unlimited numbers of bitmaps in a single HLP or MVB file.

 SEG renamed to Push, added many new powerful features.

 A walk-through script for ASETUP has been added to the shareware archive to assist Help authors in developing installation distributions for their projects.  This version supports the creation of self-extracting, self-starting .EXE files which function under Windows 95 and Windows 3.1/3.11.

 ThinHelp now includes depressable-button features implemented through a flag value in the animation parameter.  When no macro is used in the embedded window statement this feature simply creates a raised 3D-style bitmap.

 Display speed has improved considerably.  JPANI users will note that topics using as many as two dozen ThinHelp embedded BMP windows will display quickly and with virtually no “flash” or flicker.

 THIsWin32() macro added to test for ThinHelp version number, used most often for NT installations.

 Registration demo moved to a separate helpfile.

 A 32 bit version of SEG.EXE is now available to registered users for use with Windows 95/NT 3.5x.

 Animations can now be looping or play-once.

 Shareware archive now includes a free icon graphics library for use with ThinHelp.

 Many, many more small enhancements.  Serious JPANI/LZANI users are recommended to read this helpfile through carefully...there is a lot of new functionality and many features of JPANI which were never documented are documented for the first time for ThinHelp.


Which ThinHelp DLL should you use?
Which ThinHelp DLL should you distribute?

An easy choice: which DLL type?

When you receive the registered version of ThinHelp you’ll have a total of four different versions from which to select for inclusion with your Help or Viewer projects.  THNHLP.DLL is the full version and supports JPEG graphics.  If you don’t need JPEG graphics, you can use THNBMP.DLL instead and reduce the size of the distribution by another 30,000 bytes or so.

A tougher choice: which version?

The next decision you need to make is whether to include the 16 bit or 32 bit version...or both...in your distribution.  Before you can make an informed decision you’ll need to understand the issues relating to distributing 16 and 32 bit DLLs with WinHelp.  A special topic which discusses these issues is linked to this help button.

A brief note about HLPLHA.DLL

If you need to use HLPLHA.DLL in your distribution for compressed baggage handling, keep in mind that it is a 16 bit DLL.  Pay careful attention to the caveats regarding 16 bit DLLs in 32 bit helpfiles at the topic linked to the help button above.

If you want to distribute 32 bit Help which is usable on Windows NT 3.5x and still have LZH-compressed baggage functionality, it is strongly recommended that you use the alternate method of LZH-compressed baggage handling described in the HLPLHA.DLL topic.


Custom color palettes in ThinHelp JPEGs

 JPEG palette options      [image] { ewx} statement palette parameters

Unlike BMPs and GIFs, JPEG files do not contain a color palette.  JPEG decompression always provides a 24 bit TrueColor image whenever the hardware and software permit it.  Most displays use a resolution of 256 colors and rely on palette information stored in either the software displaying the picture or in the picture itself.  In the case of JPEGs, the palette must be provided by the software.

Actually, most Windows applications only allow 236 colors, not 256, since Windows reserves 20 colors for itself in 256 color mode.  ThinHelp takes this into account, setting aside a 236 color palette for JPGs to insure no distortion of standard 16 color WinHelp bitmaps.  ThinHelp reduces this palette using a technique called dithering, and this requires consideration of many small details.

Additional information for the less technically-minded about dithering, palettes and luminances is provided in the help topic linked to this button.

Three JPEG palette options

ThinHelp can apply the 236 unique colors available to 256 color displays in three different fashions.  Each has its advantages and disadvantages.

Standard color palette:

This is ThinHelp’s default setting.  It provides two primary benefits: speed and compatibility.  It is by far the fastest method and it permits the simultaneous display of as many pictures as required in a window or group of windows.  Unfortunately the standard palette does not give the best results with detailed renderings and photographs.  The individual pixels will appear too sharply defined in relation to their neighbors, an effect known as speckling, and it is seldom used except for line drawings and cartoon panels which do not depend on color precision or include a lot of detail.

Standard color palette plus some additional colors:

ThinHelp normally uses the Red/Green/Blue (RGB) color components with six different luminances, providing 6x6x6=216 colors.  If you use ForeHelp, you have probably noticed that 6 is the default value for JPEG graphics on the Options dialog window of the ThinHelp embedded window statement editor.  The 20 remaining unused colors can be used to boost the color count of one, and only one, of the pictures on the screen.

The luminance count per color component can also be reduced.  For example, with three luminances (no luminance, medium, and maximum luminance), 3x3x3 or a total of 27 colors are assigned to the image.  This might appear to be far too few, but as you’ll see in a moment, it might be an ideal choice.

To achieve the standard-plus-additional-colors effect, the first and second numerical parameters in ThinHelp embedded window statements are reserved for palette-handling.  Here’s an example.

{ ewl THNHLP,THIN,!TECHDATA.LZH;FLOWER;3/50 }

This tells ThinHelp to use 3x3x3 (or 27) colors for the default color handling of the JPEG, and an additional 50 colors to optimize this picture only.  If you have more pictures to show at the same time, only use the first parameter (3) so that the color palettes will match.  If you’ve ever tried to match color palettes of GIF graphics for Web pages, you’ll appreciate this flexibility.  It’s an excellent choice for graphics which contain a lot of subtle variations of the same color but not necessarily a wide range of colors.  Skyscapes, which use a lot of blues, or forest scenes heavy with greens might look fine with a 3x3x3+50 palette.

This is slowest technology supported by ThinHelp and it does not give the best results.  It is, however, far less work than creating your own color palette, and it may be the ideal choice for developing quick, one-off projects that don’t demand intensive palette manipulation or letter-perfect 256 color display.

Also note that speed may not be as serious an issue as it may appear from this description of the technique.  Like most Web browsers, ThinHelp will create an empty frame for the bitmap and display all text in the topic before decompressing JPEG graphics.  This insures that the user will not be faced with a blank window while the graphic is being processed.

User-defined custom palettes

This scheme has three distinct advantages and produces the best overall display and performance results.  The first advantage of defining your own palette is the ability to use whatever graphics software you may have to create the palette using intelligent color reduction.  Secondly, you can use the same manually-optimized palette for all pictures needed for the topic.  Finally, this technology is faster than the ThinHelp-computed palette described above because ThinHelp doesn’t have to work out the best color palette to use.

Disadvantages include slightly reduced speed compared to the first method, the need for a tiny 1,000-byte bitmap in the LZH archive which acts as the palette definition file, and the work required to develop the palette definition (.PAL) bitmaps.

Here’s the quickest, easiest way to create palette definition (.PAL) files.

1. Load your JPEG graphic into any graphics application capable of converting TrueColor JPEG to 256 colors (e.g. Paint Shop Pro, LView Pro, Hijaak, Photoshop) and reduce it to 256 colors.  Select optimized if this option is available...you’ll have to experiment to see if error diffusion or reduce bleeding have any significant negative or positive effects.  You should also select any available checkbox or radio button that specifies “include Windows standard colors”.

2. Store this graphic as a typical 256 color BMP file.  But before saving it, reduce it in size.  It doesn’t have to be larger than one square pixel (1x1) to contain the palette information you want, and the smaller it is, the smaller your compiled helpfile will be.  When saving the file to disk, give it the extension .PAL instead of .BMP.  This bitmap will not be displayed in the Help window...its only purpose is to tell ThinHelp what palette colors will be applied to the current topic.

3. Name the .PAL file so that it will be referenced when the appropriate topic is loaded.  Its name should follow the name of the bitmap from which it was derived.  For example, if you have a topic which uses MYPHOTO.JPG and you want the PAL file to control MYPHOTO.JPG’s color palette, name the 1x1-pixel palette-defining bitmap MYPHOTO.PAL.

4. Store both files in the same LZH archive.  This archive can be located either inside the helpfile as baggage or outside the helpfile as an external graphics library, but both bitmaps must be LZH-compressed.  .PAL files will not be applied to JPEG graphics included as non-LZH-compressed baggage files.

5. Reference the bitmap in your source RTF so that ThinHelp knows to display both the bitmap and the .PAL file.  The simplest way to do this is to omit the files’ extensions, as in this example:

{ ewc THNHLP,THIN,BITMAPS.LZH;MYPHOTO }

This syntax loads both the JPEG and the .PAL file, because ThinHelp looks for .PAL, .MSK and .SEG files any time it finds a reference to a bitmap file that doesn’t use an extension.

Alternately, you can use a separate {ewc} statement just for the .PAL file.  If you do create a separate {ewc} statement for the .PAL, the best place to put this statement is after the last text characters in the topic’s nonscrolling region.

6. You’ll find it least confusing to assign a separate .LZH archive for each bitmap or set of bitmaps for which you need a .PAL file, and this will also insure the best performance.  Just remember to add the name and path of the .LZH to the [BAGGAGE] section of your Help or Viewer project file.

Do not attempt to use Push’s scaling filters to create your .PAL file.  Dedicated graphics software should be used for this task.  Repeated applications of rescaling will reduce your image files to dimensions suitable for a .PAL file, but...the final color reduction to 236 colors is unlikely to produce the results you expect.  Use the method outlined above instead.

This sample JPEG image uses a .PAL file to produce an optimized appearance on 256 color displays.  Depending on the quality of your display, the difference in quality could be negligible or painfully obvious.  Click here to pop up a JPEG bitmap which does not use a .PAL file to see the difference.

Palette parameters in embedded window statements

There are two palette parameters available in the embedded window statement for defining custom palettes.  Here’s a sample embedded window statement that uses these parameters and some tips for optimizing them.  You’ll find this useful with small Web GIFs converted for use with ThinHelp, especially if you’re a GIF wizard just getting your feet wet with JPEGs.

{ ewc THNHLP,THIN,!BITMAPS.LZH;LOGO.BMP;5/15 }

This statement defines the custom palette with 5x5x5=125 colors, plus fifteen additional colors selected by ThinHelp to improve the overall appearance of the image, for a total of 140 colors out of 256 used for this image.  ThinHelp reserves another 20 colors for the default windows palette so there are actually 160 colors in use.  That leaves 96 more unique colors available for use in other graphics in this topic.

You may find that having these colors available for ThinHelp to assign to other graphics will save you a lot of palette correcting and calculation, especially with converted Web GIFs and PCXs from clip art CDs.  The sample embedded window statement above doesn’t use transparency index colors or animation parameters, but these features are still available for this embedded window if needed.

Notes, tips and issues

 If you don’t know how to optimize the palette of a given JPEG file, just load the JPEG into Push, reduce the color depth to 236 colors and save it as a BMP file.  Push will convert the JPEG to an optimized 256 color BMP.  From there you can load  it into another graphics program, resize it to 1x1 pixels, and when saved, this file will have the desired 256 color palette.


Windows font sizes and desktop colors

Two Help headaches: global font size and desktop colors

Font size and screen resolution have been problems for Help authors since Windows 3.1 was released.  But Windows 95 has thrown a new wrinkle into Help authoring: wholesale massacre of your carefully-selected color schemes if the user has a nonstandard desktop color defined.

Author-defined color schemes are tricky to control.  Here’s what can happen.  You carefully select a desktop color and set all your topic text to match.  Then you discover that whenever the helpfile is displayed on a Windows 95 system using a non-standard desktop color scheme, your text colors fall back to black and your selected background colors are replaced by the window background color used by that color scheme.  Suddenly your maroon text on ergonomic-green background turns into black-on-pale-blue...or worse.

This button will call up the Control Panel desktop colors applet so you can see this effect for yourself.  (Windows 3.1/3.11 users take note: this will have no effect in your version of Windows.)  Select the Plum color scheme if it hasn’t been erased.  You’ll note that this is a HiColor display setting, but it will work in 256 color mode too, and demonstrates an anomaly of Windows 95 that you should be aware of.

Subheadings may turn from blue to all-black, and the background color in the nonscrolling region may be lost, changed to the same colors as the main topic window.  (Use this same button to restore your regular color scheme after finishing this test.)

Now open any non-ThinHelp helpfile on your system which you believe is making use of transparent graphics.  Chances are good that you’ll discover instantly just how transparent those graphics really are.

Make no mistake...millions of users know how to change color schemes, and the installation of custom themes and schemes is an extremely popular method of personalizing Windows 95.

Solving the desktop color dilemma

The background color control parameters in THWaterMark() will allow you to force the background color to your chosen colors in both 16 bit and 32 bit helpfiles.  But there’s a subtle dilemma to resolve.  Microsoft considers Help’s adaptation to the desktop’s colors to be a feature of Help, a deliberate design choice and not a bug, and has no plans to fix it or allow Help authors to easily work with it.  That leaves you with a choice...do you let your users select their own desktop colors or do you impose your own background colors through the use of background color control using THWaterMark()?

It’s a design choice you’ll have to make for yourself, and there is no answer which will please everyone.

Solving the bitmap-scaling dilemma

Windows 95 makes it easier than ever, and -- thanks to the choice of smaller global system fonts -- more necessary than ever, for the end user to select large fonts over small as a system default.  You may be one of the unfortunate Help authors who were deluged with complaints late in 1995 about distorted bitmap images in your helpfile in Windows 95 large-font display modes.

Fortunately, font size selection by the end user, whether enabled globally through Control Panel or from Help’s Options menu, shouldn’t ever be an issue with ThinHelp embedded windows...or any embedded windows for that matter.  Embedded-window bitmaps always scale themselves correctly regardless of screen resolution, so if you’re having trouble with an SHG or BMP that won’t behave in large-font mode, why not display it as a ThinHelp embedded-window bitmap?

If ThinHelp is not your preferred choice for displaying a given bitmap, you can still insure correct display by converting the bitmap to an .SHG (it need not contain any hotspot information), loading the SHG into Push, and saving a copy of the SHG elsewhere on your system.  Push automatically “fixes” the resolution of SHG files so that scaling problems should never be an issue.

ewc THNHLP,THIN,!TECHDATA.LZH;PREVMENU.BMP;0/0/34/0;;JI(`'~`ID_CONTENTS')}


About ThinHelp and Help Tab-key functions

Windows Help has two keyboard functions most users never learn about -- or need to know about -- until they’re in a situation where they have to know them.  WinHelp allows keyboard-only navigation of helpfiles through the use of the Tab key.  Tab moves the user from one hotspot to the next in sequence, and when the appropriate hotspot is selected, pressing Enter executes the action associated with that hotspot.  Ctrl+Tab is also available as a means of displaying all hotspots in a topic simultaneously, a tip many Help authors find useful in exploring others’ Help systems or checking their own.

ThinHelp’s embedded windows do not support these features of the Windows Help interface.  Tab will only step the user through normal, non-embedded-window hotspots.  Although cursor shape change is supported, Ctrl+Tab will not display ThinHelp’s embedded-window hotspots even if they are generated from SHG files in ThinHelp compressed graphic libraries.

While this makes ThinHelp useful for hiding hotspots (e.g. a secure-access hotspot for topics which unauthorized users should not see), it also makes ThinHelp incompatible with Windows systems where the keyboard is the only available input device.

Solutions

There are possible solutions available for this problem.  Key to the Mouse is a Windows 3.1/3.11 shareware package which will allow the keyboard to emulate a mouse (you can probably find it with a World Wide Web search), and the supplemental resources archives/disks for Windows, Windows 95 and Windows NT should include mouse-emulation software for keyboard-only users.  We were unable to find Key to the Mouse in a recent Internet search, so we recommend relying on the accessibility options software and supplementary archives available from Microsoft.

Due to the large number of programs and program functions which depend entirely on a pointing device for their utility, the lack of full Tab key support in ThinHelp should not prevent users from accessing information in ThinHelp-enhanced files, and no support for WinHelp Tab key functions is planned for future versions.


Improving JPEG performance with caching

While JPEG is a terrific technology for providing photo-quality bitmaps in the lowest possible file size, it provides decompression times on most current PCs.  Visible delays of several seconds per bitmap may be experienced on slower 486 and 386 systems even for relatively small JPEGs, introducing an unwanted “zap factor” into your project.  In response to this problem, ThinHelp provides a disk-based caching function which will save the decompressed bitmap data as a disk file in the Help or Viewer title’s directory.

Caching is a means of accelerating access to data by storing it in a more quickly accessible form.  In ThinHelp’s case, uncompressed datafiles containing bitmap data are used as the cached data since this data can be loaded into memory much more quickly than JPEG-compressed graphic data.  It offers much the same type of performance boost as a Web browser’s cache function.

Implementing disk-based caching

Enabling disk caching for a JPEG is a two-step process.  Authoring caching into your Help or Viewer project is a simple matter of adding a “+” to the embedded window statement before the archive name.  This lets you specify caching on any or all JPEGs at your discretion.  JPEGs can be cached to the hard disk whether they are included alone in baggage or as part of LZH-compressed libraries.

Here’s a sample embedded window statement which demonstrates the proper placement of the “+” caching flag.  This statement points to a JPEG contained in BITMAPS.LZH which is included as baggage:

{ ewc THNHLP,THIN,+!BITMAPS.LZH;MYPICTUR.JPG }

This statement points to a JPEG in the same BITMAPS.LZH library located outside the helpfile:

{ ewc THNHLP,THIN,+BITMAPS.LZH;MYPICTUR.JPG }

This statement points to a JPEG included as baggage but not as part of a compressed archive:

{ ewc THNHLP,THIN,+MYPICTUR.JPG }

Since ThinHelp’s disk caching can make use of author-defined .INI entries, disk caching can be implemented in titles designed to be run from a CD-ROM drive or floppy disk, but only if cached files are to be stored on the hard disk.  Due to the size of cached DIB datafiles, hard disk caching is not recommended for projects using a large number of JPEG graphics unless a proper “cleanup” routine is supplied to prevent large amounts of unwanted cache data from accumulating on the end user’s system.

.INI control over cached JPEGs

ThinHelp allows you to specify where .CAC files will be stored and retrieved using entries in WINHELP.INI.  These entries need to be handled properly by your installation software in order to function properly in the installed software, and this method of implementing caching is recommended over ThinHelp’s default caching method, which deposits cached bitmaps in the directory where the helpfile is found, whenever large JPEGs are used.

Each bitmap requiring caching should be referenced in WINHELP.INI using the following syntax:

[FILES]
filename.cac=path

...where filename is the prefix of the JPEG file needing to be cached and path is the directory path where the cached file is to be stored.  Here’s an example using the ThinHelp tutorial helpfile:

[FILES]
TR007.CAC=G:\HELPSTUF\THINHELP

...deposits the cache file for the lagoon scene JPEG gracing the title topic in the \THINHELP\ subdirectory of someone’s G:\HELPSTUF\ directory.  We chose this example because it demonstrates one of the problems to watch for with ThinHelp caching.  You need to be able to write the appropriate .INI entries using your installation software.  In this case, the installer detects that ThinHelp was installed to G:\HELPSTUF\THINHELP\ rather than C:\THINHELP\ and writes an .INI entry appropriate to the installation.

Keep in mind when setting up your .INI entries for cached JPEGs that you’ll need to include the appropriate delete commands in the software’s uninstallation routine if you do not wish to leave large cached files behind on the end user’s system.

Technical information

The filename is a hexadecimal number representing the hash code for the graphic and compressed graphic library specified.

The following types of graphics cannot be cached to the hard disk:

•  transparent .BMP bitmaps

• .SHGs which originated as .WMF-format metafiles

• .SEG files generated by Push which contain metafile overlay information

Customer relations

.CAC files created by ThinHelp will vary in size depending on the resolution of the target system.  A .CAC file generated on a TrueColor or HiColor display will be three times larger than the same .CAC file generated on a 256 color system, which in turn will be larger than a .CAC file generated on a 16 color system.

Large numbers of .CAC files could quickly fill the hard disk of an unsuspecting user with TrueColor display mode enabled.  If your project depends heavily on .CAC files to enhance performance it is recommended that you add courtesy messages to the project letting the user know where these files are located and informing them that they can be safely erased at any time to recover lost disk space.

Cautions about cache implementation on networks

Configuration of ThinHelp projects using disk caching which may be installed on networks should be handled with careful attention to the various display types which may be in use and the storage location of the project.

The workstation that launches the topic containing the cachable JPEG for the first time will be the one to define what resolution this .CAC file will have.  If a TrueColor-capable workstation launches the project, 256 color workstations accessing the same topic in the same project will get the advantages of the increased display speed but the graphic will suffer distortion since the source DIB data for the graphic will be TrueColor.

Generally speaking, in network installations where multiple display resolutions will be in use, two or more installations should be made and separate sets of icons or shortcuts should be created and assigned to the appropriately-configured systems based on their graphics capability.  This will insure that 16 color systems access dithered .CAC files appropriate to their displays while TrueColor systems access a different installation offering TrueColor .CAC files.

Notes, tips and issues

 There is no significant advantage to caching BMPs.  This feature is intended for application with JPEGs only.

 There is currently no control over disk space usage when caching JPEGs to the hard disk.  Take this into consideration when setting up the title so that the end user’s hard disk is not overloaded with cached JPEG graphics.  Each 640x480 JPEG graphic will produce a cache file of approximately 300K in size at 256 color depth and approximately 900K in size at 32K color depth and higher.  This means that a 1Mb helpfile containing 50 400x500 JPEGs could consume over 40Mb of hard disk space if all bitmaps are flagged as cachable.  A small .BAT file can be added to the installation and launched from the helpfile itself which will allow the user to erase cache data to restore lost disk space on demand.

 .CAC files are not hidden and can be easily erased.  If your installation software’s uninstall scriptor supports wildcards, add an entry to erase all files in the installation directory ending in .CAC (e.g. *.CAC) when the installation is removed.  You can also specify the .CAC files by name.  They are assigned names based on hash values, not at random, so the .CAC files created on your development system will have the same names as .CAC files created on the end user’s system.


Hardware requirements

If you use WinHelp or Multimedia Viewer to build stand-alone applications that will not be bundled with other software, but will instead be used for advertising, as electronic books or as educational software, the hardware requirements of add-ons, extensions and accessories for Help become very important because you can’t always know what kind of hardware will be available on all target systems.  Developers of context-sensitive help for applications will need to consider memory requirements for WinHelp and the application.

Stand-alone helpfiles can run under Windows 3.1 in standard mode in less than a megabyte of memory.  ThinHelp was carefully engineered to be usable on the most poorly-equipped Windows PCs -- even 80286 workhorses which were never meant to run Windows -- but ThinHelp-enhanced helpfiles will certainly perform better when they have a bit more room to function than normal Help.

CPU requirements

ThinHelp is high-tech software that respects its users.  It has been designed to run on any machine that supports the Windows 3.1 API.  Any machine.  That means even ancient 80286 machines and RISC emulators suchg as SoftPC, SoftWindows (PowerPC) and WINE (untested) which are only capable of running 286 standard-mode code.  Your compiled ThinHelp projects will be usable on the Apple Macintoshes with SoftPC (although the DLL won’t work through the infamous ResEdit/Excel hack because the DLL is not a Mac binary), and on RISC-based machines such as the DEC Alpha running Windows NT in 80286 processor emulation mode.

Memory

ThinHelp decreases hard disk space requirements by using LZH compression technology, but it will allocate extra memory for itself to handle the decompression of the bitmaps if this memory is available on the user’s computer.  LZH compressed bitmaps alone do not consume a lot of memory, making THNBMP.DLL the ideal choice for low-powered systems, but JPEG decompression requires a lot of temporary buffers.  Here’s how memory management plays out with ThinHelp:

LHA handling

1. Buffers are required for the ThinHelp decompression data segment (8 Kbyte)

2. LZH compressed data read from the helpfile (extraction buffer).

3. Buffers required during LZH decompression (less than 64 Kbyte)

4. LZH decompressed data block containing either JPEG or BMP data

JPEG handling

1. JPEG-decompressed 24 bit bitmap (width x height x 3 = total bytes required)

2. Buffers during dithering (Up to 128 Kbyte)

3. The dithered 8 bit bitmap (width x height x 1 = total bytes required)

4. Animation frames ready to be shown on the display (width x height x 1 x number of animation frames x count of embedded windows = total bytes required)

5. Data frames cached and ready to be shown onscreen but not yet displayed...bitmaps shown in a previous topic for example. (width x height x 1 bytes x number of cached bitmaps = total bytes required)

6. Temporary DDB handle used during bitmap display (width x height x 1 bytes = total bytes required)

Before using the bitmap cache, ThinHelp checks to see if there are more than 600,000 available bytes left in memory.  If memory is tight, caching will not be used.  Memory conservation is one reason why ThinHelp operates reliably even the slowest Windows machines.

When several bitmaps are displayed on the screen at once, memory demand defaults back to this equation:

width x height x 1 bytes x number of animation frames x number of embedded windows onscreen at the same time = total bytes required

During decompression of individual bitmaps ThinHelp will need an approximate extra:

width x height x 5 bytes = total additional bytes required

The biggest JPEG file uses in the example helpfile requires about (620 x 420 x 5) = 1,045Kbytes during decompression.

The flower image requires (227x149x5 bytes) = 170 Kbyte during decompression.

Estimate peak memory requirement at about 500 Kbytes.  When less than 500 Kbytes are available, the helpfile will still display on the user’s screen, but the bitmaps may not be visible.

Additionally, if enough memory is available ThinHelp will cache each decompressed image as DIB memory for use in subsequent topics.  This caching is dynamic and dependent on available RAM memory on the target system.

Display driver

ThinHelp will try to make the best possible use of the given display. The best available technology is 24 bit TrueColor and ThinHelp will support this resolution.  However, most installed systems use 256 color palette-driven display devices.  ThinHelp supports dithering to 256 colors with optimized and standard palettes and allows palette sharing with other applications.  If the display supports only VGA -- even 16 colors -- a Floyd-Steinberg dithering algorithm will be used to make sure the image is at least viewable on the display, if not of the highest quality.

CGA and Hercules displays are not supported. They are treated as VGA displays and Windows will map the image’s color palette to two color black and white.  Don’t expect pleasing results on CGA and Hercules from anything but the highest contrast screen shots, icons and simple line art.  Memory requirements for dithered bitmaps will depend on the display device.

Printing

When printing a ThinHelp embedded window, the print quality depends primarily on the quality of the printer driver in use.  Printer drivers supporting error-diffusion dithering, such as the HP LaserJet series, give better results than those without this feature.

Memory requirements for printing depend on the driver, and these are generally quite high for graphics-intensive topics.  Significant reductions in print time can be provided to the end user by setting large or nonessential bitmaps as nonprintable from the helpfile using 32 as a portion of the display type parameter.


Memory management via THSetCacheSize()

Insuring compatibility with context-sensitive help and contracted applications

ThinHelp features author-controllable memory usage through the THSetCacheSize() macro.  This function is entirely optional.  In addition, ThinHelp’s dynamic memory management makes the implementation of this function unnecessary for most distributions.  But there may be circumstances in which you’ll find it indispensable.

Developers expect Help to be the last thing they need to worry about when calculating memory requirements.  But in a screen-shot-heavy help system, it’s all too easy to present a drop-dead gorgeous, ThinHelp-enhanced helpfile only to be shot down by a marketing department that can’t see past the 5Mb of memory a procedural slide show or series of large screen shots consumed on a 64Mb system and can’t be convinced that your helpfile will be stable and quick on 80486 4Mb client systems.

You’ve seen ThinHelp in action.  You know this isn’t the case.  But as a Help author you may not even be given the opportunity to prove what you’ve seen for yourself.  THSetCacheSize() will allow you to bypass objections from marketing and technical and insure that your efforts don’t get vetoed prior to production.

How THSetCacheSize() works

By default, ThinHelp will adapt itself to the system on which it is used.  It will use up to 20 percent of available system memory, caching the file’s bitmaps as they are displayed for use in subsequent topics.  It is also optimized for use with older or overstressed systems and will use no cache at all if it finds less than 600K of free memory.

THSetCacheSize() assigns a fixed amount of memory for use by ThinHelp which may not be exceeded on the target system.  When ThinHelp reaches this memory limit, it uses disk access instead of cache functions.  And even if you have multiple ThinHelp-enhanced files open on the desktop at once, all files will share the same pool of cache memory, offering the potential for a substantial improvement in performance if you use external graphics libraries in multi-file systems.

This cache is dynamic, meaning that even a large default cache will be released to other programs that need it.  ThinHelp will only begin using cache memory when it needs it, even if an overly large default cache size is specified by mistake.

Steps

1. Ascertain the minimum RAM requirements needed for the application and help system combined.

2. Discuss the needs of the software with developers and, if need be, those who contracted the software’s design to determine exactly how much memory ThinHelp will be allowed to use in order to fall within the specifications of the project.

3. Once you have determined the maximum amount of memory that ThinHelp will be permitted to use for its bitmap cache and the minimum amount of free memory to leave untouched regardless of the system in use, register the THSetCacheSize() macro in the [CONFIG] section of your helpfile and add a THSetCacheSize() macro immediately following the RegisterRoutine() macro which will set the memory parameters.  Here’s an example of registration and execution macros designed for use on 6Mb to 8Mb systems in conjunction with a fairly memory-hungry application:

RR(`THNHLP', `THSetCacheSize',`UUU')

THSetCacheSize(500000,3000000,0)

The first parameter in the macro is the maximum number of bytes (not kilobytes or megabytes, but bytes) of memory that ThinHelp will be permitted to use for bitmap caching regardless of the system in use.  The second is the lower free memory limit, below which ThinHelp will use no internal caching at all.  The third parameter is always “0”.  This sample limits ThinHelp to a half-megabyte of cache memory for its bitmaps and insures that no cache is used unless at least 3Mb of free RAM is available.  These settings should please even the pickiest contractor or developer, although there may be a degree of performance loss in your helpfile when displaying some topics in a graphics-heavy project.

A sure-to-please solution for tricky situations

If your title is destined for use on a secure network or intranet, you may encounter situations where you need to have two or more different sets of ThinHelp cache parameters in your compiled help in order to insure that the helpfile performs optimally on all needed systems.  This can be accomplished in seconds, without recompiling, using Bent Lynggaard’s free WH_WEDIT.EXE utility which, in its most recent versions, can add new [CONFIG] macros to compiled 16 and 32 bit helpfiles from its Edit option.  This utility must only be used on copies of the original helpfile.  It must be tested prior to installation.

WH_WEDIT.EXE is available for download from Winsite, Garbo and SimTel archives and can also be found on the better WinHelp ftp sites.

Notes, tips and issues

 Setting THSetCacheSize() parameters for all ThinHelp-enhanced Help or Viewer titles is not recommended.  Doing so will usually compromise systems either at the higher end of the performance spectrum or the lower end.  Limiting the cache to 500,000 bytes will result in performance degradation on systems with 6Mb or more, particularly in graphics-intensive titles, and expanding the cache to 2,000,000 bytes places an unnecessary strain on similarly-equipped systems.  ThinHelp’s defaults are optimized to provide the best possible performance on the widest range of target systems.

 When calculating memory requirements, keep in mind that when ThinHelp displays the same bitmap in multiple locations in the same topic or helpfile, it only needs one copy of that bitmap in its cache.

 THSetCacheSize() is a global macro.  That means that whenever multiple instances of ThinHelp-enhanced files are in use, the same memory pool is shared by all instances.


Distributing helpfiles with extension DLLs

ThinHelp has been tested and proven on several continents and with distributions numbering in the hundreds of thousands.  When properly installed, it should provide trouble-free operation for as long as the helpfile and the proper ThinHelp DLL remain in their installation directories.

Achieving this degree of reliability was our job.  But insuring reliability when creating your distribution package is your responsibility.  Getting DLLs to work reliably with WinHelp is not the heavy load that some authors who have had bad experiences might claim, but it’s not a task to be taken lightly either.

Take the utmost care with your first few distributions to insure that installation is handled properly by the setup software.  Once you discover how reliable a properly-configured WinHelp or Viewer third-party DLL can be, any hesitation you may have about adding new DLLs to Help or Viewer projects should be replaced by relief...and a little extra space for the creativity which will make your ThinHelp projects stand out.

An important note for Multimedia Viewer authors

Viewer authors should specify INI values and file locations pertinent to ThinHelp’s DLLs to VIEWER.INI instead of WINHELP.INI.

A serious warning about redistributing shareware versions

Under no circumstances is the unregistered version to be redistributed except as the complete, unmodified ThinHelp demo archive.  Under no circumstances is the demo archive to be re-archived or altered in any way for purposes of redistribution.  Distributing an unregistered version of ThinHelp could render any installations of ThinHelp-enhanced helpfiles on the end user’s system unusable.  Under certain circumstances this may result in civil or criminal action not just by Herd Software Development but by any and all affected parties including other distributors of Help and Viewer products enhanced with ThinHelp.

Registered users are also cautioned not to install demo versions of ThinHelp over existing registered ThinHelp installations.  Doing so will usually necessitate a reinstallation of the registered version to restore functionality.  Updated downloadable demos will also be reflected by updated registered version helpfiles which will contain any needed updates to the documentation.

Setup/installation software

Whenever you distribute a helpfile as a stand-alone application, especially if its userbase will include novice users, it’s almost always a good idea to include a setup program to install a Program Manager icon or Start menu shortcut.  Our ASETUP software is available free for use in distributing your helpfiles, and if you follow the instructions in the tutorial you’ll discover that ASETUP can even create self-extracting, auto-starting, compressed .EXE files using the same high-efficiency LZH compression used by ThinHelp...and with a lot less overhead than most other installation packages.

Installation paths and directories

Microsoft recommends installing DLLs to the \WINDOWS\SYSTEM\ directory.  This is the most reliable method, but it is also the most intrusive.  As long as the module or filename of the DLL is referenced properly in the helpfile and the helpfile is installed using the correct setup parameters, this method of installation is not necessary.  ThinHelp’s DLLs are small files, and there’s no reason why you should not be able to install them into the same directory as the helpfile itself.

When installing the DLL file in the same directory as the helpfile, make sure that the software’s startup directory is also referenced in the Start menu shortcut or Program Manager item’s Properties.  You can’t simply reference the path to the file on the Command line and be done with it.  Matching the startup directory and the command line will insure that the helpfile can always find the DLL when it needs it.  This applies to all embedded window WinHelp and Viewer DLLs, not just ThinHelp.  Macro DLLs do not require the specification of a startup directory.

If specifying a startup directory is not possible (e.g. if your helpfile will be installed to a support files directory and called as context-sensitive help), then you should specify the path to THNHLP.DLL in the [FILES] section of WINHELP.INI.  This will insure that the file is accessed properly...provided the installation is not moved or otherwise altered by the end user.

We recommend adding a notation to the distribution’s README.TXT if WINHELP.INI is used to reference THNHLP.DLL.  This will often simplify troubleshooting by the end user and save both distributors and users from many support calls.

Communicating with developers/packagers

If you develop helpfiles which will be packaged by another department, or context-sensitive help for applications, it’s important that either the developers or packagers, or both, be informed of the use of DLL extensions by your helpfile.  In the case of ThinHelp, this information will be needed to properly determine the optimum memory and hardware requirements of the finished package (minimum requirements should be virtually unaffected), and to insure that all of the correct files are included in the package and installed into the correct directories.  There are no known incompatibilities with this version so memory requirement should be the only vital issue here.

Data security: who can steal your graphics?

If you are concerned about the security of your graphics data, we have bad news.  If WinHelp can display it, an end user can steal it.  This doesn’t just apply to WinHelp but to any Windows software.  Quality screen capture software can lift any bitmap from virtually any program, and we know of no effective protection against anyone determined to lift graphics from Help or Viewer titles.  Legal or not, help decompilers are used by WinHelp authors everywhere to learn how certain tricks were done and examine components of a helpfile.  All displayed text can be copied from a standard helpfile by anyone with the 32 bit Help viewer.

The only effective protection against this sort of theft is to encrypt the helpfile itself and insure that topics containing protected text or graphics can only be accessed through a password.  ThinHelp does not provide this type of security.


Issues relating to Windows versions

Cross-platform installation considerations

ThinHelp is provided both as 16 bit and 32 bit DLLs.  Special consideration must be given to the target operating system on which your helpfile will be used in order to insure optimum compatibility.  Here are the main points to keep in mind:

Windows 3.1:

Use THNHLP.DLL only, not THNHLP32.DLL.  Place THNHLP.DLL in the directory containing the helpfile (preferred by most users) or the \WINDOWS\SYSTEM\ directory (preferred by Microsoft).  If you expect your helpfile to be used on Windows 3.1/3.11 systems with Win32s 1.30 or higher, use the 16 bit THNHLP.DLL...but be aware of the issues with Windows NT discussed below.

In pre-release testing, THNHLP32.DLL functioned normally when used in a 16 bit helpfile in Windows 3.1/3.11 which was loaded into the 32 bit help engine included with Win32s 1.30, but this application is not recommended due to the memory overhead required by Win32s.  There is a variety of other issues relating to the 32 bit emulation subsystem which makes it unsuitable as the main Help engine for Windows 3.1/3.11.

Windows 95:

No special considerations.  Place THNHLP.DLL and/or THNHLP32.DLL in the directory containing the compiled file or the Windows SYSTEM-Directory. You may use both THNHLP.DLL and THNHLP32.DLL for files compiled with HCRTF.EXE and HC31/HCP.EXE.

Developers planning for future compatibility should keep in mind that upgrade versions of Windows 95 are likely to behave more like Windows NT.

Windows NT 3.5x:

Special care must be taken with helpfiles destined for use on Windows NT because Windows NT 3.50 and higher (including 3.51) don’t have the luxury of the Win32s Help engine available in Windows 3.1/3.11, nor do they have the backward compatibility of Windows 95’s WINHLP32.EXE.  If NT’s Help engine detects a 32 bit helpfile and only 32 bit DLLs, it starts the 32 bit Help engine.  If it detects a 16 bit DLL being used in a 32 bit helpfile, it starts the 16 bit engine.  The 16 bit WINHELP.EXE in NT is the exact same help viewer used by Windows 3.1/3.11, and this version will not display 32 bit helpfiles.  If in doubt, it is suggested that you use 16 bit Help and 16 bit DLLs which will be usable on all current versions of Windows.  This combination has the added advantage of being compatible with most Macintosh and UNIX systems equipped with WinHelp or Windows emulation software.

When in doubt, always match 32 bit helpfiles with 32 bit DLLs and 16 bit helpfiles with 16 bit DLLs when distributing any help system destined for Windows NT use.

Windows 16 bit and 32 bit help engines in Windows NT:

The 16 bit Help engine which comes standard with Windows 3.1/3.11 cannot use 32 bit DLLs even if you have Win32s 1.3x installed. 16 bit applications using WinHelp() API calls can only use the 16 bit WINHELP.EXE help engine.  This version of WINHELP.EXE cannot display files created by HCRTF.EXE.

If the 32 bit Help engine in Windows NT encounters a call to a 16 bit DLL it will display a message box, close the file and start the 16 bit WINHELP.EXE to display the topic.  In many cases the machine crashes during this process.

A work-around for 16 bit and 32 bit compatibility problems on Windows NT

If you want your help file to run properly on all three common flavors of Windows, you’ll need to take a little extra care with installing the software and registering macros.  Here are the steps for complete version-independent compatibility.

1. Compile your helpfile as a Windows 3.1 Help file using HC31.EXE or HCP.EXE.

2. Set up the installation software so that it includes both versions of THNHLP.DLL.  The 32 bit version should be renamed to THNHLP.DLL instead of THNHLP32.DLL.

3. When it installs, have the installer check versions.  Top-quality installation software such as our own ASETUP includes this level of preinstallation diagnosis.

4. If Windows NT is detected, have THNHLP.DLL (or THNHLP.DL_) copied to the \SYSTEM32\ directory of Windows NT and renamed to THNHLP.DLL.

5. Have the installer also copy the 16 bit THNHLP.DLL, but this file should be installed to the \SYSTEM\ directory of Windows NT.

Another option for Windows NT compatibility

If you don’t like the idea of storing files in the user’s system directory, or can’t access this directory on a network, try this approach,

1. Copy the helpfile, THNHLP.DLL (32 bit) and THNHLP.DLL (16 bit) into three different directories. These can be subdirectories of your installation directory.

2. Manually, or with the help of your installation software, insure that an entry is added to WINHELP.INI.  It should read as follows:

[Files]
THNHLP.DLL=C:\MYDIR\DLL16,THNHLP.DLL not found

...where C:\MYDIR\ is the drive and directory where the software will be installed, \DLL16 is the subdirectory where 16 bit THNHLP.DLL will be installed, and THNHLP.DLL not found is the message to display in case of an error.  The 16 bit help engine can now find the appropriate DLL.

3. Next you need to let the 32 bit help engine know where to find THNHLP.DLL.  Place an entry such as this in the registry.  Once again, you should be able to get your installation software to handle this chore.

HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\Help\thnhlp.dll = C:\MYDIR\DLL32

This process works because 32 bit WinHelp will look first to the registry, while 16 bit WinHelp depends first on WINHELP.INI for its file locations.


Using THNHLP.DLL as an import filter DLL
THNHLP.DLL as an import filter

THNHLP.DLL and THNHLP32.DLL both include a function THDecJpgDib that may be useful in non-WinHelp applications to decompress a JPEG-compressed memory block into a Global Memory Handle.  See the file JPGDEC.H for details.

C and C++ developers can create an import library (LIB file) using the IMPLIB utility included with the compiler.  Add this import library to your project with your Link Project.

The function call

HGLOBAL FAR PASCAL THDecJpgDib(LPVOID lpJpgData, DWORD dwBlkSize, DWORD Dummy1, DWORD Dummy2);;

Parameters

lpJpgData:	Pointer to a data block containing the JPG-compressed image
dwBlkSize:	Size of this data block in bytes
Dummy1,
Dummy2:	Currently not used, reserved for future definition applications.  Pad this parameter with “zero”.
Returns:

A handle to a global memory block allocated with GlobalAlloc in CF_DIB-Data-Format.

Use GlobalLock to retrieve a Pointer to BITMAPINFOHEADER (or, in OWL 2.5, use TDib ADib(Handle);) to create a TDib-Object from it.

The return value will be NULL if the function does not succeed.

 NOTE: Illegal input data may result in abnormal program termination without returning from DecJpgDib.  Examine JPGDEC.H for more detailed information.


Baggage file size limits

 In theory, several thousand bitmaps may be compressed into a single [BAGGAGE]’d LZH-archive.  There is no known limit on file size, but size isn’t the most critical issue.

LZH archives structure their file systems differently from PKZIP.  Long lists of files take much longer to retrieve from LZHs than with PKZIP-compressed archives, and there is an absolute limit of 1,000 bitmaps per LZH archive...not a limit you’re ever likely to reach.

In general it’s a good idea to keep each LZH archive under 70 files for recommended installation on 80486-DX and higher, half that for 80386 installation.  You’ll also find that using several LZH files rather than just one speeds the task of updating, freshening and organizing your bitmap archive baggage.

You may also find when using archives of a fairly large file size (250k compressed and higher) that you get better performance by splitting them up into archives of 200K each or less.  This is something you may have to experiment with, since ThinHelp projects used primarily on 386-SX machines might benefit from even smaller archives with even fewer files.


Maximum allowable simultaneous images

The JPEG decompression software in ThinHelp allows several images to be shown simultaneously without color palette distortion.  However, the same color palette will be used for all JPEG-decompressed pictures onscreen at one time.  This will produce a noticeable reduction in display quality on 256 color systems.  This degradation of image quality is as unavoidable with JPEGs in Help as it is with JPEGs in HTML.

ThinHelp caches up to 100 decompressed pictures in memory, but the amount of actual memory ThinHelp uses is calculated as a percentage of available system memory.  ThinHelp will use available free RAM until free memory is smaller than 600Kb or the cache reaches 20 percent of available system memory, whichever comes first.

This behavior is author-controllable via the THSetCacheSize() macro which is normally executed from [CONFIG].


Undocumented features in ThinHelp

Any new product featuring this level of sophistication and user-configurability is bound to have a bundle of undocumented features.  The authors of the documentation discovered new uses and applications for ThinHelp virtually every day during the development of the documentation, and many of the more obscure or technically difficult applications we discovered for ThinHelp were deliberately omitted from THINHELP.HLP.

If you find a unique application or feature in ThinHelp you think other users might like to know about, tell us about it by filling out our user survey.  Registered users receive updates by email and we’ll be glad to compile a list of these features for others to peruse.  Let us know if you’d like your email address used in the report in case others find bugs or new features they want to inform you about.

Please keep in mind that “undocumented” must also mean “unsupported”...unless, of course, we’ve created the documentation for the feature ourselves.  If an undocumented feature fails to work in a given circumstance, we cannot assume any responsibility for the consequences.


About to launch Help to RTF...

All files in ThinHelp’s help system include complete, uncrippled functionality with our Help to RTF conversion software for allowing you to create Word-compatible documentation from helpfiles including all bitmaps and embedded window objects.  This feature is reserved exclusively for helpfiles included with Herd Software Development software products.  For complete functionality with all helpfiles you will need to own a license to Help to RTF Standard or Help to RTF Pro.

You can use the evaluation version of Help to RTF included in this package to create printable documentation from any of the included helpfiles and optionally load the appropriate helpfile directly into Help to RTF by selecting the Print Some or All Topics... item from each helpfile’s File menu.

Select one of the following:

Launch Help to RTF        Learn more about Help to RTF


A guide to compression, file formats
and optimized display insurance

by Bernd Herd

This section is designed to assist you in understanding the nature of the file compression technologies used by ThinHelp, compatibility issues, and the effects they may have on your completed work.

  Abstract

 A guide to bitmaps and bitmap quality

 A chart of ThinHelp-compatible compression technologies


Guide to compression and file formats: abstract
Abstract

• JPEG compression support and dithering in ThinHelp are designed for photographic (TrueColor/HiColor) images only.

• Do not reduce a bitmap from TrueColor or HiColor to 256 colors prior to applying JPEG compression.

• Do not edit a JPEG file directly unless you have no other options. Use your original TrueColor bitmap for editing instead.

• Dithering is a lossy process that reduces picture quality and blurs the image.  Avoid it whenever possible.

• Multimedia applications for display directly from CD-ROM require different methods of optimization

• Keep the number of files in individual LZH-compressed graphics libraries as low as is reasonably possible to insure optimum performance (one bitmap per LZH archive is quite acceptable).

• Do not use graphics databases (external LZH-compressed bitmap libraries) on CD-ROMs...include them as baggage instead.  Use WINHELP.INI for CD-based applications to properly reference needed files.  (Viewer titles should use the corresponding VIEWER.INI entries.

• Hard-disk-based graphics databases will accelerate CD-ROM performance but must be installed with careful attention to paths and working directories.


A guide to bitmaps and bitmap quality

  A little about light colors, luminances and monitors

  What are bitmaps and how do they work?

  Dynamic palettes: making the most of limited memory

  Dithering TrueColor bitmaps to paletted bitmaps

  Loss of image quality produced by dithering

A little about light colors, luminances and monitors

Color monitors work on principles of color generation through light, not solids.  That means that all colors seen on your monitor, even grey shades, are based on a mix of red, green and blue, which are the primary colors of light.  (Red, yellow and blue are the primary colors for solid objects such as paints and plant pigments.)  These three primary colors correspond to the three types of color receptors in the human eye, and the combination of varying degrees of red, green and blue create all the colors the human eye can detect.  The amount of red, green or blue light energy in a given color is referred to as the luminance of that primary color.  All colors can be defined in terms of their three luminances, or the relative degrees of red, green and blue light energy they contain.

Every TV-type cathode ray tube monitor contains three separate electron gun systems for emitting these red, green and blue light signals.  Electromagnets surrounding the guns target these three beams in precise patterns.  All popular color monitors (but not all monochrome monitors) also have masks with a grid of tiny holes on the inside of the lens which are designed to focus and filter these beams for accurate, distortion-free color display on your screen.  A properly aligned and tuned monitor shows no red or green shadowing where the electron beams stray from their appointed targets in the grid.  Improperly-tuned monitors display a “ghosting” effect where the light beams of one or more of the electron guns miss their targets by small or large amounts.

What are bitmaps and how do they work?

A bitmap is, quite simply, a file formatted as a map of bits, or on/off switches, that have specific meanings.  Bitmap files begin with a series of bytes that define what type of file it is and how the bits are structured to create the map, but the bulk of the file is nothing but a series of characters that represent a collection of bits, and those bits combine to define a degree of color for a specific pixel in the bitmap.  The bitmap is nothing more or less than a definition file that tells the computer where to put the pixel and what color it should be.

16 color bitmaps

The only information contained in normal Windows BMP bitmaps relating to brightness or contrast is a small index of colors near the beginning of the file that the individual pixels use as a reference for selecting possible color values.  Luminances enter the picture indirectly through the color palette included in the bitmap file, and it is the palette, not the bits assigned to the pixels, which contains information about luminance values for the 16 available colors.

But bitmap files can be formatted in a variety of ways.  Standard Windows Help bitmaps, for example, contain only 16 different colors.  Each pixel needs only four bits of data, or half a byte, in order to properly define which color a given pixel shall be.  (2x2x2x2=16, with each combination of  two variables representing a bit here).  This is why standard 16 color bitmaps are often referred to as having “four bit color”.

256 color bitmaps

256 color bitmaps, on the other hand, require a full byte of data to define the color of a given pixel (2x2x2x2x2x2x2x2=256).  These too are mapped to an index table contained in the bitmap file that tells each pixel which colors it may choose from for display.  These bitmaps are referred to as eight bit color.

16 million color bitmaps

And then there are TrueColor bitmaps, the “sixteen million color” bitmaps that use 24 bit color.  They don’t contain charts (can you imagine the size every TrueColor bitmap would be if it did?), and of course they will almost never contain the full 16,777,216 possible colors.  They don’t need charts or color indexes.  All the bitmap needs to know is that when the standards were set down for displaying computer graphics, it was decided that there would be 256 possible degrees of energy, 256 luminances, available to each of the red, green and blue light components of each pixel.  256 is equivalent to eight bits, so of course 256x256x256 possible combinations gives us 16.7 million possible variations, or 24 bit color.  Each pixel of data in a TrueColor bitmap thus requires three whole bytes of data to be defined.

The actual color chart, or index, used by a 16 color or 256 color bitmap doesn’t normally have anything to do with luminances.  But when 16 million color bitmaps are displayed, the colors are based on nothing but luminances...it’s the only logical way to deal with this many possible color variations.

Dynamic palettes: making the most of limited memory

In TrueColor mode, a typical 1024x768-pixel display requires 2.3 megabytes of physical memory.  This memory must normally be housed right on your graphics adapter card.  Your system RAM can’t usually be used for this purpose.  Due to the high price of video memory, which is typically much faster than standard RAM memory, the average PC as of mid-1996 had only 1Mb of video memory.

To reduce the hardware requirements for displaying TrueColor graphics on these systems, they are usually configured to support dynamic 256 color palettes.  A dynamic palette is one which adapts to the needs of the graphics being displayed.  This means that while the average 16 color system can only display the standard 16 Windows colors, a 256 color display can show up to 256 unique colors at the same time, and show a different set of 256 colors for each new graphic displayed on the screen.  (Actually this is only partly true...Windows reserves 20 colors for itself, meaning that most applications are limited to 236 unique colors.)  The 256 possible color selections in a 256 color display can be selected from any of the 16.7 million possible colors, and is called a palette.  The physical representation of these colors on the screen is called the hardware palette.

Any open application on the desktop can request its own unique set of 256 colors, meaning that four open 256 color windows may want to display a total of nearly 1,000 colors at once.  This is clearly “against the rules” for 256 color displays.  Windows tries to work around this conflict by matching the requirements of all open applications.  Each application can ask Windows to compute a logical palette which will be matched, or transferred, to the hardware by Windows itself.  The application normally has no direct control over the hardware palette.

What gives so many multimedia authors fits is that Windows performs this matching differently for foreground applications (topmost windows) than it does for background windows.  This is why Web browser window colors often distort in 256 color mode when you open another 256 color application over top of the browser’s window.

Dithering TrueColor bitmaps to paletted bitmaps

Photographic images and photo-realistic renderings typically use more than 256 different colors, making it impossible to display them without losing a lot of color information.  If you decide to “let Windows do it for you”, you may have had the experience of applying the standard 256 color Windows palette to a photographic image and discovering that the result was completely unrecognizable.  This is typically the result you get when converting TrueColor or optimized 256 color bitmaps to WMFs in tools such as Paint Shop for conversion to WMF files so you can use them as 256 color SHGs.  (It has never been a good idea to display SHGs this way in 16 bit Help and we do not recommend this technique.)

Any quality graphics editing or processing software will provide vastly superior results to Windows’ own built-in palette handling.  The trick is converting the graphic to something that Help or Viewer can display that doesn’t look like a scan of a water-stained magazine page.

Good dithering and bad dithering

Intelligent graphics software can insure that this won’t happen to your graphics by using a bit of computing wizardry called dithering.  Dithering is the process by which the software computes which colors are best for a given pixel in the graphic based on the needs of the whole graphic and the luminance values of neighboring pixels.  Bad dithering makes your graphics look speckled or crosshatched.  Good dithering can make some 256 color graphics virtually indistinguishable from TrueColor.  But don’t be fooled...dithering always degrades the quality of the original image.

Dithering isn’t always needed or even wanted.  Sharply-defined images such as cartoon panels, screen shots and geometric designs will often suffer from dithering effects, both in terms of file size and graphical quality.  A Windows screen shot captured at TrueColor depth and reduced to 16 colors with dithering will compress poorly and look speckled.  A simple color reduction (from 16M colors to 256 or 16 colors) is usually all you’ll need for such graphics.  (Just remember not to allow “error diffusion” in the reduction process...this is a form of dithering.)

There are many different types of dithering in common use in Windows.  The most common implementations are ordered dithering, such as that used in Microsoft’s Video for Windows, which is very fast but produces a great deal of blurring.  Error diffusion dithering, such as that used by ThinHelp, takes considerably longer to compute but gives much better results with highly detailed images.

There are different types of ordered and error-diffusion dithering, too.  Paint Shop Pro, for example, produces a different type of ordered dither from PaintBrush or Paint.  If you have two different Web browsers, you’ve probably noticed that the error-diffusion dithering used in one browser produces much different results from the error-diffusion dithering applied to the same graphic by a different browser.  NCSA Mosaic is famous for its exceptional dithering and palette management, and Netscape Navigator is even more legendary for the opposite reason: its dithering and palette handling are notoriously poor.

Loss of image quality produced by dithering

Reducing a photographic image which uses tens of thousands of different colors to a usable 256 color image must by necessity involve the loss of thousands of individual colors in the process, and it usually requires some type of error-diffusion dithering to insure a reasonable quality of display.  This is a form of lossy data compression that permanently removes information from the image.  It’s a one-way process that can’t be undone once it’s been done.


A chart of compression technologies

There is far more to data compression than the scope of this helpfile permits.  If you’d like a detailed introductory guide to data compression, there is a fairly extensive novice-level tutorial included in the freeware PC Owner’s Survival Guide.  (You can find this on CompuServe via File Finder or on the Internet from www.shareware.com by performing a filename search on SURVGUID.ZIP.)  The information in this helpfile is restricted to ThinHelp-related compression technologies only.

Full name	Abbrev.	File formats using this technology	Typical reductions
Run-length Encoding*	RLE	SHG† Segmented Hypergraphics BMP Windows Bitmaps TIFF  Tagged Image File Format (also known as "Packbits")	5-10 % (image dependent)
Lempel-Ziv*	LZ77	SHG† Segmented Hypergraphics HLP  Windows Help Files	7-20 % (image dependent)
Lempel-Ziv/Huffmann*	LZH	LZH† LHA-compressed archive files such as those used by ThinHelp	30-60 % (image dependent)
Lempel-Ziv/Welch	LZW	GIF CompuServe/ Unisys Graphic Interchange Format TIFF  Tagged Image File Format	25-50 % (image dependent)
Joint Photographic Experts Group*	JPEG	JPG†‡ Compressed image files TIFF‡ Tagged Image File Format (not recommended)	50-90 % (user definable)
Legend

†  File is “as-is compatible” with ThinHelp

*  Compression scheme is supported by ThinHelp

‡  Format produces lossy compression

Run-length encoding (RLE)

What it is

Run-length encoding is the simplest common graphics and binary compression technology.

How it works

The general theory behind RLE is “indexed storage” rather than linear storage.  In other words, rather than storing twenty consecutive grey pixels in the file, it stores a message saying “the next 20 pixels are grey”.

Where it’s used

Microsoft supports RLE compression in many forms.  The Windows 3.0-3.11 startup logo screens are RLE-compressed images.  SHED.EXE-generated SHGs are compressed using RLE technology.  BMP, MRB and SHG files compiled into a helpfile with compression set to maximum are usually LZ77-compressed, but sometimes RLE compression is also used.  CompuServe encouraged and used RLE compression extensively in its early days as a means of reducing the download times for graphics files.

Advantages and drawbacks

A capable programmer can implement RLE graphics compression in an application in only about two hours.  Compression and decompression are also quite fast, making it ideal for applications where low-technology or slow hardware limitations make more efficient schemes impractical.

RLE compression usually gives good results when applied to cartoon panels, line drawings and screen shots, but it can produce a net gain in file sizes when applied to photorealistic images.  Even the application of simple PaintBrush dithering to a bitmap makes the dithered area virtually uncompressable using RLE.

ThinHelp support

ThinHelp supports the RLE compression used in SHG files, but not standard RLE-compressed BMP files such as Windows startup logo graphics.

LZ77 (Lempel-Ziv 77)

What it is

LZ77 is a relatively simple algorithm (at least in terms of modern compression schemes) developed by Messrs. Lempel and Ziv.

How it works

The idea behind Lempel-Ziv 77 is to identify and recreate patterns.  For example, rather than storing one set of bytes at this point in the file and another set of bytes later in the file, it can save a message such as “repeat the pattern found 200 bytes back for 15 bytes”.

Decompression speeds for this relatively efficient algorithm are lightning-fast if coded properly.

Where it’s used

LZ77 is the standard compression technology used by Windows Help for nearly every compressed data block including text, phrases and all graphics (BMP, SHG and WMF). For reasons known only to Microsoft, WinHelp 3.1 implemented both LZ77 and RLE decompression, but the obvious step of applying both LZ77 and RLE compression to the same data block wasn't implemented until WinHelp 4.0.  Microsoft’s semi-mystical “Hall” and “Zeck” monikers for WinHelp 4.0’s compression technologies can’t hide the fact that underneath HCW.EXE’s makeup they’re still the same technologies used in 16 bit Help.

LZ77 compression is used in most compressed Windows disk-based installations, including Windows 3.1/3.11 and DOS 6.xx.  COMPRESS.EXE is the tool used to create these compressed files.  LZEXPAND/LZ32.DLL is used to decompress LZ77-compressed files in Windows; EXPAND.EXE is used for the same purpose in DOS.

LZ77 decompression can be blazingly fast when it’s applied properly, and this algorithm is often used to compress .EXE program files to save disk space.  Seldom used now by third-party Windows applications since newer technologies produce superior compression ratios.

Advantages and drawbacks

Unfortunately, Microsoft missed a trick when applying LZ77 in Windows, because while Help decompression is almost unnoticeable on anything faster than a 386-SX, the same file decompression algorithms in LZEXPAND.DLL and LZ32.DLL, used so often in software installation routines, seem to crawl in comparison.

In the author’s opinion, the worst thing Microsoft did to compression technology in WinHelp is the “astounding” speed of the LZ77 compressor in HC31.EXE and HCP.EXE...astounding only in terms of its unbelievable sluggishness.  When you compile a normal Help project with SHG and BMP graphics which are not baggaged or stored outside the helpfile, half of the compile time could easily be spent compressing bitmaps...more if the helpfile is graphics-intensive.

Fortunately the speed of the new 32 bit compiler makes LZ77 compression times bearable for the author of 32 bit Help, but if you’re still authoring 16 bit Help, you’ll save time on all but the smallest projects if you switch off compression in the [OPTIONS] section until you execute the final build of the project.

A dithered color such as pink or orange can be efficiently compressed by LZ77.

ThinHelp support

ThinHelp does not support LZ77-compressed graphics.  It doesn’t need to; this compression is applied to the graphics only during the compilation of the helpfile or Viewer project.

LZH (Lempel-Ziv-Huffman)

What it is

LZH, LZW and ZIP compression are enhancements to the LZ77 compression algorithm.  A second algorithm, known as Huffman coding, is applied to the data in addition to the Lempel-Ziv algorithm.

How it works

Basically, LZH or Lempel-Ziv-Huffman is based on “pattern sets”.  This combination of algorithms can process not just single patterns, but whole sets of patterns.  More complex applications of the LZH algorithm can even process patterns generated by the compression algorithms themselves.

Where it’s used

LHA/LHArc and ZIP/PKZIP are the best-known implementations of modern, highly complex compression algorithms.  LHA and ZIP are not just efficient at compressing data...they’re also fast enough to be standards in their field.

LHA uses a strict implementation of the Lempel-Ziv-Huffman algorithms and is slightly slower than PKZIP, but despite PKWARE’s attempts to make ZIP the “ultimate in all-purpose compression” LHA still generates smaller output files for bitmaps.

Advantages and drawbacks

PKZIP and LHA are both fast, with PKZIP in particular featuring highly-optimized routines intended for commercial data compression where time is as important as compressed file size.  PKZIP-compatible decompresses can generate more the two megabytes of uncompressed data per second on a Pentium P90.  They’re not nearly as fast as LZ77 in decompression, but with the improvement in processor speeds, decompression delays are less and less noticeable.  Haruyasu Yoshizaki’s LHA.EXE was expected to drop out of sight by late 1994 after PKZIP 2.04 set a new standard for compression size and speed, but it’s still popular, and the LZH algorithms are still in wide use in many applications.

Bitmap files compressed with LHA.EXE-compatible LZH compression usually result in file sizes about half of that generated by Microsoft’s LZ77 implementations, which you can test for yourself if you have a copy of COMPRESS.EXE or an LZEXPAND.DLL-compatible installation builder utility.

ZIP compression has been released as a freely-usable file format by PKWARE, but you must purchase a license to use any PKWARE utilities in a commercial setting.  LHA.EXE by Haruyasu Yoshizaki is freeware, and the LZH algorithm itself is freely usable in any form, however compiled applications with LZH support may be commercial products.

ThinHelp support

ThinHelp supports LZH compression not just for bitmaps, but for WAV audio as well.  The bonus HLPLHA.DLL extension supports any LZH-compressed file added to Help or Viewer baggage.

JPEG (Joint Photographic Experts Group)

What it is

JPEG is a standard compression format designed specifically for graphics data by a volunteer organization known as the Joint Photographic Experts Group.  It was intended to fill the need for a compression scheme that would reduce the stored file size of often-monstrous photographic images for transfer over networks and phone lines and archival storage on disk.

How it works

JPEG is a form of lossy compression which achieves its remarkable file size reductions through the application of algorithms designed to reduce the number of colors needed by a graphic with as little impact as possible on the appearance of the graphic on a computer screen or printout.

LHA, ZIP and LZ77 can’t process most photographic images efficiently.  Photorealistic renderings such as those created by raytrace software might compress reasonably well, but natural images are another matter.  There simply aren’t enough patterns in these images for the algorithms to recognize and reduce in size.

Here’s an example.  These two swatches may appear to be identical shades of grey, but the color indexes indicate that they are completely different colors.  If these swatches were single pixels in an order that appeared random to LZH or LZ77 algorithms, compression would be virtually impossible.

Red: 127 | Green: 127 | Blue: 127

Red: 126 | Green: 127 | Blue: 128

The first thing JPEG does to an image is to convert it to 24 bit TrueColor if it was anything else.  (This means that it’s never a wise idea to reduce images to 256 colors before importing into JPEG software...if the image is of photographic quality, the additional reduction will degrade the quality of the image.)

Next the luminance (brightness or energy values) are separated from the chrominance (color information) in much the same way that the NTSC or PAL do for television. The reason is that our brains detect sharp images mainly in the luminance information, so the chrominance information can be much less exact without us noticing it.

Here’s where it gets technical.  The resulting data is then fast-fourier-transformed (FFT) on a 16x16-pixel base, several bits are omitted (more luminance than chrominance bits are stored) and the data is then compressed using Huffman coding, resulting in the eventual JPEG file.

When loading the data the whole process is reversed (Huffmann decoding, inverse FFT, chrominance bits added, etc.) so the end result of decoding a JPEG file for display is always a TrueColor image.

Where it’s used

The technology is optimized for use in a photographic environment and should not be applied to screenshots, cartoon panels, line drawings and similarly simple graphics.  JPEG is often misused with images generated by rendering and filtering software which could create smaller, better-looking GIF graphics, and many slow-loading Web pages are slow precisely because JPEG was used where GIF would have been appropriate.

Instead of providing exact representations of graphic data, JPEG tries to omit data that studies have proven the human eye doesn’t necessarily need for it to register a crisp, clear image.  JPEG is therefore a completely different technology from lossless archivers such as PKZIP and LHA.

Advantages and drawbacks

The compression rate achieved with JPEG compression depends on the desired quality of the compressed image and the complexity of the original image.  If you can live with some visible degradation you can often achieve compression ratios as high as 30:1 (a file size reduction of approximately 96 percent from a TrueColor BMP).  Typical reductions are on the order of 80 to 90 percent when applied to BMP or PCD (Photo CD) images.

The biggest drawback to JPEG is speed.  It is the slowest in decompression of all ThinHelp-supported compression formats.  Even extremely well-tuned bitmap viewer applications can produce delays of several seconds when displaying JPEGs on a Pentium P90 as small as  500x500 pixels.

Some types of photorealistic renderings and raytraces respond well to JPEG compression and some don’t.  This is something you’ll need to discover with individual graphics.  Generally speaking, however, if it originated as a photograph it is probably best processed with JPEG.

There is never any color palette information stored in a JPEG file.  It originated as, and will always be displayed as, a TrueColor bitmap that does not require a palette.  So when ThinHelp loads the JPG file it has to determine an appropriate color palette based on the bitmap itself and the end user’s screen resolution and dither the bitmap in a fashion appropriate to the user’s screen resolution.  Storage of an optimized TrueColor image as a 256 color BMP file in an LZH-compressed archive provides considerably better display performance than JPEG.

ThinHelp support

If you need the best possible display quality and the source image is a TrueColor bitmap, then JPEG is the preferred compression scheme.  Users with 24 bit display resolutions will observe no dithering at all.

If the bitmap originated as a GIF or 256 color bitmap, you might get a smaller file by compressing it with JPEG but you will lose image quality in the process.  If you load a JPEG-compressed bitmap into an editor and save it again as JPEG you’ll get an additional loss of quality with each successive load-and-save.  So if you store bitmaps as JPEG files for use with ThinHelp or HTML, you should always keep copies of the original TrueColor bitmap in BMP or uncompressed TIFF format.  This is why Push does not save the JPEG image if you don’t explicitly tell it to do so.


NTSC and PAL/SECAM: definitions
National Television Standards Committee (NTSC)

 Committee responsible for approving standards for data transmission using television signals.  NTSC is the format used for both professional and consumer-level videotape in North America.

Also refers to a video display type, used mainly for high-resolution 16 million color Targa-format graphics.  Also (abbrev. pejorative): Never The Same Color

PAL, SECAM

PAL and SECAM refer to TV broadcasting and videotape standards used in Europe and Asia.  The two are not compatible, so the two formats must be converted for retransmission when broadcast and videotape material are transferred between countries using the different formats.  PAL uses a 625-line screen at 25 frames/second and SECAM provides for 819 lines, a significant improvement over NTSC’s 525-line screen image.

(From the PC/Internet Lexicon ©1996 D:\Mystify Software)


Note that the actual hardware capability of most VGA adapter cards permits a representation of 6 bits, or 64 luminances, for each of red, green and blue.  This limitation has no effect on the software, but it does mean that even in TrueColor mode, your display is probably limited to only 256 colors out of a possible 64x64x64 or 262,144 colors.

This limitation should not apply to SVGA adapters capable of TrueColor resolutions.


The LZW compression algorithm (not the file format but the compression algorithm itself) was developed by the Unisys Corporation who also hold and administer a patent on it.  Data compression algorithms are considered to be patentable processes.


GIF format: definition
The CompuServe GIF (Graphics Interchange Format) is mostly used in online environments where graphic files need to be as small as possible and usable on as many potential platforms as possible.  It is the most-used graphics format on the World Wide Web, with JPEG running a distant second.

There was some fear in 1994/95 that GIF would have to be replaced as a cross-platform graphics standard when CompuServe and Unisys, who jointly hold the patents on the GIF compression algorithm, served notice that they would be levying royalties on the use of the GIF format.  This prompted many experts to push for the burgeoning Portable Network Graphics (PNG) format as a successor to GIF.

PNG never actually caught on after CompuServe gave in to public pressure.  Rather than imposing royalties on all use of the GIF file format, these are levied only against developers of for-profit software which actually generate files in the GIF format.  So while the maker of your favorite Web graphics processor may pay a royalty, you won’t have to.


“Lossy” compression: definition
“Lossy” compression technologies depend on intelligent manipulation of the information contained in the file so that the end result will appear as undistorted as possible.  Lossless compression technologies such as PKZIP and LZH can be used to compress virtually any type of information with patterns regular enough to permit compression.  Lossy compression algorithms, however, are data-type-specific.  For example, MPEG video compression uses a different method of compression from MPEG audio because audio data patterns and data requirements are substantially different from those of video signals.

Lossy compression is also “one-way” compression.  Once detail is lost from a file using this type of compression, it cannot be restored in its original form.  This is why it is important to maintain uncompressed versions of data processed with lossy compression (if the file size isn’t too large to make this feasible) and to apply any subsequent editing or processing to the original uncompressed data.

In other words, keep non-JPEG versions of your TrueColor graphics if possible as “masters” in PSD, PCD, BMP, Targa or TIFF format.


Performance and reliability issues for CD-based applications

This section is designed to provide guidelines and the theory behind them for developing CD-ROM based Help and Viewer applications of all types, not just those with ThinHelp enhancements.

 Theory: differences between CD-ROM drives and hard disks

  Track seek times

  To compress or not to compress

  CD-ROM caching...don’t depend on it!

  Enforcing access to the helpfile via CD and insuring proper location

 Methods of graphic storage

  Normal WinHelp/Multimedia Viewer coding

  “With Data” WinHelp/Media Viewer coding

  An alternative to wd coding: ThinHelp baggage coding

  A non-alternative for CD: ThinHelp graphic database coding

  ThinHelp hard disk graphic database coding

  Organizing graphics databases

Theory: differences between CD-ROM drives and hard disks

Track seek times

Most modern CD-ROM drives can access data at rates of 300-900 Kbytes per second, leading one to believe that a CD-ROM drive should be able to access data at about the speed of an older hard disk.

Unfortunately this just isn’t the case in real life.  CD-ROM drives have much slower seek times (elapsed times required to track down the data needing to be read) than even old-style hard disks, meaning that the maximum speed of a CD-ROM drive can only be achieved if the data is read sequentially, or end-to-end, one block of data right after the other.

To compress or not to compress

If you design or intend your Windows Help or Multimedia Viewer applications to read their data directly from a CD, file sizes usually become less important than the overall performance of the application.  After all, you’ve got more than 600 megabytes of space to work with.  You may be in the habit of compressing large bitmaps to make disk space quotas or decrease download times, but when designing CD-based applications this becomes far less important an issue.  It’s seek time -- the time it takes to find the bitmap -- more than it is time needed to read the bitmap -- that must be taken into consideration.

CD-ROM caching...don’t depend on it!

There are huge differences in the data caching algorithms of various CD-ROM interfaces. The DOS 6.x/Windows 3.1x MSDCEX.EXE interface only permits from eight to 64KByte of CD-ROM cache.  A Windows 95 or NT system could dynamically allocate several megabytes of cache for the same purpose...provided the software is installed properly, and many times it is so poorly installed that its performance is extremely slow.  Your CD-ROM may hum along nicely even without a dedicated CD cache controller, but your next door neighbor’s machine may crawl like a slug.

ThinHelp’s caching algorithms allow you to access the same graphic repeatedly in subsequent topics, and as long as the graphic remains in the memory cache, access times will be just as blazingly fast as those of any other memory cache.  And if your system has enough RAM for the job, you can easily accumulate several megabytes of ThinHelp bitmap cache.  ThinHelp doesn’t care whether you have MSCDEX at its worst setting or the hottest update to a commercial CD-ROM cache.  It does its own caching.  So the performance bottleneck occurs when ThinHelp has to find the graphic for its first appearance on the user’s screen, and if performance is an issue to you, speeding up this initial access is where you should focus your efforts.

Enforcing access to the helpfile via CD and insuring proper location

While few users will ever manually copy a helpfile stored on a CD onto their hard disk, you may encounter situations where the user will remove the CD-ROM containing your Help file before they are finished using the Help application.  If you want to be able to access your helpfile from CD-ROM and insure that your user knows what to do if the CD is prematurely removed, place an entry into WINHELP.INI which will tell Windows where this helpfile is to be found.  Here is a template INI entry you can use for developing installation scripts:

[Files]
MYFILE.HLP=n:\mydir, Please place the MyApplication CD-ROM into Drive n and press Enter.

...Where n is the drive letter of the CD-ROM drive and mydir is the subdirectory, if any, on the CD where the helpfile is to be found.

This tells Windows Help to search for the MYFILE.HLP file in the CD-ROM drive D: directory \MYDIR\.  If it can’t be found there, it will ask the user to replace the CD by displaying the text you enter after the comma, which functions as an author-definable error message.  This message text may be modified to suit your requirements.

Viewer authors should specify INI values and file locations pertinent to ThinHelp’s DLLs and corresponding helpfiles to VIEWER.INI instead of WINHELP.INI.

WINHELP.INI entries can easily be created using the Windows API function WritePrivateProfileString.  Most installation software contains facilities for writing INI and registry entries as needed, and your installer should be able to concatenate the proper INI string from variables you specify in your scripting.  If your installation software cannot do this, find an installer that can.

Be very careful not to hard-code D:\ as the drive letter for the CD into any INI entry referring to your CD.  Keep in mind that a growing percentage of users have multiple hard disks or multiple partitions and D:\ may already be assigned.  Installation software designed for use with CD-based applications should permit the use of a variable for the drive letter in any scripting command for generating INI entries such as the one shown above.

Methods of graphic storage

Normal WinHelp/Multimedia Viewer coding

The usual method of referencing bitmaps, the {bmx filename.bmp/shg} statement, automatically interacts with an internal WinHelp cache.  A file referenced with this statement is accessed much the same way as a file added to Help’s internal baggage file system.  But baggage is usually stored a long way from the text associated with it, so WinHelp will require a separate seek operation on the CD-ROM to read the bitmap.  Each time DOS or Windows’ own cache has been flushed or overwritten with new data, that read operation must be repeated.

The WinHelp developers at Microsoft were aware of the potential bottlenecks Help could experience when run from CD-ROM and implemented CD-ROM optimization features in WinHelp for Windows 3.1 and higher.

“With Data” WinHelp/Media Viewer coding

There is a second type of WinHelp bitmap referencing, seldom discussed in authoring circles and usually buried deep in the authoring guides, which is designed specifically for developing CD-based Help: “with data” referencing.  The syntax for this type of referencing is {bmxwd filename.bmp}.  The wd coding tells the compiler to store the graphic with the text, or adjacent in the file to the text to be displayed along with it, so that no additional seeks are required to access the image.

Here are several points to keep in mind about wd coding:

• This type of coding is limited to graphics of an approximate maximum size of 64 Kbyte.  If your BMP cannot be reduced to 64K or less, this type of encoding will not work.

• Each time you use this coding for the same graphic, the compiler adds another copy of the bitmap to the helpfile, even if multiple references occur in the same topic.  This means that your helpfile could easily grow to several times its previous compiled size when using this coding while still providing superior performance.

• This type of coding will only work for 16 color bitmaps destined for 16 bit Help for use on any platform other than Windows 95, or for 16 or 256 color bitmaps destined for 32 bit Help.  It will not work for TrueColor or HiColor graphics.

An alternative to “wd” coding: ThinHelp baggage coding

If you use ThinHelp to read data from the compiled title’s baggage, a CD seek will be required for the first access to that bitmap.  But as long as that bitmap remains in ThinHelp’s cache, no additional seeks will be required.  This will often result in a performance improvement even greater than wd coding.

Try to avoid LZH archives containing multiple files when developing Help/Viewer titles designed to be loaded directly from CD or floppy disk.  A 1:1 ratio of bitmapes per LZH archive will provide optimum performance, since each additional bitmap in the archive will require an additional seek by the CD-ROM drive controller.

A non-alternative for CD: ThinHelp graphic database coding

The dynamic graphic library support provided by ThinHelp is intended only for hard disk installations where it offers the optimum balance of performance to disk space consumption.  Space is usually not an issue on CD, so shared graphics databases (externally stored LZH-compressed bitmap archives) are not recommended.  There is a real risk that the database itself may be stored quite distant from the helpfile and thus produce a much greater delay than a seek to the helpfile’s own internal baggage.

Dynamic graphics libraries could be stored on the hard disk to overcome seek delays, but this would require intrusively installing the libraries to Windows’ path, since there is no easy way of “stuffing” a path string into an embedded window statement.

If space is an issue and shared graphics archives are desirable, try to place the external LZH files and all helpfiles requiring them in the same directory of the CD.

ThinHelp hard disk graphic database coding

While installing graphics databases to the hard disk is not recommended for large bitmap archives, it may be a viable solution for a small archive containing a collection of the most-used bullets, icons, button faces and other interface component bitmaps needed by your application.  Just be sure to install the file somewhere in the Windows path and insure that your uninstall routine or Windows 95 SETUP.INF file can find and remove the archive later if needed.

In this case, you’ll find it both easier from an authoring standpoint and more courteous to your end user not to use the one-to-one bitmap-to-LZH-file ratio recommended for CD-ROM installations.  Even if the bitmap is not in ThinHelp’s cache, you still have SmartDrive, vcache and other standard Windows hard disk cache control devices to fall back on.

For optimum results, try to create archives of small bitmaps.  In testing we’ve found archives of up to 35 bitmaps acceptable for 386-DX33 systems and 70-bitmap archives seem to perform relatively well on 486-DX2 systems.

Don’t use the one-to-one ratio recommended for baggaged LZH files accessed from CD-ROM when you want access from the hard disk.  Two hundred icon-sized graphics, each in their own archive, could consume as much as 1.6 megabytes of hard disk space if installed in separate LZH archives since each individual file must consume a full cluster of hard disk space.  Single clusters could be anywhere from 1Kb to 8Kb in size.  The same number of graphics combined into six or seven compressed libraries could consume as little as 100Kb, a substantial savings in disk space usage and probably worth a slight reduction in the performance of your helpfile.

Organizing graphics databases

Large Help systems installed to a hard disk with several LZH-compressed bitmap libraries could result in an overly cluttered application directory.  This can be easily avoided by insuring that all of the following precautions are taken:

• carefully code your embedded window statements to reference graphics libraries contained in subdirectories of your installation directory.

• specify the exact path of the helpfile or Viewer title, not the path of the graphics libraries, as the working directory for the helpfile when the icon or shortcut is installed.

• insure that all needed graphics libraries are installed to the appropriate subdirectories when building your installation.

Here’s a sample embedded window statement that refers to a bitmap located in a graphics database called ICONS1.LZH which has been installed to a subdirectory of the helpfile’s installation directory called \GRAPHDB\:

{ ewc THNHLP,THIN,./GRAPHDB/ICONS1.LZH;TITLICON.BMP}

Note that the ICONS1.LZH reference is preceded by “./” (dot-slash) and the name of the subdirectory.  The dot-slash is not essential but it is recommended in case you are using Help extensions or macros which alter the default directory used by the helpfile.

It may be tempting to set up the application so that it starts from the installation directory and uses the directory containing your graphics libraries as a working directory.  Don’t do this unless THNHLP.DLL is the only extension DLL added to your project.  There is a real risk of losing the ability to access certain embedded window functions in many popular embedded window extensions if you attempt this type of setup.  It is recommended that you use the relative path referencing shown above for every RTF source reference to a bitmap archive which is to be installed to a subdirectory rather than changing the working directory.