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.
- Open your HHP Editor.
- 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).
- 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).
- 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.
- 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?
- Open the FAR HHP Editor window or HH Workshop.
- Define a Window Type if you do not have one ("Window Type" page).
- 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.
- 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 http://www.keyworks.net/.
Known Bugs
Security Updates Break HTML Help
Relative Path Bug
Problem:
"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:
[FILES]
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:
[FILES]
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 wiwi.uni-frankfurt.de>
Rainer builds the full path to the external file using some cleaver script. Thanks Rainer:
<SCRIPT LANGUAGE="JavaScript">
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('>');
document.write(' <PARAM name="Command" value="ShortCut">');
document.write(' <PARAM name="Button" value="Text:Test">');
document.write(' <PARAM name="Item1" value=",');
document.write(location.href.replace(/mk:@MSITStore:/,"").replace(/\\[^\\]+\.chm::.*$/,""));
document.write('\\otherhelpfile.chm,">');
document.write('</OBJECT>');
</SCRIPT> |
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
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
Problem:
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.
Solution:
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. http://support.microsoft.com/?kbid=811630
Embedding Causes Popups
Problem:
After downloading the latest Internet Explorer I now get popups showing for HTML that contains embedded (ActiveX & Java) content.
Solution:
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
Problem:
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.
Solution:
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">
