MS HTML Help‎ > ‎


See also: A series of Security Updates have stopped many HTML Help features from working on the local PC and on servers.


  1. 1 HTML Help Compilation
    1. 1.1 What's required to Compile HTML Help
    2. 1.2 HH compiler error codes
    3. 1.3 "HHC6003: The file itircl.dll has not been registered correctly"
    4. 1.4 Compilation fails abruptly -- FAR reports "MS Compiler hha.dll has crashed during compilation"
    5. 1.5 HHW crashes when editing TOC
    6. 1.6 Incorrect Project Setup --> Missing content
    7. 1.7 Bad Authoring programs install HHA.DLL -> Compiler Crash
    8. 1.8 "Warning: Too many topics associated to the "xxx" keyword.  Remaining 999 links truncated"
    9. 1.9 Cannot write to file "c:\path\file.hhp"
  2. 2 HTML Help Viewing
    1. 2.1 What's required to View HTML Help
    2. 2.2 HTML Help Versions
    3. 2.3 When I click the Index tab Help crashes
    4. 2.4 Why does my CHM window show the title "HTML Help " instead of my title?
    5. 2.5 Why do my Icons, Images and document style fail to show?
    6. 2.6 Why do I see the filename containing %20 in the Favorites page instead of the topic Title?
    7. 2.7 Why wont my CHM open?
    8. 2.8 Images don't show in the CHM
    9. 2.9 Removing "Jump to URL" menu items
    10. 2.10 Why do my TOC labels change at Run-time?
    11. 2.11 Why do I get a HH_GET_WIN_TYPE Run-time Error?
    12. 2.12 How do I reset the help window size and position?
    13. 2.13 What is a .CHW file?
    14. 2.14 CHM crashes
  3. 3 Toolbar Buttons
  4. 4 General Information 
    1. 4.1 HH File Formats
    2. 4.2 Navigation Pane Page Tabs
    3. 4.3 HH.EXE Params 
  5. 5 Known HTML Help Bugs
    1. 5.1 Security Updates Break HTML Help
    2. 5.2 Relative Path Bug
    3. 5.3 Search Results & Binary TOC 
    4. 5.4 W2K SP4 - Links Fail
    5. 5.5 Embedding Causes Popups
    6. 5.6 The Same CHM Opens Bug
    7. 5.7 Multi-page Print Bugs
  6. 6 Microsoft Hot Fixes 

This page contains information on Microsoft HTML Help and HH Workshop (SDK).

HTML Help Compilation

  • What's required to Compile HTML Help

    The HTML Help compiler is part of MS HTML Help Workshop (HHW.exe). This is a free, very basic authoring system provided by MS and must be installed before any other authoring tool (such as  FAR HTML) can compile to a .chm help file.

    HTML Help Workshop (HHW) installer is called HtmlHelp.EXE and contains a copy of the HTML Help Run-time installer (HHUpd.EXE). These can both be downloaded from 

    Note: Later versions of Windows has HH Run-time already pre-installed (in fact it is now part of the OS). 

  • HH compiler error codes

    KeyWorks provide free reference information on all HH 1.x compiler error messages. 
    We ship KeyWorks Reference CHM with our FAR HTML product (with permission).

  • "HHC6003: The file itircl.dll has not been registered correctly"

    This error effects only a small number of users.
    A HH component (itcc.dll - lives in c:\windows or program files) did not get installed or registered correctly.
    First thing to try is uninstall and reinstall HH Workshop (HtmlHelp.exe installer is available from the MS site).

    If still not installed get the DLL from another PC containing Workshop. To register the DLL run regsvr32 itcc.dll.

    This fix was originally reported by MVP David Liske:

  • Compilation fails abruptly -- FAR reports "MS Compiler hha.dll has crashed during compilation"

    The MS HTML Help compiler is a DLL (HHA.DLL) installed with HH Workshop. Thus when it crashes it will also cause its host application (FAR, Workshop, etc) to crash also. 

    There are a number of reasons why the MS HH compiler may crash.

    1. Invalid filenames

    The HTML Help compiler does not like some filenames. Try and stick with these characters _, a..z, A..Z, 0..9. 

    Do not use periods apart from in the normal file extension. Example: A filename such as xxx.h001.gif is identified incorrectly as a HTML file. The compiler then attempts to parse the binary file and crashes.

    I believe that spaces in a filename can still cause some minor problems with HTML Help. Best to replace spaces with underscores.

    2. Invalid Tags or Characters

    Certain sequences of HTML tags and characters can crash the compiler. 

    • A web file may have become corrupted.
    • A FrontPage _vti file may have been included in your compile. 
    • A stray control character may have been left in a HTML file.
    • Your HTML editor may have produced code not understood by the parser in the MS compiler.
    3. Insufficient Memory

    If the help web is big (>10MB) then try recompiling on a more powerful PC (eg. Win2K, 256M RAM, lots of harddisk space on the system drive). If it  successfully compiles then you know that free memory is the problem.

    4. File Paths Too Long

    From Richard Sloggett (Innovasys): The Microsoft HTML Help 1.x compiler has known problems with the long filenames generated by Document! X .NET documentation. This problem can often (but not always) be worked around by compiling to a root path (e.g. c:\docs). If you need to create CHM format .NET documentation, you can use the 'Generate shortened alias filenames' option on the 'Microsoft .NET Options' page in the Document! X project editor in order to have Document! X shorten the generated filenames. This option does extend the documentation build time though.

    Rob: So try not to use long file and folder names. Move the project closer to the drive root to reduce the path length. And if you use the Innovasys tool to author, try Richards suggestion above.


    You need to debug your help system. You need to identify the file(s) that are crashing the compiler.

    I normally remove sections of my help web by renaming or moving folders and files, then recompile. Keep adding and removing sections until the compiler does not crash. Eventually you will find one or two files that are causing the problem. You may also need to debug these files by temporarily removing sections of the HTML file.

    Note:  A good starting point is to watch the compile log file being displayed and try to see where the crash appears. Tip: You may need to press PrintScrn  (captures the screen to the Windows clipboard) just before the crash to be able to read the list. The compiler normally follows the list of files in the .hhp project file then searches for addition files by examining the .hhc and .hhk files.


  • HHW crashes when editing TOC

    HHA.DLL (4.74.8702.0) is the current compiler engine in Workshop. If workshop crashes when compiling Japanese help projects, or when editing TOCs then you should get the HHA.DLL (4.74.9301.0) fix from MS Support (contact your nearest Microsoft Office). Note that one user reported the problem seemed to just suddenly appeared overnight. When contacting MS Support please quote the following KB numbers.

    KB294990  (HTML Help Workshop May Cause an Access Violation When Editing Contents File with .hhc Extension)
    KB304412  (FIX: HTML Help Compiler May Not Compile Correctly on Japanese Windows)
  • Incorrect Project Setup --> Missing content

    A trap for beginners. Make sure you get your project directory structure correct. 

    All project content (.htm, .jpg, .gif ...) must be located "in" or "below" the project folder (the folder containing your .hhp project file).  Files items specified in the [FILES] section of your .hhp project file should have a relative path and must _not_ begin with "..\". Similarly your HTML files must _not_ link to content above the project directory (since the compiler will try and auto-include this content). If you break this rule these outsider files will be compiled into the root of .CHM file breaking various file links.
  • Bad Authoring programs install HHA.DLL -> Compiler Crash

    There are a few ISVs that install HHA.DLL and itcc.dll separately instead of installing the full MS HH Workshop (htmlhelp.exe). This is generally an OK practice if the ISV knows what they are doing. I've seen problems however where itcc.dll is installed to the non-default location (c:\program files\HTML Help Workshop). Later when Workshop is installed or updated the registry info points to the wrong DLL and DLL mismatch causes problems. Same with HHA.DLL -- this does not require registration so ISVs can install HHA.DLL to the Authoring tools local run dir. If however Workshop is installed the Authoring Tool must take care to run the correct (latest) HHA.DLL. Looks like the Innovasys guys do the right thing. They install HHA.DLL (using version checking) to the Windows System32 folder (the default location used by workshop), and itcc.dll to c:\program files\HTML Help Workshop -- again the default location used by workshop. ISVs please keep in mind the safest approch (if you can afford the file space) is probably to install the full Workshop.

    If you are seeing constant crashes try the following -- Uninstall Workshop if installed. Find all occurrences of HHA.DLL & itcc.dll on your hard drive and Registry and delete them. Reinstall Workshop,

    Search Tab crashes (freezes) help

    This is the same problem as above. Some help authoring tool try to install parts of the HH Runtime or the HH Workshop (compiler).
    If a .chm is compiled using an old DLL then run on a modern windows machine, you can see lockups occur when you go to the search tab.
    The problem occurs because some DLLs are ActiveX (COM) and need to be registered. But only one DLL can normally be registered on a PC so the new rogue DLL overrides the existing DLL. So all other authoring programs are effected..

    The best advice is to remove these rogue DLLs (and get a reliable authoring app). Apps should always install the full HH Workshop/SDK (not partial installs).

    Use our utility MJ's Utilities to help find the rogue DLLs.

  • "Warning: Too many topics associated to the "xxx" keyword.  Remaining 999 links truncated"

    This compiler error occurs if you embed the same keyword too many times throughout your HTML docs. The limit is probably around 256.
    Typically seen if all your documents use the same <title>xxx</title>. This is because the compiler creates K and A keywords using each HTML document's title text. Say you wanted to create a .CHM file using say all your daily log files (and they all had the same title) then you would see this error. I don't think the error causes any problems. We suggest you use FAR to rename the titles to $F.$ (filename no ext). This could be automated if necessary using FAR batch mode.


  • Cannot write to file "c:\path\file.hhp"

    Under Vista you may see this message when you try and save a HH Project. I find if I close the project and open it again using the Workshop File Open command its OK. Seems to be only when I open a HHP in workshop using another program such as Windows Explorer.

    One user reported that switching On Compatibility Mode (see file properties for HHW.exe) also gets rid of the problem. It also resets the file association, so you will need to set that up again.


HTML Help Viewing

  • What's required to View HTML Help

    HTML help run-time is now part of the operating system. For older systems (Windows NT4 and Windows 9x) you should download and install HHUPD.exe (HH run-time installer). Actually installation of the HH run-time has changed over the years. For the most up to date information please go to the Microsoft HTML Help 1.4 SDK web page and click the HTML Help Downloads link.

    Internet Explore Dependency

    Internet Explore is required by the HTML Help run-time to display HTML content. You must have IE4 or greater installed to view .CHM help files. Actually help for IE4 is in HTML Help format so installing IE4 or greater will install the HH run-time for you. IE3 works to some extent but is not recommended.

    When installing to Windows NT4 you must be logged on with full Administrator privileges. You should also have NT service pack 3 or greater installed. Watch out, some NT4 installations come with IE2 but the IE aboutbox says 4.x.x an internal version number -- This is not IE4 and CHMs wont open correctly.

    Windows 2000 already has HH 1.3 installed. Infact HH Run-time is now part of the OS for Win2K, WinME, WinXP, Win2003 etc and since all system files are now "locked down", this means you can run hhupd.exe but it won't update anything. For these systems only an official MS Service Pack can be used to update the existing version of HTML Help. Thus HHUpd.exe is really only for Win NT4 and Win 9x.

  • HTML Help Versions

    You should have a minimum of version 1.2 (4.73.8252) installed. Earlier versions are too unstable. Later versions contain bug fixes and are more stable. Again note that Windows 2K and ME and later can only be updated using an official MS Service Pack. has a page that details all HTML Help releases 

  • When I click the Index tab Help crashes

    This problem is generally caused by the "stoplist" feature (A small text file containing words that should be ignored by the full text search engine). Lists greater than 512 bytes (characters) will hit a bug in the compiler that then fails to create the keyword index.  They work fine if you stay under that limit. The problem no longer seems to show under Win XP.
  • Why does my CHM window show the title "HTML Help " instead of my title?

    HTML Help is not a Unicode application, and there is a risk of showing garbage characters if the primary language ID of the CHM does not match the primary language ID of the systems LCID (for example a KOR help title displayed on a Japanese OS). The caveat here is when the help title is compiled as English. English help titles can display their titlebar string on all operating systems since all of the code pages support English.

    Unfortunately the check is too strict. Only the Primary Language ID should be checked, however HH also checks the Secondary Language ID causing say Portuguese (Brazil) help to display HTML Help on a Portuguese (Portugal) PC.

    In the case of English help, in the past all help had to be set to English (US). This bug was fixed in HH 1.31? and now English (Australian) help for example will display correctly on all systems.
  • Why do my Icons, Images and document style fail to show?

    Once IE6 Temporary Internet Files Cache fills up you can see some really weird side effects when viewing CHM help files. Icons and images not showing, style sheets not being applied correctly to documents. The fix is to simply empty your IE cache.

    - Open IE Internet Options dialog (Tools > Internet Options, or via Control Panel)
    - Click "Delete Files" button

    The HH Viewer window should now display content correctly. If it doesn't then try closing a few windows --  Often I find that when many IE windows are open and resources are low I start to lose TOC and Toolbar Icons.
  • Why do I see the filename containing %20 in the Favorites page instead of the topic Title?

    This is another side effect of using spaces in folders and filenames. Best to use underscores instead of spaces.
    HTML Help incorrectly sees a difference between %20 = SPACE and apparently cannot find the file and title.
    This bug has been reported to MS.
  • Why wont my CHM open?

    We mentioned above that when a file is named (with a leading ".H") it rightly or wrongly tells the HH Compiler that this is a HTML file and should be parsed for search terms. We found another beauty... User had a binary file xxx.swf in a folder \\. The compiler reported no errors compiling help however if you looked inside the CHM (using FAR) all the usual #???? files required by a CHM were missing. When you tried to open the CHM you got an error message "Cannot open the file :mk:@MSITStore:FILENAME.chm". The fix was to remove the leading ".H" from folders and filenames. EG. Rename folder \\ to say \\.
  • Images don't show in the CHM

    Here are the typical reasons why images do not displaying in your CHM:
    • If you use Word to edit the HTML files then the help compiler wont recognize the DHTML type image include statements. Open the .HHP project file in a text editor and add the images to the [FILES] section (or use FAR or your authoring program to add the images).
    • Try emptying the Temp files cache. Images often wont display when IE6 Temp files cache fills up.
      Internet Explorer: Tool > Internet Options, Delete File button.
    • Debug: View inside the CHM using FAR Explorer, or right+click an image to view its Properties and view its file path.
      Is the images where you expected it to be?  Is the image in the root of the CHM instead of in a folder? Then see next section.
    • Authors often include images via ..\ type path. Files placed in a CHM must be in or under the HHP project dir. The .HHP project file represents the root of the CHM so obviously a file included from a ..\ or ..\..\ type folder has no meaning and the compiler simply dumps the file in the root of the CHM (think of a CHM as a ZIP file containing relative file paths). If you need to include files into the CHM that are in folders above or adjacent to the .HHP folder then you will need to either copy those file across, or move the .hhp/.hhc/.hhk project type files higher in your directory structure (and adjust all their internal file paths accordingly).


  • Removing "Jump to URL" menu items

    How do you remove the "Jump to URL" menu item from the various HH viewer menus?

    It appears that this item (along with the "View Entry" which I don't see anymore under XP) were originally linked to the presence of HTML Help Workshop. The following registry key controlled its visibility. Removing the key would make the "Jump to URL" go away (Thanks Ralph Walden).

    HKEY_CURRENT_USER\Software\Microsoft\HtmlHelp Author

    Under Windows XP (all versions) the "Jump to URL" menu items are now linked to the NoRun Group Policy. Set NoRun=1 to hide or disable the menu items.
  (Search for "NoRun")
    Warning: Enabling the NoRun Policy will remove the "Jump to URL" menu item AND remove the Run command from the Windows start menu (after a reboot).

    As a MS partner I have access to the HTML Help code. This is what the code does...

    Open Reg key HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Policies\Explorer
    Read (Dword item) NoRun

    if item found and (NoRun == 1) hide JumpToUrl
    if item not found then 
       // try looking for same key in HKEY_LOCAL_MACHINE

      Open Reg key HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Policies\Explorer
      Read (Dword item) NoRun

      if item found and (NoRun == 1) hide JumpToUrl


  • Why do my TOC labels change at Run-time?

    Interesting problem. A user found that some run-time TOC labels, were different than the design-time TOC labels.

    Here's what we found:

    In MSDN mode (Binary TOC selected), if 2 or more TOC items share the same URL then they will all be forced to use the last TOC label.

    E.G. We have 3 TOC items "xxx", "yyy" and "zzz" that all point to the same URL "make.htm". At runtime all these TOC items will display "zzz" (the last occurrence in the TOC).


    1. Don't use Binary TOC (but you will lose MSDN Next/Prev button functionality if used)
        (Sync and Font buttons will still work)
    2. Don't make 2 TOC items point to same URL. Or see Redirect solution below.

    Note that duplicate TOC URLs also cause other problems:

    1. Sync button will only sync to last occurrence.
    2. TOC auto sync will only sync to first occurrence.
    3. Merging -- If 2 CHMs are merged and each point to "index.htm" (same file name but different locations) then TOC Auto Sync (and from memory Search result links) wont work correctly (Sync is based on file name not the full file path). So make sure you use unique file names everywhere -- E.G. don't use file name index.htm in every folder.

    Redirect solution:

    Point your duplicate TOC item to a unique file name (URL) that contains code to redirect to the correct URL. 
    Works well and user is unaware of redirection.

    Example of Redirection file. More discussion on Redirection can be found below at Fixing TOC Auto-sync (Tips & Tricks)
    <head><title>Some Title</title>


  • Why do I get a HH_GET_WIN_TYPE Run-time Error?

    Typically when you compile and run your CHM it runs ok on your PC, but when copied to another machine or folder you may see the following error:
       The window name "main" passed to HH_GET_WIN_TYPE has not been specified

    In FAR HH project editor there is a checkbox "Create .chi Index file" (Compiler page). Make sure this is UNCHECKED. This is only used for making very old MSDN document systems. When checked, a .CHI index file is created that must be installed in the same folder as the CHM file (otherwise you get this start up error).

    Alternatively open up your .HHP project file using notepad and remove the line "Create CHI file=Yes" and recompile.

  • How do I reset the help window size and position?

    The file "hh.dat" stores all your CHM window size, position, preferences and favourites information. It's an ITS file (same proprietary file format as a .CHM file) so it can't be edited.  Delete "hh.dat" to reset all CHM windows to their default settings. It will be recreated by Windows later.

    Tip: The Favourites information is written to the "hh.dat" file, but not immediately, so there can be a timing problem if you close and reopen a CHM file in fairly quick succession. 

    Typical locations for hh.dat:

    Tip: By default Windows hides files marked as hidden or system from Explorer. Using "Control Panel > Folder Options > View" enable the viewing of all files.

    Windows 95 single user
    \Windows\Application Data\Microsoft\HTML Help\  (hh 1.3 and greater)

    Windows 98 single user
    \Windows\Application Data\Microsoft\HTML Help 
    Windows 98 multi-user
    \Windows\Profiles\%username%\Application Data\Microsoft\HTML Help 

    Windows 2000
    \Documents and Settings\%username%\Application Data\Microsoft\HTML Help 

    Windows NT 4.0
    \Winnt\Profiles\%username%\Application Data\Microsoft\HTML Help

    Windows XP
    \Documents and Settings\%username%\Application Data\Microsoft\HTML Help

    Windows Vista
    \Users\%username%\AppData\Roaming\Microsoft\HTML Help

  • What is a .CHW file?

     Ralph Walden:  These are normally created on the fly, though you can ship them. They contain the combined index when two or more files are merged. They are not compressed, which makes sense if HH is creating them on the fly (compression requires a significant amount of memory, and can be fairly slow). However, if they are to be shipped, then compressing them makes a lot of sense.
     Rob:  The CHW file that ships with MSDN (VS 6.x) is 50MB. That can be recompiled down to about 5MB by our shareware utility FAR HTML.  The CHW file format is an ITS file the same as a CHM file.
     You can safely delete .CHW files and they will be recreated next time you open help. The WinHelp equivalent file was the .GID file

  • CHM crashes

    There is a situation where a .CHM help file appears to compile OK but crashes when you try and viewing the ,CHM, or open the Search tab, or attempt a search.

    This problem arises when some Help Authoring Tools (HATs) install & register outdated Microsoft compiler DLLs to non-standard locations. They should have downloaded and installed the full HH Workshop. Microsoft then upgrade the runtime DLLs causing a mismatch that crashes the help viewer.

    Well whatever the reason we have created a tool to validate and fix these registered DLL problems:


Toolbar Buttons

  • How to enable the Next/Preview Browse buttons?

    These buttons seen on the MSDN window (HH 1.x based system) are normally not available via MS HH Workshop (although see "Workshop Secrets" below). You can enable them by using the  FAR HTML Help Project Editor. Once you have enabled the Next/Previous buttons (Toolbar page) you must also make sure Binary TOC and Binary Index are selected (Compiler page). 

    Note:  Binary TOC mode is incompatible with Merge help, Information types, and Custom TOC icons -- these HH features all require the default Non-binary TOC setting. Thus Next/Previous buttons only work with single CHM help systems.

    Tip: Next/Previous page browsing may not work correctly if the topic filenames contain space characters. 
  • Workshop Secrets

    The Next/Previous/Zoom buttons (used by HH 1.x based MSDN), can be displayed in Workshop (normally hidden). A recent post from Jeremy Griffith says -- In the Workshop Open dialog, type "I'm MSDN" (without quotes) and click Open. Window Types button settings "Next, Previous, Zoom" are now visible, as well as project checkbox "Create .CHI Index file". 

    From Richard Quadling:
      You can also unset it using "I'm not MSDN". This actually adds/removes 0x80000 to the regkey
      HKCU\Software\Microsoft\HTML Help Workshop\Settings\profile

    Note: There are limitations (see section above).

  • I changed the TOC icons but do not see changes after compilation?

    Customizing  icons are not compatible with Binary TOC.  Set your project to the defaults of Non-Binary TOC & Binary index then recompile.

  • How do I add Font Size (Zoom) toolbar button?

    This buttons seen on the MSDN window is normally not available via MS HH Workshop (although see "Workshop Secrets" above). You can enable it by using the FAR HTML Help Project Editor.

    See also:;EN-US;Q240062&

  • Can I create my own custom toolbar buttons?

    Only two custom buttons are available under 1.x. They have a fixed icon and can only call a URL. They cannot call script or ActiveX, however you could open a topic that triggers some script while the page loads.

General Information 

HH File Formats

Navigation Pane Page Tabs

The navigation pane can contain a Contents, Index, Search and Favorites page tab. The Contents tab (AKA Table Of Contents or TOC) is defined by a file with a .hhc file extension. The Index tab is defined by a file with a .hhk file extension. The search and favorites tabs do not require extra files. Your HH authoring tool can create and edit .hhc and .hhk files.

  • How do I remove the Navigation pane?

    This is not obvious. 
  1. Open your HHP Editor.
  2. To remove the Contents and Index tabs:
    Clear all edit fields that specify a .hhc or .hhk file. In FAR these fields are on the "Compiler " page and also the "Files" page (if a Window Type is defined). 
  3. To remove the Full Text Search tab:
    Clear the  "Compile FTS information" checkbox.  In FAR this is on the "Compiler Page". Also clear the "Show Search Tab" checkbox. In FAR this is  on the "TriPane" page  (if a Window Type is defined).  
  4. To remove the Favorites tab:
    Clear the "Show Favorites Tab" checkbox. In FAR this is on the "TriPane" page. If you do not have a "TriPane" page then you may need to define a Window Type. In Workshop this on the "Navigation Pane" page of the Window Types dialog.
  5. If you want to remove the toolbar pane:
    Deselect all toolbar buttons and recompile. You will need to create a default window definition if you don't have one. 
  • Can I open a HH window open with Navigation pane initially closed? 
  1. Open the FAR HHP Editor window or HH Workshop.
  2. Define a Window Type if you do not have one ("Window Type" page).
  3. FAR: Clear the "Remember window position & size" checkbox on the "Window Types" page. 
    Workshop: Clear "Save window position" ("Position" page tab in the "Window Types" dialog)
    This stops the window remembering if the navigation pane was open or not.
  4. FAR: Check the box labeled "Initially closed" in the "TriPane" page
    Workshop: Check the box labeled "Open with navigation pane closed" in the "Navigation" page.


HH.EXE Params 

q  HH.EXE is distributed with HTML Help so you can rely on it being present. It lives in the Windows folder and has a limited number of command-line options. HH.EXE is associated with .CHM files. So double-click a .CHM file and Windows will open the file using HH.EXE. It is a very small file, it mostly passes the help filename onto a HH API library. HH.EXE is not single instance, if you open a CHM file three times using HH.EXE, then three help windows will appear.

Example of opening a help topic using Help ID = 1001

HH.EXE  -mapid 1001 ms-its:path/help.chm

Note: The “–map <ID> <file.chm>” command line became available in HH 1.1b.

Example of opening a help topic using a topic path

HH.EXE  ms-its::path/help.chm::/path/topic.htm
HH.EXE  mk:@MSITStore:path/help.chm::/path/topic.htm

Example of using HH.EXE to decompile a CHM help file

HH.EXE  -decompile  destdir  file.chm
where "destdir" is the directory to put the files into. This could be simply "."

Note: The mk:@MSITStore protocol works with IE3 and above while ms-its works with IE4 and above. A shorter version of “ms-its” is to just use “its”. Actually, the later versions of HH don’t even require the protocol prefix.

q       KeyHH.EXE is a free program from KeyWorks Software, written by Ralph Walden. KeyHH.EXE supports many more command line options then HH.EXE. I have to say that KeyHH.EXE is an excellent program. I distribute it with most applications I help produce. 

You can get more information about KeyHH.EXE from the KeyWorks web site at

Known HTML Help Bugs

Security Updates Break HTML Help

A series of security fixes has now reduced HTML Help to functioning as local help only.
See: Security Updates that Break HH

Relative Path Bug


"Help cannot find a system component"

Every application has a Current Directory setting. DLLs like the HH 1.x API do not. Their Current Directory is the host applications Current Directory. When we launch help via Explorer, the host is HH.EXE -- a small launch program that Windows has associated with .CHM files. Open a .CHM using Explorer or Windows Shell, and HH.EXE calls the API to launch the .CHM file.

HH.EXE politely sets its "Current Directory" to be the .CHM folder. This is good, because imagine we have other .CHM help files, programs, documents etc. in the same folder. In a merged help system, or when a CHM topic uses a HH Shortcut command, it is important that the Current Directory is set correctly, otherwise these other help components will not be found.

Problems arise however, when "our" applications open help (using the Help API). The application will often change the Current Directory when a user performs File > Open, or File > Save As etc. Or maybe the .CHM help file(s) are stored below the Application Folder in a .\Help folder. The user presses F1, we launch the main .CHM help file, however we have an incorrect Current Directory, and Merging and shortcuts all fail.

Fix #1:

The best fix that I have found is this: In your application code, just prior to performing a Help API call (to open help). Set the Current Directory to the Help directory (your developer knows how to do this). If required, you can reset the Current Directory back to its original setting after the API call.

Another fix that some folk use is to make sure the help components are installed to folders in the Windows search path. From memory, this helps with HH Shortcuts only. For Example we have a video viewer we launch via HH Shortcut. We install the Video Viewer into the Windows directory where it can always be found.

This Current Directory bug is probably the main reason why the next generation of help (MS Help 2.x), now uses the Namespace system instead of the file system.

Words From Wizard Ralph Walden (x-MS):

To help windows locate a help file, place the name of the help file in a special registry key or ini file.

[HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\HTML Help]
Name = myfile.chm
Data = "c:\chmfolder\"

Or use HH.INI. You do not need to reboot a Win95 machine for the registry to work. 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 CDROM disk. The format is identical to the WinHelp.ini file. The following docs are taken from the hcw.hlp file and modified for HTML Help:

HLP-filename=path, message

Example: The following 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.


Shortcut Fix: #2 From Mr Wizard "Rainer H. Rauschenberg" <rainerh AT>

Rainer builds the full path to the external file using some cleaver script. Thanks Rainer:

document.write('<OBJECT id=myid type="application/x-oleobject"');
document.write('        classid="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"');
document.write('        codebase="hhctrl.ocx#Version=4,72,8252,0"');
document.write('        width=100');
document.write('        height=100');
document.write('        <PARAM name="Command" value="ShortCut">');
document.write('        <PARAM name="Button" value="Text:Test">');
document.write('        <PARAM name="Item1" value=",');

Rainer: "only drawback I found is that ',' are not allowed in the path"
Updated examples from Rainer (German site)

Rob Chandler: Script Update -- I found that my IE6 topic location.href file paths inside a CHM can now be prefixed with either mk:@MSITStore or ms-its or its: (before was only mk:@MSITStore).

See below Script_to_External_File (Tips & Tricks)


Search Results & Binary TOC 

Normally when you perform a search, the results list is a bunch of items with titles lifted from each documents <title> tag.  But if you have enabled Binary TOC you may see Titles that do not seem to correspond with the associated Topics. What happens is for a Binary TOC the topic title is lifted from a TOC item label instead of the documents <title> tag. I suspect that this is a HH 1.x Collections feature. 

W2K SP4 - Links Fail


A few Windows 2000 users have recently reported that the links in their HTML Help files stopped working after they installed Windows 2000 Service Pack 4. Installing the latest critical update did not fix the problem.


Apparently with SP4 IE overwrote the hhctrl.ocx CLSID with the wrong registry key. The fix is to unregister then register hhctrl.ocx (the unregister must be done first).

   regsvr32 /u <drive>:/winnt/system32/hhctrl.ocx
regsvr32 <drive>:/winnt/system32/hhctrl.ocx

When this problem occurs on platforms other than Windows 2000 SP4, the solution is to install Critical Update 811630.

Embedding Causes Popups


After downloading the latest Internet Explorer I now get popups showing for HTML that contains embedded (ActiveX & Java) content.


This is because some idiot has selfishly rolled MS for half a Billion US$ over a very old patent on embedding remote content. The end result is MS IE must now show a popup message when embedding remote content in HTML.

The solution at the moment is to put offending <object> and <applet> statements in a separate JS include file and use document.wrtite() statements. Local ActiveX is not a problem.

MS have produced a test IE6 application you can download to a local folder (it will not disturb your normal IE installation) . Once installed try opening a web page with embedded content.

MS have published fix up notes here

Other reading

Note: I think MS have probably resolved this issue now.

The Same CHM Opens Bug


I have a number of CHMs all with the same filename (but different folders). When my application switches between these CHMs the original CHM is always displayed, even though the absolute path to each CHM is used.


The HH API has an annoying ability to remember a CHM by its filename only (no directory). Thus when an application opens c:\test1\Help.CHM then closes that and opens c:\test2\Help.CHM the result is that the Test1 file is displayed both times.

One fix is to close your application between each CHM opening. The easiest fix is to call FreeLibrary() then LoadLibrary() on the HHCtrl.OCX Library before opening each CHM.

This second solution only works if your application dynamically loads the HH API (HHCtrl.OCX) using LoadLibrary. Applications written in languages such as VB which statically load the API wont be able to do this.


Multi-page Print Bugs

Multi-page print breaks for images not wrapped in double-quotes

Reported by: Greg Walker, 20-Feb-2004, HH Version 5.2.3644.0
Verified by: Rob Chandler, HH version 5.2.3735.0.

Nov 2004 - RWC: Sounds like the bug introduced in HH 1.4 (5.2.3644.0) this bug was fixed shortly after in HH 1.4a (5.2.3669.0) -- See HH 1.4

From Greg:

HTMLHelp is not translating img tags when preparing a multi-page print temp file (right-click on a topic in TOC and select Print:All subtopics) UNLESS the src is encased in double-quotes.  HTML standard accepts double-, single-, or no quotes at all.

Sample html in original:

    <img src=img/thing1.gif ...>
    <img src='img/thing2.gif' ...>
    <img src="img/thing3.gif" ..>

Viewed in CHM all three images are displayed.  Print a single page, all images print.  Print from topic, and this is what is generated:

    <img src=mk:@MSITStore:C:\Program Files\blah\PrintBug.chm::/img/thing1.gif ...>
    <img src=mk:@MSITStore:C:\Program Files\blah\PrintBug.chm::/'img/thing2.gif' ...>
    <img src="mk:@MSITStore:C:\Program Files\blah\PrintBug.chm::/img/thing3.gif" ...>

Note the CHM is stored in a directory path containing spaces.

Thing1.gif does not print because there is a space in the path (Program~Files).  Thing2.gif does not print because the single-quotes are in the wrong place.  Only thing3.gif is printed.

This happens with the latest HH.exe (5.2.3644.0).  Workaround is to ALWAYS use double-quotes.

From Manny:

I found a different problem.  I was using double quotes for all my images but still did not get some pictures to print.  I was able to discover the problem.  HTML Help requires the <img tag and the src= attribute to be on the same line!  If they are not on the same line then HTM Help will not recognize that it needs to put the special mk:@MSITStore tag in front of the src= attribute.

From obab: 11/11/2006

** The Multipage issue: **:
I had the border attribute first:
<IMG border="0" SRC="images\pagedirector.jpg" ></IMG>
I put SRC first (and then removed the quotes off border as I saw an example 
without the quotes).
<IMG SRC="images\pagedirector.jpg" border=0></IMG>
this works now

** The stylesheet issue: **
I originally copied this line from the HHW help and just changed its values:
<LINK REL = "stylesheet" TYPE = "text/css" HREF = "css\Style.css">
On multipage print it threw errors until I notices spaces on each side of 
the "=" sign. Once I removed the spaces it all worked fine.
<LINK REL="stylesheet" TYPE="text/css" HREF="css\Style.css">

Microsoft Hot Fixes 

Typy into Index search box freezes HTML Help viewer. At the time of writing this fix has been rejected for Windows 10 updates.