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 http://msdn2.microsoft.com/en-us/library/ms670169.aspx 
  
  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. 
  See: http://www.workwrite.com/helpthink/errors_zubak.htm
  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: http://www.mvps.org/htmlhelpcenter/itircl.htm
  



• 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.

  Debugging: 

  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.
  
  Helpware.net 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 xxx.Hxxx.xxx (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 \xxx.Hxxx.xxx\. 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 \www.Havoc.com\ to say \Havoc.com\.
   

• 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.
   
  http://support.microsoft.com/kb/292504/EN-US/  (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).
  
  Work-a-rounds:
  
  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)
   

  <html> <head><title>Some Title</title> <script>   window.location.replace("MyTopic.htm"); </script> </head> <body> </body> </html>

• 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\hh.dat
  \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:
• MJs Diagnostics -- version 3 is now compatible with Windows 64 bit 

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: http://support.microsoft.com/default.aspx?scid=KB;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