Deploying HTML help 1.x by genesisf

VIEWS: 432 PAGES: 33

									             Deploying HTML Help 1.x            Page 1

                               A Help Think Press Publication

                          HTML Help 1.x
                                                           by Robert Chandler
                                                               The Helpware Group

                                                                     Help Think Press
                                                              A Division of Work Write, Inc.
                                                                 128 South Eastview Avenue
                                                                  Feasterville, PA 19053 USA
                                                                     Tel: +1 215.357.3453

Copyright 2002, Help Think Press/Work Write, Inc. All rights reserved.
                                        Deploying HTML Help 1.x            Page 2

Copyright © 2002, Work Write, Inc. All Rights Reserved.
This document is the sole property of Work Write, Inc. and is protected in its entirety by
copyright law. You must tread this document as you would any other copyrighted
material, such as a book.

Limitation of liability
No patent liability is assumed with respect to the use of the information contained
herein. Although every precaution has been taken in the preparation of these materials,
the publisher/author assumes no responsibility for errors or omissions. Neither is any
liability assumed for damages resulting from the use of the information contained

All terms mentioned in this book that are known to be trademarks or service marks have
been appropriately capitalized. Cheryl Lockett Zubak/ Work Write, Inc./Help Think Press
cannot attest to the accuracy of this information. Use of a term in this book should not
be regarded as affecting the validity of any trademark or service mark.

The publisher welcomes your feedback
This document is published by Help Think Press, a division of Work Write, Inc. Work
Write, Inc. Work Write, Inc. specializes in the development of hypertext user assistance
as well as training on authoring tools and help design. (For more information, see
“About the pubisher” at the end of this document. Help Think Press welcomes (truly! no
kidding!) your comments on these materials and, if we finds them to be valid, will
make every effort to incorporate them into the next edition.

You can reach Cheryl Lockett Zubak at Work Write, Inc., 128 South Eastview Avenue,
Feasterville, PA 19053 USA. Phone: +1 (215) 357-3453; fax +1 (215) 357-0695; email; website

                           Copyright 2002, Help Think Press/Work Write, Inc. All rights reserved.
                                               Deploying HTML Help 1.x                   Page 3

Table of contents
Title page .................................................................................. 1
Copyright.................................................................................. 2
Introduction: Deploying HTML Help 1.x ...........................................4
A few websites you should know about .......................................... 5
HTML Help requires Internet Explorer ............................................. 5
    Why Internet Explorer? ........................................................................... 6
What needs to be updated? .........................................................6
Installing HHUPD.exe ...................................................................8
    HTML Help version 1.3 ............................................................................. 9
Distributing Internet Explorer ...................................................... 11
    About the ISV component install ............................................................. 11
    A few notes and some a little history ....................................................... 13
Installing Internet Explorer “silently” ............................................14
    Implementing the silent installation ........................................................ 14
Advanced registry settings .........................................................19
    Estimating required disk space ............................................................... 19
    Creating a progress indicator ................................................................ 20
Tips for programmers................................................................ 20
Installing your help system (.chm) files ........................................ 22
    Current directory bug .......................................................................... 22
About the Windows Update Installer ............................................ 26
    Source Code ........................................................................................    26
    Shipping ............................................................................................   27
    Customizing .......................................................................................     27
    Debugging .........................................................................................     28
    Localizing...........................................................................................   28
Using IEAK to download IE .......................................................... 28
    Running the IEAK customization wizard ................................................... 28
Which IE components should I download? ..................................... 31
About the author, Robert Chandler .............................................. 33
About the publisher, Help Think Press .......................................... 33

                                Copyright 2002, Help Think Press/Work Write, Inc. All rights reserved.
                                                   Deploying HTML Help 1.x                     Page 4

                                                                          A Help Think Press Publication

                                                                                  HTML Help 1.x
                                                                                                                  by Robert Chandler
                                                                                                                      The Helpware Group

                                     I   n this document, I will cover issues related to installing Microsoft HTML
                                         Help 1.x1 —in particular, implementing the Internet Explorer silent installa-
                                         tion. The processes I will discuss require some programming knowledge,
                                         since they entail setting registry items and so on. But don’t worry if you
                                         aren’t a programmer, since we have provided a free Internet Explorer silent
                                         installation program that can be run in either standalone mode or in quiet
                                         mode from your own installation program. But more about that later.

                                         This document covers such subjects as:

                                              Reviewing the HTML Help system requirements

                                              Understanding HTML Help files that must be deployed

                                              Installing the HTML Help runtime files through HHUPD.EXE
This document and
accompanying sample files were
developed under contract to:                  Distributing Internet Explorer
Help Think Press
A Division of Work Write, Inc.                Implementing the Internet Explorer silent installation
Copyright © 2002, Help Think             1
Press/Work Write, Inc. All rights          You may have heard of Microsoft Help 2.0 as the forthcoming help standard from Microsoft. The public release of
reserved.                                Help 2.0 has been delayed until 2003, although it is certainly available through the Visual Studio .NET Integration
                                         Program (VSIP). Although this document focuses on HTML Help 1.x deployment, the details about IE installation
                                         apply equally well to Microsoft Help 2.0.

                                    Copyright 2002, Help Think Press/Work Write, Inc. All rights reserved.
                                     Deploying HTML Help 1.x            Page 5

   Understanding the free installer

   Downloading Internet Explorer through IEAK

A few websites you should know about
Both the installer and its Delphi source code are available on my web site at:

HTML Help 1.x installation program is a free download from:

Internet Explorer is a free download from:

Details about the Internet Explorer ISV license can be found at:

For documentation on reusing the WebBrowser control, go to:

HTML Help requires Internet Explorer
What does Internet Explorer have to do with Microsoft HTML Help 1.x or
Help 2? Well, a lot actually. Right-click your mouse on the right topic pane
of any HTML Help window and you will see the Internet Explorer popup
menu open. HTML Help uses the Internet Explorer reusable WebBrowser
control to display its help topics. As a result, Internet Explorer must be
installed on the user’s machine before HTML Help 1.x can be used.

                                                                                         Figure 1 HTML Help 1.x
                                                                                         (and MS Help 2.x)
                                                                                         window uses the
                                                                                         WebBrowser reusable
                                                                                         control distributed with
                                                                                         Internet Explorer to display
                                                                                         topics in the topic pane on
                                                                                         the right.

                        Copyright 2002, Help Think Press/Work Write, Inc. All rights reserved.
                                                   Deploying HTML Help 1.x                     Page 6

Why Internet Explorer?
Why does Microsoft require us to install Internet Explorer “just” to view
HTML Help? Don’t they realize how difficult it can be to distribute a
browser, particularly if the user already has a browser installed? Or is this
just a conspiracy to make us all use Internet Explorer?

Let’s think about this logically. What would be the point of a company
developing two HTML viewers, one for help and another for everything
else? It would more than double the development time required to get
HTML Help releases out the door, and, frankly, we would all still be using

Secondly, help developers want to be able to create help systems that have
all of the features of web pages: scripting, style sheets, ActiveX controls,
DHTML, and so forth. If we were to use a “dumbed down” browser created
for creating online help systems, we wouldn’t be able to do all of these
things. I have no doubt that we’d be complaining about that just as loudly
as we might be complaining about having to install Internet Explorer!

In addition, as this chapter will explain, distributing Internet Explorer with
HTML Help 1.x and MS Help 2.x isn’t as difficult as it once was thought.
Microsoft has released the long awaited Internet Explorer 5 silent installa-
tion. This installation package allows you to install IE as a system compo-
nent rather than a browser with a presence on the user ’s desktop. Much of
this chapter, in fact, is aimed at help developers who want to distribute
Internet Explorer components using the silent installation.

What needs to be updated?
To support HTML Help 1.x, the primary technology components that must
to be installed on the user ’s machine are Internet Explorer and the HTML
Help runtime files. These files must be installed for HTML Help 1.x to

A critical discussion that help authors and developers must have centers
around which versions of these components will be installed on user’s
machines. You must decide on the minimum system requirements before
developing the content of your help system so that you’re certain the design
of the help system will be supported by the browser/HTML Help configura-
tion. For example, IE4 or greater is required for Dynamic HTML content,
and IE5 or greater is required for XML support. HTML Help 1.2 or greater is
required if you want the Favorites tab and advanced search options. It’s
important to make sure that the minimum browser upports the type of
content you plan to develop. So plan, and plan early.
  Microsoft Help 2.0 also requires Internet Explorer, but has its own runtime files. The methodology for deploying
these files has not yet been determined.

                                   Copyright 2002, Help Think Press/Work Write, Inc. All rights reserved.
                                                  Deploying HTML Help 1.x                    Page 7

HTML Help1.x requires a minimum of Internet Explorer 3.0, but I highly
recommend that you install IE4 or greater at minimum. (MS Help 2.x
requires a minimum of Internet Explorer 5.0 as it uses XML.)

The table below lists the versions of Internet Explorer and HTML Help 1.x
are installed on various Windows operating systems.

Windows                                Internet Explorer            HTML Help
Operating System                       Version                      Version

Windows NT4                            2.0                          Not installed

Windows 95 Original                    Not installed                Not installed

Windows 95 OSR2                        3.01                         Not installed

Windows 98 Original                    4.01                         1.1a

Windows 98 SE                          5.0                          1.21

Windows 2000 3                         5.0                          1.30

Windows 2000 SP1 3                     5.0                          1.31

Windows 2000 SP2 3                     5.0                          1.31

Windows ME 3                           5.5                          1.32

Windows XP 3                           6.0                          1.33

I recommend that you install the most recent versions of Internet Explorer
and HTML Help since these contain many bug fixes and optimizations. You
may find that older versions of Internet Explorer are no longer available for
download, and license agreements are also no longer available on the
Microsoft web site. My opinion? IE5 is said to be vastly superior to IE4, but
avoid IE5.5 unless you can install Service Pack 2. IE6 appears to be a good
solid release.

  HTML Help 1.x components are now considered to be part of the operating system. All Windows operating system
DLLs are protected on Windows ME/2000/XP and greater. You cannot upgrade these systems unless you upgrade
Windows or apply an authorized service pack. Running HHUPD.EXE will have absolutely no effect if installed on any
of these operating systems.

                                  Copyright 2002, Help Think Press/Work Write, Inc. All rights reserved.
                                                   Deploying HTML Help 1.x                     Page 8

Installing HHUPD.exe
The main installation program for HTML Help 1.x is called HHUPD.EXE.
This free program installs the runtime components of HTML Help.
HHUPD.EXE can be downloaded from the MS web site. Please read the
licensing and distribution license available on the MS web site at:

HTML Help 1.x requires Internet Explorer 3.0 or greater. If Internet Ex-
plorer isn’t already installed, be sure to install it prior to running
HHUPD.EXE. HHUPD.EXE will not overwrite newer versions of HTML Help
1.x. However, it is good practice to check the current version prior to
installing and only install if required.

You can run HHUPD.EXE silently from your own installation program by
using the /r:n and /q:a command line switches. The first switch inhibits the
reboot message seen at the end of the install. The second switch specifies
absolute quiet mode, meaning no setup messages will be displaying during

Example: hhupd.exe /r:n /q:a

Normally a reboot is not required if you’re installing over a previous copy of
HTML Help. However if files were in use at installation time, a reboot will
be required to complete the installation. As a general rule you should ask
the user to reboot after installation.

Let’s look at what is installed by HHUPD.EXE.

Component                          Description

Hhctrl.ocx                         Provides access to all main HH functions and services.

Itss.dll                           Handles the its: and ms-its: pluggable protocols along with the
                                   hard-wired mk:@MSITStore protocol. It is also used for both
                                   compressing and decompressing files.

Itircl.dll                         Controls the full-text search engine.

Hh.exe4                            Windows uses hh.exe to open CHM files. During installation, a file
                                   association is created between .chm files and hh.exe.

hhctrlui.dll                       Installed with HH 1.3 and above. 28 language DLLs are installed
                                   under the “mui” folder in the windows system folder.

  As an alternative or adjunct to HH.EXE, take a look at KeyHH.exe, a free utility developed by KeyWorks Software, a
division of Work Write, Inc. ( This utility works around some problems with HH.EXE,
including opening standalone windows, opening an HTML Help topic from WinHelp, or opening an HTML Help
window based on a keyword search or mapped id.

                                   Copyright 2002, Help Think Press/Work Write, Inc. All rights reserved.
                                         Deploying HTML Help 1.x            Page 9

The ocx and dll files are installed and registered to the Windows system
folder. Hh.exe is installed in the Windows folder.

Caution: Always use HHUPD.EXE to update the HTML Help runtime components. Never install the
individual files yourself.

HTML Help version 1.3
Prior to HTML Help version 1.3, the user had to download and install a
different HHUPD.EXE for each language version of HTML Help. However,
HTML Help 1.3 has been designed for the Windows 2000 multilingual
environment. The resources have been pulled out of each foreign language
HHCTRL.OCX file and placed in separate dll files. There is only one
HHUPD.EXE for HTML Help 1.3. It installs the OCX, DLL and EXE files as
before, but now installs all available language DLL files as well. At run-time,
if a language DLL is not found, the the English resources stored within
HHCTRL.OCX are used.

Each language DLL is named HHCTRLUI.DLL, and is installed in a separate
folder. Each folder is named using the hex representation of that locale’s
Locale ID (LCID). For example the English locale’s folder is named 409, the
German locale’s folder is named 407, the Japanese locale’s folder 411, and so
on. On later versions of Windows, you will find the folders are simply
named 009, 007, and so on. Each locale folder lives in the MUI (Multilingual
User Interface) folder, which in turn lives in the Windows System folder.
Windows XP has one language DLL folder, unless you have the XP language
pack installed.

English Win98 Example: c:\windows\system\mui\409\hhctrlui.dll
English WinXP Example: c:\windows\system32\mui\009\hhctrlui.dll

Table 1. Locale Ids for 28 languages
Table 1 shows the 28 languages and their Locale IDs installed with HTML
Help 1.3. Remember that you can get the version and language information
of DLL by right-clicking the DLL and selecting properties.

LCID                        Language

0401                        Arabic

0403                        Catalan

0404                        Traditional Chinese

0405                        Czech

0406                        Danish

0407                        German

                            Copyright 2002, Help Think Press/Work Write, Inc. All rights reserved.
                                          Deploying HTML Help 1.x              Page 10

LCID                         Language

0408                         Greek

0409                         English

040A                         Spanish

040B                         Finnish

040C                         French

040D                         Hebrew

040E                         Hungarian

0410                         Italian

0411                         Japanese

0412                         Korean

0413                         Dutch

0414                         Norwegian

0415                         Polish

0416                         Portuguese (Brazilian)

0419                         Russian

041B                         Slovak

041D                         Swedish

041F                         Turkish

0424                         Slovenian

042D                         Basque

0804                         Simplified Chinese

0816                         Portuguese

Note: Because of the changes to the way language is handled, it’s important to distribute HH 1.3
or above, as HHUPD.EXE installs all 28 languages version in one hit. Also remember that HHUPD.EXE
no longer works for newer operating system such as Win ME/2000/XP. Only official service packs
will update HTML Help on these operating systems. Thus HHUPD.EXE is only useful for updating
Win9x and WinNT4.

                             Copyright 2002, Help Think Press/Work Write, Inc. All rights reserved.
                                          Deploying HTML Help 1.x             Page 11

Distributing Internet Explorer
You can distribute Internet Explorer in these ways:

    Customer downloads IE free from the MS web site

    Customer purchases IE from local computer shop

    Customer upgrades Windows operating system

    Developer distributes to customers on CDROM

The last option is what interests us in this document. Information about
licensing and distributing Internet Explorer can be found on the Microsoft
Internet Explorer Administration Kit (IEAK) site.

Microsoft offers a number of different types of license and distribution

    An internal distribution license for corporations that want to distribute
    within their organization

    An external distribution license for Internet Service Providers (ISPs)
    that want to distribute to external customers

    A distribution license for Independent Software Vendor (ISVs)

Note: The MS IEAK web site supports download and license agreement for Internet Explorer 4, 5,
5.5 and 6. I recommend you avoid IE4 as there were some problems associated with the silent
install (more on this later).

About the ISV component install
We’ll focus on the ISV license in this document, since it is holds the most
interest for help system development. The IEAK web says this about the
ISV license: “If your application uses the APIs documented in the Internet
Client SDK, and you want to redistribute with your application the compo-
nents that implement those interfaces, this is the license you need.”

The important aspects of the ISV installation are:

    No license fees or royalties

    No reporting requirements

    You are required to fill in the online profile and license form before you
    can download and distribute Internet Explorer.

                            Copyright 2002, Help Think Press/Work Write, Inc. All rights reserved.
                                   Deploying HTML Help 1.x             Page 12

   Must place a Microsoft copyright statement in your products about box

   This statement should state:

   “Includes Microsoft Internet Explorer technology under license. (c)
   1995-2001 Microsoft Corporation. All rights reserved”.

   Check the IEAK web site for full details on the copyright statement.

   Must install Internet Explorer in “silent” mode

The “silent” install requirement means that you must install without
displaying any Internet Explorer setup options at all. This does not mean
that you cannot display your own setup dialogs or add a progress indicator.
You should never try to upgrade the user secretly without the user ’s con-
sent or knowledge. Such an operating system upgrade would not go unno-
ticed anyway.

Internet Explorer is installed without the shell, icons, or links; and Netscape
file associations are preserved. Full information on distributing Internet
Explorer under the ISV license can be found on the IEAK ISV web site.

Examples of APIs in the Internet Client SDK include:

   WebBrowser Control

   Windows® Internet API (WinInet API)

   Windows Shell API

   Common Controls API

   NetMeeting™ API

   NetShow™ APIs

   APIs implemented by the Microsoft Chat control

   APIs implemented by the ActiveMovie™ control

   APIs implemented by the Tabular Data control

   APIs implemented by the Advanced Data Connector (ADO API)

   APIs implemented by the Microsoft Dynamic HTML multimedia

                       Copyright 2002, Help Think Press/Work Write, Inc. All rights reserved.
                                   Deploying HTML Help 1.x             Page 13

Help developers require the first item, but you will get the first four items
whether you want them or not. (By the way, this list is probably somewhat
changed with Internet Explorer 6.)

So, do only the DLLs get installed? Well, it may look that way, but in fact
the entire application is installed with each API. The complete browser will
be installed. If you require the NetShow API or the Windows Media Player
API, then you will get the entire NetShow or WMP application.

Nevertheless, because shortcuts and links are not installed, I would say that
the basic user may have difficulty finding the browser executable in the file
system after a silent installation (assuming the user was using Netscape and
did not already have a copy of Internet Explorer installed).

A few notes and some a little history
HTML Help 1.0 was released mid 1997 with IE4. Microsoft’s original idea of
an HTML Help installation program (called HHRUN) was replaced by an
Internet Explorer 4 minimum install to consolidate the distribution of
Internet Explorer. The install is free to distribute and users of the ISV
license are required to install silently.

Unfortunately the IE4 minimum install is not entirely silent. Three “arti-
facts” remain after the install. The user is faced with the Channel Bar, an
invitation to take the Guided Tour of Internet Explorer, and the Internet
Explorer icon created on the desktop. Microsoft promised that these issues
would be resolved in the next major release of the browser. The IE 5 and 6
installation programs are certainly much improved.

                       Copyright 2002, Help Think Press/Work Write, Inc. All rights reserved.
                                           Deploying HTML Help 1.x              Page 14

Installing Internet Explorer “silently”
We will focus on IE6, however the IE 5.x installation is much the same. IE
4.0, 5.0, and 5.5 installs are still available from the IEAK web site.

Note: Before getting down to the nitty-gritty, we would like to acknowledge fellow MVP Paul
O’Rear for all his research and hard work in this area. Paul has published an excellent document
on the minimal install on the web at:

Implementing the silent installation
Let’s look at the steps required to create an Internet Explorer silent installa-
tion package. If you are not a programmer or plan to use our free Windows
Update Installer, you can skim over much of this next section.

1. Register

You will need to go to the IEAK web site and register. Go to the “license
and registration” page. The license you are interested in is the one made for
ISVs and developers. When asked for the “Type of Company,” select Inde-
pendent Software Vendor (ISV). After accepting the license agreement, you
will be sent an IEAK customization code by email. You will need this code
if you decide to use the free IE Customization Wizard to download IE6.

2. Download IE6 installation files

Go to the IE6 download page (, and
follow the site instructions to download the IE installation files to your
local hard drive. Make sure you prepare plenty of disk space. (An IE mini-
mal installation typically consumes around 30 MB of disk space.) Note that
all files downloaded, according to the download instructions, must be
redistributed with your application. No files may be removed.

If you need to distribute international versions of IE6, you may have a
problem. For example, if you download Japanese IE6, you will find that all
the download instructions are also in Japanese. If English is your native
language, then make yourself familiar with the English instruction by
writing down all the download steps. Then, when it comes to downloading
the foreign language versions, you will be able to go through the steps even
though you cannot read the instructions.

There maybe another problem with using the standard IE download page.
It would appear that later versions of IE allow for installation only. You
may no longer have access to the “Advanced” button that formerly allowed
you to download a complete distributable installation.

                             Copyright 2002, Help Think Press/Work Write, Inc. All rights reserved.
                                     Deploying HTML Help 1.x               Page 15

A better alternative is to use the IEAK customization wizard to download
the IE distribution files. We will talk more about how to use the IEAK
Customization Wizard later.

3. Download the HTML Help installation files

The IE6 installation includes HTML Help 1.33 install files, but there is a
catch. If a version of HTML Help 1.0 or greater is found on the user’s
machine, IE install will not upgrade it. The IE online help itself only re-
quires HTML Help 1.0. This was the case with the IE5 install, and I suspect
that IE6 will be the same.

Thus to ensure that the latest version of HTML Help is installed on the
target PC, we need to also run the HTML Help Install program HHUPD.EXE
immediately after running IE5 install. This can be performed either before
or after you restart Windows. Please read the distribution license on the
HTML Web site.

4. Command line switches

Now that we have all the installation files, we need to run them with
special command line switches to achieve the required silent install. The IE5
install program is called IE5SETUP.EXE, and for IE6 it is called IE6SETUP.EXE.
This is a self-extracting zip file. By using WinZip or some other zip utility,
we can checkout its contents.

File                    Description

Ie5wzd.exe              The real installation program that performs the actual work of
                        unpacking CAB files and installing the IE5 components. This
                        called Ie6wzd.exe for IE6.

Ie.txt                  This file was with the IE5 install. I’m sure this information is also
                        available for IE6 via the web. It contained important installation
                        information such as:

                        “NT4 systems must have Service Pack 3 or greater installed.
                        Windows 98 Arabic and Hebrew require the corresponding
                        localized version of Internet Explorer 5. It is not possible to
                        install the English version of Internet Explorer over the localized
                        version of Windows 98. This restriction does not apply to
                        localized versions of Windows 95 or Windows NT 4.0.”

                        It’s worth reading this file.

Other files             There are a number of other setup support files contained in

                        Copyright 2002, Help Think Press/Work Write, Inc. All rights reserved.
                                       Deploying HTML Help 1.x              Page 16

Now that we have identified the two setup executables, here is the IE5 or
IE6 command line you will need.

     Ie5setup.exe <ie5setup switches> /c:” ie5wzd.exe <ie5wzd switches>”
     Ie6setup.exe <ie6setup switches> /c:” ie6wzd.exe <ie6wzd switches>”


 ie5set.exe /Q:A /C:”ie5wzd.exe /M:0 /S:””#e”” /Q /R:N /X”
 ie6set.exe /Q:A /C:”ie6wzd.exe /M:0 /S:””#e”” /Q /R:N /X”

Ie5setup.exe/ie6setup.exe switches explained

Switch                    Description

/Q:A                      Specifies quiet mode, which does not present any dialog boxes
                          to the user.

/C:<>                     Specifies the name of the setup exe file and its command-line
                          parameters all enclosed in a set of double quote characters.
                          Notice that if quotes are used within these quotes such as in the
                          case with the /S switch then we need to use two quotes together.
                          So /S:”#e” becomes /S:””#e””.

Ie5wzd.exe/ie6wzd.exe Switches explained

Switch                    Description

/M:0                      Specifies the minimal installation mode: 0=minimal, 1=typical,

/S:””#e””                 Specifies the source path of Ie5setup.exe. The “”#e”” is auto-
                          matically replaced by the full path during installation.

/Q                        Specifies quiet mode, which does not present any dialog boxes
                          to the user unless information is missing.

/R:N                      Specifies no reboot after installation. If you suppress restarting,
                          your program should take care of restarting the computer.
                          Internet Explorer is not configured correctly until the computer
                          is restarted.

/P                        An option switch which allows setup to run in a special mode.
                          Instead of IE5 being installed, setup will instead estimate how
                          much disk space is required and return the estimation in registry
                          values. Instructions on using this switch follow.

/X                        Installs Internet Explorer without the shell, icons, or links and
                          does not take over the default browser or http protocol associa-
                          tions. This switch must be included to conform to the ISV license

/X:1                      An alternative to using /X. Installs Internet Explorer with the
                          shell, icons, and links, but does not take over the default
                          browser or HTTP protocol associations.
                          Copyright 2002, Help Think Press/Work Write, Inc. All rights reserved.
                                     Deploying HTML Help 1.x             Page 17

Now if you ran IE5SETUP.EXE/IE6SETUP.EXE with the above switches from
the Windows Start > Run dialog on a Pentium 133MHz, you would see the
hard disk rattle for a few minutes and then stop. After restarting Windows
the hard disk would rattle for a a few more minutes, two Internet Explorer
messages would appear, and finally an Internet Connection Wizard icon is
placed on the desktop. Clearly we need to do some work here so that the
user is not left staring at a blank screen wondering if the installation has

5. Hiding IE artifacts

Through registry settings, you can suppress the three Internet Explorer

                                                                              Figure 2 Artifact 1. The
                                                                              Windows Update message seen
                                                                              as Windows is restarting.

To suppress this message set the following registry value just before you
restart Windows.


                                                                              Figure 3 Artifact 2. The
                                                                              Personalized Settings
                                                                              message seen just after
                                                                              Artifact 1.

To suppress this message, set the following registry value just before you
restart Windows.

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Active Setup\Installed
Components] ”NoIE4StubProcessing”=”Y”

                         Copyright 2002, Help Think Press/Work Write, Inc. All rights reserved.
                                    Deploying HTML Help 1.x             Page 18

Microsoft says that using this setting may have an adverse affect on setup
of the personalization aspects of IE. Unlike the first registry hack that
simply inhibits the display of a message, this setting inhibits the entire
action. Microsoft recommends that you only use this setting only if
Internet Explorer is not already installed.

                                                                         Figure 4 Artifact 3. The
                                                                         Connection Wizard icon is
                                                                         placed on the desktop after
                                                                         Windows startup has

To stop the Connection Wizard icon from being placed on the desktop,
delete the following registry entry just before you restart Windows.


6. Packaging the IE setup

Lastly, we need to package the silent install into some sort of installation
program. Since the Internet Explorer and HTML install files can total 30MB
or more, I suggest you place them in a folder on the installation CDROM.
Most install programs are capable of running external programs.

Let’s look at what the installer would need to do.

    Welcome screen describing what is about to happen.

    An NT check for NT4 Service Pack 3 or above.

    An NT check for administrator logon (NT users must be logged on with
    full administration privileges otherwise IE and HH will not install

    Message to warn the user if IE and HH are already installed.

    If several language versions of IE and HH are available then we need a
    way to select the correct language version.

    An installation progress meter would be nice.

    We need to set the registry items to remove the Internet Explorer

    We need a “Restart Windows” message at the end of installation.

It’s definitely a job for a programmer. However, most of the above have
been incorporated into our free “Windows Update Installer” program.
                        Copyright 2002, Help Think Press/Work Write, Inc. All rights reserved.
                                         Deploying HTML Help 1.x             Page 19

Advanced registry settings
In addition to the registry settings I’ve already described, some additional
settings associated with IE setup are also helpful. These settings are docu-
mented in IEAK online help. I used these settings in the Windows Update

Estimating required disk space
Adding a /P command line switch will cause an IE5 setup to calculate how
much disk space is required, instead of installing files. Disk space estima-
tions are returned in registry values.

ie5set.exe /Q:A /C:”ie5wzd.exe /M:0 /S:””#e”” /Q /R:N /X /P”
ie6set.exe /Q:A /C:”ie6wzd.exe /M:0 /S:””#e”” /Q /R:N /X /P”

When this program call returns, you can display the results to the user,
along with the available disk space on the Windows drive. If all is okay to
proceed, run IE5SETUP.EXE once more, this time without the /P switch.

Three registry values are filled in when the /P call returns. All values live
under the following key:

[HKEY_LOCAL_MACHINE\Software\Microsoft\Active Setup\InstallInfo]

Value                        Description

InstallSize                 String Value contains the real install size in KB. You may want to
                            display this to the user along with the available disk space on the
                            drive with the Windows directory.

EstimatedCopy               String Value contains the space required by the install process.
                            This figure can be used to create a progress Indicator.

Complete                    DWord value contains a result of zero meaning success. Non-zero
                            normally means that there is insufficient disk space to install
                            Internet Explorer. Check the IEAK program online help for more
                            information on return codes.

It would be wise to delete these registry values prior to running in /P mode.

Note: The IE5 IEAK online help we downloaded had a typographical error that omitted the space
character in “\Active Setup\”. This will not work. The space must be included.

                            Copyright 2002, Help Think Press/Work Write, Inc. All rights reserved.
                                   Deploying HTML Help 1.x            Page 20

Creating a progress indicator
Using the EstimatedCopy value returned by the /P call, you could create an
installation progress indicator.

Read the “original disk space free” on the Window drive at the start of
install. At the end of installation (before reboot), disk space free will be
approximately equal to “original disk space free“ minus “EstimatedCopy”.
All high-level programming languages allow you to read the disk space free
of a drive.

Add a timer event to your code, with, for example, interval equal to one
second. On every event, read the current disk space free value and update
your progress bar. Remember: CAB files are being copied to and deleted
from your hard disk. It will look a bit strange if the progress bar moves
backwards and forwards, so only show progress increases.

Tips for programmers
Here are some more tips and reminders for programmers.

   Don’t run with scissors. That should make MS Office people feel at
   home. ;-)

   When installing on NT machines, both the IE5SETUP.EXE/IE6SETUP.EXE
   and HHUPD.EXE installation programs require the current user to have
   full administrative privileges. Otherwise, the installation will fail.

   To check whether Internet Explorer is already installed, read the version
   information from SHDOCVW.DLL found in the Windows System direc-
   tory. For more information on reading Internet Explorer version infor-
   mation, see:

   Run the HTML Help installer HHUPD.EXE immediately after the
   IE5SETUP.EXE/IE6SETUP.EXE if you want your users to have the latest
   version of HTML Help. IE5SETUP.EXE/IE6SETUP.EXE only updates HTML
   Help 1.x if the components are not found on the machine.

   To run HHUPD.EXE in silent mode use the following command-line

       Hhupd.exe /r:n /q:a

                       Copyright 2002, Help Think Press/Work Write, Inc. All rights reserved.
                                Deploying HTML Help 1.x             Page 21

You could check whether HTML Help is already installed by reading the
version information from HHCTRL.OCX normally found in the Windows
System directory. However, since it is an ActiveX control, it may actu-
ally be installed in the Windows ActiveX cache. You can get the path to
the OCX from the registry; however the simplest solution may be to
always run HHUPD.EXE with no checking. It’s relatively small, quick to
install, and will not overwrite newer versions of HTML Help. For
protected versions of windows (Win ME/2K/XP), the HHUPD.EXE
installer will gracefully fail. If you use the /r:n /q:a silent switches you
won’t even see an error message on screen.

The HTML Help installer, HHUPD.EXE, can be downloaded for free from
the MS web site. Windows users require the x86 install version.

If you have non-English customers, do not install the English IE setup
on their machines. If you cannot provide the correct language installa-
tion, it might be wise to open a message asking them to purchase and
install Window98 SE, Windows 2000, or greater. HH 1.3x can be
installed on any language machine.

IE5SETUP.EXE/IE6SETUP.EXE provide two log files to help pinpoint instal-
lation problems. The log files appear in the Windows or NT folder.

Active Setup Log.txt contains a log of all activity prior to restarting the
PC. Refer to this log if Internet Explorer components are not installed

RunOnceEx Log.txt contains a log of all activities after restart such as DLL
registration. Refer to this log if you receive a message stating that a
specific DLL did not register properly, or if any unexpected dialog box
appears during the final phase of the setup process.

                    Copyright 2002, Help Think Press/Work Write, Inc. All rights reserved.
                                          Deploying HTML Help 1.x              Page 22

Installing your help system (.chm) files
Generally speaking, the installation of your help system (CHM and any
support files) is very straightforward. Simply copy it to the desired loca-
tion. However there are a few traps for beginners we should mention.

Current directory bug
Often we need a topic in a help (CHM) file to access other help files or
support files. These other files are usually stored in or around the help
folder (the folder containing your CHM files).

Examples of accessing external files:

    Use a HH Shortcut command to open or execute an external file
    (e.g., PDF)

    Find other CHM files (part of a merged help system or document set)

    Open a WinHelp (HLP) file

    Access large media files stored externally

You get the idea. A problem arises however when the “current directory” is
changed by the host program and external files can no longer be located
because they are no longer in the Windows search path.

Most HTML Help commands rely heavily on the use of relative paths, so it
is vital that we either maintain the current directory, or we place the help
files into the search path where they can be found. If you don’t take these
precautions then at some stage your users are going to get that annoying
“file not found” message.

What often happens is we do all our testing by opening the main CHM help
file from Windows Explorer? In this situation, the current directory cannot
change and no problems are observed. Eventually real users, who open help
through the software application, start reporting that they are getting file
not found errors, and you are left scratching your head because you know
you tested it fully. What has happened is this: As soon as the user access the
file system via the standard Open or Save dialogs, the current directory is
changed. The main help file opens correctly; however, it cannot find the
other files.

Note: I suspect that this is the major reason why MS Help 2 has now adopted the use of registering
all help components under a “namespace” so that component files can always be located.

                             Copyright 2002, Help Think Press/Work Write, Inc. All rights reserved.
                                     Deploying HTML Help 1.x            Page 23

For developers: calling help from applications

If your application calls help by hosting the HTML Help HHCTRL.OCX API
library, you must correctly maintain the current directory. If you open help
via another program such as HH.EXE or KEYHH.EXE you won’t have any
problems, since, as separate programs, they have their own environment
and current directory.

In Delphi, we have the option of identifying whether a standard Open/Save
dialog can change the current directory. For other programming languages,
you may need to get the current directory before every File Open or File Save,
and then restore it later. Another method that we use is to simply set the
Current Directory = Help File Folder just prior to making a call to the Help API.
This is simple if all help calls are made through a central point. After
launching help, if you want to set the current directory back to what it was
before you changed it, that’s okay. It will not affect the help window that is
now open.

Getting files into the help search path

Another fix is to simply get the files into the Windows search path. When
ever Windows searches for a file, it looks in these locations:

    The current directory
    (Each EXE has a current directory. This is initially the folder where the
    EXE resides.)

    The Windows System folder
    (e.g., c:\winnt\system32 or c:\windows\system)

    Windows folder
    (e.g., c:\winnt or c:\windows)

    Any folder as specified in the Path= environment variable.

For the HH Shortcut command (used to open or run external files), placing
the target file into the search path (as specified above) works well.

For HH merged file systems, we need to place our secondary CHM files into
the current directory (with the master CHM), or we need to register the
help files with Windows.

                         Copyright 2002, Help Think Press/Work Write, Inc. All rights reserved.
                                     Deploying HTML Help 1.x            Page 24

Registering help files

Just as we can register an HLP help file’s location in WinHelp, we can also do
the same in HTML Help. Registering the location of a help file ensures
Windows can find it when required.

In WinHelp we set the following registry key:

Key = myfile.hlp
KeyData = “c:\hlpfolder\”

In HTML Help we set the following registry key:

[HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\HTML Help]
Key = myfile.chm
KeyData = “c:\chmfolder\”

WinHelp.INI and HH.INI file format

You do not need to reboot a Windows machine for the registry to work. You
can also register CHM files via HH.INI (create this file in the windows folder if
one isn’t already on the machine). The primary advantage of the HH.INI file,
is that you can add a prompt to tell the user something should the file not
be found. That’s particularly useful if the CHM file is on a CD-ROM and you
need to tell the user to insert a specific CD-ROM disk.

The format of HH.INI is identical to the WINHELP.INI file.

Help-filename=path, optional message


The following HH.INI entry instructs Help to look in the \Product\Files folder
on drive P for the Notepad help file. If necessary, Help will prompt the user
to insert a CD into the drive:

Notepad.chm=P:\Product\Files, Please insert your Windows 98 CD
into drive P.

                         Copyright 2002, Help Think Press/Work Write, Inc. All rights reserved.
                                  Deploying HTML Help 1.x            Page 25

Summing Up

   Simple help systems with a single help file are no problem.

   If you are using the HTML Help Shortcut command, make sure the
   target file is in the Windows search path.

   If you are using the HTML Help WinHelp Topic command, make sure
   the HLP target file is in the Windows search path or you have registered
   the help file.

   For multi-CHM document sets, install each CHM file to the same folder
   and make sure the current directory does not change. Alternatively, you
   can register each CHM file so it can be found by the master CHM when

                      Copyright 2002, Help Think Press/Work Write, Inc. All rights reserved.
                                    Deploying HTML Help 1.x            Page 26

About the Windows Update Installer
We have provided a free Internet Explorer silent installation program to
accompany this document. It implements all the things we talked about in
the last chapter. We call it the Windows Update Installer as it sounds less
threatening than Internet Explorer Silent Installer.

The main window displays a graphic, a language select dropdown and three
buttons: Install, Close, and Help. All text and images are fully customizable via
an accompanying INI file. The installer may also be run from your own
install program in quiet mode where the main window is made invisible. It
has been translated into several languages. The program detects and dis-
plays the correct language resources defaulting to English if a language
cannot be found. If you translate into other languages please email us so
that others can benefit from your translation work.

                                                                             Figure 5 The main window
                                                                             for the Windows Update
                                                                             Installer contains a graphic,
                                                                             a drop-down for selecting
                                                                             the language , and several

Source Code
The Windows Update Installer is written in Delphi. The source code is
provided on my the HelpWare website:

                        Copyright 2002, Help Think Press/Work Write, Inc. All rights reserved.
                                   Deploying HTML Help 1.x            Page 27

Typically we advise shipping the Windows Update Installer, IE distribution
files, and HHUPD.EXE on a separate CD-ROM from the main application’s
installation files. If the main install program detects that IE needs to be
installed, it displays a message such as: “An upgrade is required to display
Microsoft HTML Help files. Please exit the installation now and insert the
CD labeled Windows Update. Alternatively, you can upgrade to Windows
98 SE or Windows 2000 or greater.” The advantage of using multiple CDs is
that updates are easier and safer, and you can fit more international ver-
sions of IE onto the CD-ROM.

Most people, however, will probably want to fit everything onto a single
CD-ROM, and call the Windows Update Installer directly from the main
installation program. To run the Windows Update program in quiet mode,
use the “/q” command line switch.

In quiet mode, the installer’s main window is not visible unless none of the
IE language installations available match the operating system language. In
this case, the installer will be run in visible standalone mode, and a
progress bar and install message are displayed. If the operating system is
already up-to-date, the installer simply returns.

You can read more about the /q switch in the readme.txt file distributed
with the Windows Update program and source code.

You don’t need to be a programmer to do basic customizations to the
Windows Update Installer. You can set the user interface language strings,
front-page graphic, help file, and some other settings via an INI file called
setup.dat. Open this file in Notepad to see what it contains.

Setup.dat also contains a list of all available localized versions of the IE
setup. When the Windows Update Installer starts, it checks to see which IE
languages are available on the CD and only those found are displayed in the
language select drop-down list. The Windows Update Installer will auto-
select the correct language for you. If the list is empty, it means you have
entered path information incorrectly in setup.dat.

You can read more about setup.dat settings in the readme.txt file distributed
on the CD-ROM with the Windows Update program source code.

                       Copyright 2002, Help Think Press/Work Write, Inc. All rights reserved.
                                          Deploying HTML Help 1.x               Page 28

You can enable debug mode in a number of ways.

    Start setup.exe with a /debug command-line switch.

    Create an empty file called debug.debug in the same folder as setup.exe.

While in debug mode, right-click the main window. The popup menu now
contains an item called Show Debug. This item displays information about
which languages were found or not found, and so forth. The other popup
menu items display the two MS IE5SETUP/IE6SETUP log files.

The setup program has been localized into several popular languages. All UI
strings are read from the setup.dat configuration file on program startup. On
Japanese Windows, the Japanese strings will be read, on German Windows
the German strings will be read, and so on. Extra translations can be added
by editing the setup.dat file. The right-click popup menu contains a list of all
available localizations. Select a language and watch the UI strings change.

Note: By adding dbg_forceSpecialDebug=y to the Setup.dat file you can make the Install button
display all display strings in message boxes one after the other, instead of performing the normal
installation action. This is a handy debugging aid for localization.

Using IEAK to download IE
The IEAK customization wizard allows you to download the IE installation
files. You can view download instructions in a single language, while down-
loading several language versions of IE.

To download IEAK, click the “Downloads” hyperlink left of the IEAK web

The IEAK customization wizard requires an enabling key. To get this, you
will need to register for an external license (described earlier). Once you do
this, the enabling key will be sent to you via email.

Running the IEAK customization wizard
You will need to run the Wizard once for each language download. You must
be connected to the Internet before you can download any IE setup files. If
the instructions below sometimes do not match up exactly with what you
see, simply click Next to accept the default setting.

                             Copyright 2002, Help Think Press/Work Write, Inc. All rights reserved.
                                    Deploying HTML Help 1.x            Page 29

Once you have downloaded and installed IEAK, select IEAK Customization
Wizard from the Microsoft IEAK menu in Start > Programs. Click Next to
precede though the IEAK Customization Wizard pages. Click Back to return
to a previous page.

Company Name & Customization Code (IE5 only)

The first time you run the IE5 IEAK program you need to enter your com-
pany name and customization code. The name is the same one you used
when you signed up. The code is the one emailed to you when you accepted
the online license. For IEAK6, the customization code is only required at
download time. Click Next.

Platform Options (IE5 only)

Select Windows 9x/NT 4.0 if not already selected. Click Next.

File Locations

Spend a minute getting this section right.

Click the Advanced button to enter the folder where you want the download
files to go. The AVS checkbox should be checked. Close the Advanced Op-
tions dialog and enter a destination folder. Files are downloaded to the
download folder and then copied to the destination folder in the final stage.
Keeping two copies of IE install files (around 30MB per install) in each
language will take up some disk space, so make sure you have lots of free
disk space. IEAK will automatically create language folders for you by
taking your download and destination folders and adding \EN for English,
\DE for German, and so on. Click Next.

Language Selection

The current list of available languages is downloaded and displayed in the
dropdown list. Select which language to download. Click Next.

Media Selection

Select the Flat check box only. This is for distribution via a network or CD-
ROM. Click Next.

Feature Selection

Uncheck all items except Setup Customizations. Note that the Setup
Customizations check box is not present with all languages. Also note that the
Policies and Restrictions page will sometimes appear even if you do not select it
here. Click Next and then Next again.

                        Copyright 2002, Help Think Press/Work Write, Inc. All rights reserved.
                                           Deploying HTML Help 1.x               Page 30

Download Sites

Pick a download site near you. This page may not be available. Click Next.

Automatic Version Synchronization (AVS)

IEAK will now download a list of component filename and version informa-
tion from the web. It will take a few minutes to download and to check and
validate any files previously downloaded.

Once the list appears, select the components you want to distribute. Items
you downloaded previously will be marked in green if they are up-to-date.
Items that are partially downloaded or out of date will be marked in yellow.
All other items will be marked in red. (The IE6 IEAK may have some other
symbols.) Click the Synchronize button to start downloading selected the
items. Download only the components you want to distribute.

                                                                                                       Figure 6 IEAK5 AVS

Tip: Make a careful record of which components you select and download.: for example,
1,2,3,4,7,8 and so forth. When it comes to downloading other language versions, the component
list will be displayed in that language. Luckily the component list is always in the same order for
all language downloads.

The components we downloaded for our Install disk are listed in the next
section. Click Next until you reach the Installation Options page.

Installation Options

Select the Minimal option and click the > > button to move all components
over to the right side. Click Next.

Advanced Installation Options

Click Unselect All. Click Next and then Next again.

                              Copyright 2002, Help Think Press/Work Write, Inc. All rights reserved.
                                           Deploying HTML Help 1.x               Page 31

The IEAK wizard will now copy all the files needed for distribution from
the download folder to the destination folder you entered earlier on.

That’s it. Press Finish to close the program. Remember: you will need to run
the wizard again to download another languages or extra components. The
program will remember most of the settings you entered the last time you
ran it.

Tip: When new versions of Internet Explorer become available you will need to be patient. English
is the first download available, then it takes several weeks for all languages to become available.

Which IE components should I download?
The ISV license allows developers to download and distribute whatever
components are required. Each developer will require a different component
mix. In the list below, components marked with a check are those we
included with our own installation CD-ROM. These would suit the needs of
most HTML Help authors.

Windows Media Player and Macromedia components were included because
many authors are including multimedia contents in their help systems. In
IE5 IEAK, there was some confusion over the Macromedia component
names. The Shockwave item appears to be the Director ActiveX control,
while the Macromedia Flash Player appears to be the Shockwave Flash
ActiveX control. IE6 IEAK appears to have combined the Macromedia items
into a single selection.

These items are from IEAK5. The IEAK6 items are very similar.

          Internet Explorer 5 Web Browser
          Internet Explorer Help

          Internet Explorer Core Fonts

          Dynamic HTML Data Binding

          IE5 Browser Enhancements


          Outlook Express

          Chat 2.1

          Windows Media Player

          Windows Media Player Codec

                              Copyright 2002, Help Think Press/Work Write, Inc. All rights reserved.
                           Deploying HTML Help 1.x            Page 32


Direct Animation

Vector Graphics Rendering


Macromedia Shockwave

Macromedia Flash Player

FrontPage express

Web Publishing Wizard

Web Folders

Visual Basic Scripting Support

Additional Web Fonts


Language Display Support

               Copyright 2002, Help Think Press/Work Write, Inc. All rights reserved.
                                      Deploying HTML Help 1.x            Page 33

About the author, Robert Chandler
Robert Chander works full-time for Varian Australia, makers of optical spectroscopy
instruments. After a decade in software development, Robert moved into Varian’s
Marcom department to work with help systems, Web, multimedia, and video. Robert
spoke at the 4th Annual Australasian Online Documentation conference (April 2001) on
behalf of MicroSoft, where he introduced Microsoft Help 2.0. Robert is a Microsoft Help
MVP (Most Valued Professional), which explains his association with the Microsoft help
development team. Robert’s HTML Help shareware program, FAR, is considered a “must
have” utility if you are authoring HTML Help or Help 2 without a commercial help
authoring tool.

About the publisher, Help Think Press
This document was developed under contract to Help Think Press, a division of Work
Write, Inc. Help Think Press provides publications of interest to user assistance and
performance support specialists. Work Write, Inc. is a consulting firm that specializes in
the design and development of user assistance and performance support for the
Windows and Web platforms. Work Write, Inc. president Cheryl Lockett Zubak is a
charter member of the HTML Help MVP program, and teaches courses for help authors on
RoboHELP HTML, Dreamweaver, Homesite, and help design/architecture. With her
partner, Ralph Walden, Cheryl is also developing tools and strategies for enhancing the
capabilities of Microsoft HTML Help, particularly for developing embedded help systems
and performance upport (EPSS).

                    Help Think Press                      Phone: +1 215.357.3453
                    A Division of Work Write, Inc.        Fax: +1 215.357.0695
                    128 South Eastview Avenue             Web:
                    Feasterville, PA 19053 USA              helpthink/welcome.htm

                          Copyright 2002, Help Think Press/Work Write, Inc. All rights reserved.

To top