Deploying HTML help 1.x

Deploying HTML Help 1.x Page 1 A Help Think Press Publication Deploying HTML Help 1.x by Robert Chandler The Helpware Group http://www.helpware.net Help Think Press A Division of Work Write, Inc. 128 South Eastview Avenue Feasterville, PA 19053 USA Tel: +1 215.357.3453 Web: http://www.workwrite.com/ helpthink/welcome.htm Email: helpthink@workwrite.com 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 herein. Trademarks 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 cheri@workwrite.com; website http://www.workwrite.com. 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 ........................................................................................ Shipping ............................................................................................ Customizing ....................................................................................... Debugging ......................................................................................... Localizing........................................................................................... 26 27 27 28 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 Deploying HTML Help 1.x by Robert Chandler The Helpware Group http://www.helpware.net I n this document, I will cover issues related to installing Microsoft HTML Help 1.x1 —in particular, implementing the Internet Explorer silent installation. 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 This document and accompanying sample files were developed under contract to: Help Think Press A Division of Work Write, Inc. http://www.workwrite.com/ helpthink/welcome.htm Copyright © 2002, Help Think Press/Work Write, Inc. All rights reserved. 1 Installing the HTML Help runtime files through HHUPD.EXE Distributing Internet Explorer Implementing the Internet Explorer silent installation You may have heard of Microsoft Help 2.0 as the forthcoming help standard from Microsoft. The public release of 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: http://helpware.net/downloads/ HTML Help 1.x installation program is a free download from: http://msdn.microsoft.com/library/en-us/htmlhelp/html/vsconHH1Start.asp Internet Explorer is a free download from: http://www.microsoft.com/windows/ie/ Details about the Internet Explorer ISV license can be found at: https://ieak.microsoft.com/en/license/isvlicense.asp For documentation on reusing the WebBrowser control, go to: http://msdn.microsoft.com/workshop/browser/webbrowser/webbrowser.asp 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 WinHelp. 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 installation. This installation package allows you to install IE as a system component 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 run.2 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 configuration. 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. 2 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 Operating System Windows NT4 Windows 95 Original Windows 95 OSR2 Windows 98 Original Windows 98 SE Windows 2000 3 Windows 2000 SP1 3 Windows 2000 SP2 3 Windows ME 3 Windows XP 3 Internet Explorer Version 2.0 Not installed 3.01 4.01 5.0 5.0 5.0 5.0 5.5 6.0 HTML Help Version Not installed Not installed Not installed 1.1a 1.21 1.30 1.31 1.31 1.32 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. 3 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: http://msdn.microsoft.com/library/en-us/htmlhelp/html/vsconHH1Start.asp HTML Help 1.x requires Internet Explorer 3.0 or greater. If Internet Explorer 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 installation. 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 Hhctrl.ocx Itss.dll Description Provides access to all main HH functions and services. 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. Controls the full-text search engine. Windows uses hh.exe to open CHM files. During installation, a file association is created between .chm files and hh.exe. Installed with HH 1.3 and above. 28 language DLLs are installed under the “mui” folder in the windows system folder. Itircl.dll Hh.exe4 hhctrlui.dll 4 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. (http://www.keyworks.net). 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 0401 0403 0404 0405 0406 0407 Language Arabic Catalan Traditional Chinese Czech Danish German Copyright 2002, Help Think Press/Work Write, Inc. All rights reserved. Deploying HTML Help 1.x Page 10 LCID 0408 0409 040A 040B 040C 040D 040E 0410 0411 0412 0413 0414 0415 0416 0419 041B 041D 041F 0424 042D 0804 0816 Language Greek English Spanish Finnish French Hebrew Hungarian Italian Japanese Korean Dutch Norwegian Polish Portuguese (Brazilian) Russian Slovak Swedish Turkish Slovenian Basque Simplified Chinese 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. http://www.microsoft.com/windows/ieak/en/default.asp Microsoft offers a number of different types of license and distribution agreements. 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 components 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 consent or knowledge. Such an operating system upgrade would not go unnoticed 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 controls 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 “artifacts” 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: http://www.helpfulsolutions.com/Silent_IE5_Install.htm Implementing the silent installation Let’s look at the steps required to create an Internet Explorer silent installation 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 Independent 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 (http://www.microsoft.com/windows/ie/), 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 minimal 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 requires 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 Ie5wzd.exe Description The real installation program that performs the actual work of unpacking CAB files and installing the IE5 components. This called Ie6wzd.exe for IE6. 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. Ie.txt Other files There are a number of other setup support files contained in ie5setup.exe. 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 /c:” ie5wzd.exe ” Ie6setup.exe /c:” ie6wzd.exe ” Examples: 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 /Q:A Description Specifies quiet mode, which does not present any dialog boxes to the user. 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””. /C:<> Ie5wzd.exe/ie6wzd.exe Switches explained Switch /M:0 Description Specifies the minimal installation mode: 0=minimal, 1=typical, 2=full. Specifies the source path of Ie5setup.exe. The “”#e”” is automatically replaced by the full path during installation. Specifies quiet mode, which does not present any dialog boxes to the user unless information is missing. 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. 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. Installs Internet Explorer without the shell, icons, or links and does not take over the default browser or http protocol associations. This switch must be included to conform to the ISV license agreement. 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. /S:””#e”” /Q /R:N /P /X /X:1 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 completed. 5. Hiding IE artifacts Through registry settings, you can suppress the three Internet Explorer artifacts. 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. [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\RunOnceEx] ”Flags”=dword:00000ab8 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 completed. To stop the Connection Wizard icon from being placed on the desktop, delete the following registry entry just before you restart Windows. [HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows\CurrentVersion\RunOnce] ”^SetupICWDesktop” 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 correctly). 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 artifacts. 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 documented in IEAK online help. I used these settings in the Windows Update Installer. 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 estimations 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 InstallSize Description 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. String Value contains the space required by the install process. This figure can be used to create a progress Indicator. 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. EstimatedCopy Complete 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 directory. For more information on reading Internet Explorer version information, see: http://support.microsoft.com/support/kb/articles/q164/5/39.asp 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 switches: 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 actually 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 installation, 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 installation 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 properly. 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 location. 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: [HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\Help] 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. [FILES] Help-filename=path, optional message Example 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: [FILES] 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 required. 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 displays 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 buttons. Source Code The Windows Update Installer is written in Delphi. The source code is provided on my the HelpWare website: http://helpware.net/downloads/ Copyright 2002, Help Think Press/Work Write, Inc. All rights reserved. Deploying HTML Help 1.x Page 27 Shipping 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 versions 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. Customizing 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 autoselect 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 Debugging 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. Localizing 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 downloading several language versions of IE. To download IEAK, click the “Downloads” hyperlink left of the IEAK web page: http://www.microsoft.com/windows/ieak/en/download/default.asp 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 company 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 Options 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 CDROM. 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 Download Sites Page 30 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 information 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 page 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 NetMeeting 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 VRML Direct Animation Vector Graphics Rendering AOL Art Macromedia Shockwave Macromedia Flash Player FrontPage express Web Publishing Wizard Web Folders Visual Basic Scripting Support Additional Web Fonts Wallet Language Display Support Page 32 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 A Division of Work Write, Inc. 128 South Eastview Avenue Feasterville, PA 19053 USA Phone: +1 215.357.3453 Fax: +1 215.357.0695 Web: http://www.workwrite.com/ helpthink/welcome.htm Email: helpthink@workwrite.com Copyright 2002, Help Think Press/Work Write, Inc. All rights reserved.