HTMLHelp command-line

HH.EXE is distributed with Windows HTMLHelp 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. Its 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.

You can download a single CHM sample file (CHM in ZIP) for your own experiments with the HTMLHelp command line. Then unzip the file to a local drive, e.g. D:/_temp.

A compiled help file retains the folder structure in which it was organized before compilation.

For example, if a project is organized in three folders (one for HTML files, one for images, and one for style sheets), the help file will contain those same folders internally. The folder in which the project file resides is considered the root. To correctly link to a topic file, you must specify the full path.

Command line or batch file

Call from command line or a batch script:

hh.exe mk:@MSITStore:D:\_temp\CHM-example.chm::/Garden/flowers.htm

To suppress the DOS windows using the command in a batch script, the call can be carried out with the parameter /B.

start /B hh.exe mk:@MSITStore:D:\_temp\CHM-example.chm::/Garden/flowers.htm

Further information on this parameter can be found at Simon Sheppard's website.

Open help topic with help ID

The help ID is a number e.g. 20010 that you've defined in the [MAP] section of your project (.hhp) file and mapped to the required topic in the [ALIAS] section. The -map ID chm command line feature became available in HTMLHelp Vversion 1.1b.

hh.exe -mapid 20010 ms-its:D:\_temp\CHM-example.chm

Open help topic with path specification

The mk:@MSITStore protocol is an earlier version and works with IE3 and above while ms-its works with IE4 and above. A shorter version of "ms-its" is to just use "its".

hh.exe mk:@MSITStore:D:\_temp\CHM-example.chm::/Garden/tree.htm

hh.exe ms-its:D:\_temp\CHM-example.chm::/Garden/tree.htm

hh.exe its:D:\_temp\CHM-example.chm::/Garden/tree.htm

Actually, the later versions of HH don't even require the protocol prefix.

hh.exe D:\_temp\CHM-example.chm::/Garden/tree.htm

You can omit the path to the CHM file if this file is stored in the %SystemRoot%\Help directory or is registered under the following key in the Windows registry: HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\HTML Help.

hh.exe CHM-example.chm

It's possible to jump to bookmarks e.g. AnchorSample coded in your HTML topic like:

hh.exe D:\_temp\CHM-example.chm::/HTMLHelp_Examples/Jump_to_anchor.htm#AnchorSample

For special cases e.g. to create a standalone HTML Help window you may want to install KeyHH (EXE in ZIP) as a free program from KeyWorks Software, written by Ralph Walden. KeyHH.exe is a program that augments HTML Help. It can be used in addition to or as a complete replacement for HH.EXE. KeyHH provides all of the functionality of HH.EXE, offers solutions for some known bugs in HTML Help, and provides additional functionality as well.

• Download KeyHH.zip
• Unzip the KeyHH.exe contained in the ZIP into a temporary folder e.g. D:/_temp
• Cut KeyHH.exe and paste to C:/Windows where hh.exe also resides (with administrator rights)

As a retired Microsoft Help MVP I have copied the content some years ago to http://keyworks.help-info.de. You can find more information here. The old website keyworks.net is no longer available.

Application examples to open a help topic

Run command

Remember old MS-DOS and the todays Windows 10 Keyboard Shortcuts and Run Commands. Try Windows + R

Command prompt

PowerShell

Internet Explorer 11

The ability to look inside an ITS (CHM) file is something unique to Microsoft Internet Explorer only. Only Internet Explorer (NOT Microsoft Edge browser) could load a locally path like:

ms-its:D:\_temp\CHM-example.chm::/Garden/tree.htm

The prefix ms-its: is a pluggable protocol from earlier days that follows old standards set up by the World Wide Web Consortium (W3C). The ms-its protocol works with Microsoft Internet Explorer 4.0 or later, but is not supported in all browsers.

Warning

Use the following trick for a test case only. Internet Explorer is end of life and you will end up browsing with multiple unpatched security holes.

Simply create a VBScript file e.g. Internet-Explorer.vbs with the following code.

CreateObject("InternetExplorer.Application").Visible=true

This launches the IE pre-installed on Windows 10/11. At this stage it's bundled with Windows but can't be launched directly by clicking its executable.

If you want to use PowerShell, you can save the following code in a file and execute it:

# start Internet Explorer (IE is outdated - you are warned!)
$ie_com = new-object -comobject InternetExplorer.Application -strict

# set local path to CHM topic file
$ie_its = "ms-its:D:\_temp\CHM-example.chm::/Garden/tree.htm"

# navigate
Write-Host "Connecting using URL:`n $ie_its"
$ie_com.navigate2($ie_its)
Write-Host "Successfully created Internet Explorer window with:`n $ie_its"

# make it visible (just to check what is happening)
$ie_com.visible = $true

Decompile a CHM help file using HH.EXE

As mentioned above the %SystemRoot%\hh.exe is the viewer for CHM files in Windows and can not only display CHM files but also extract CHM files. No interface - just enter hh.exe -decompile <target_directory> <path>\<filename>.chm into a command prompt, batch file or PowerShell window and amend as necessary. where is the directory to put the files into. This could be simply "."

hh.exe -decompile D:/_temp/decompile-folder D:/_temp/CHM-example.chm

Please note, it is only possible to use -decompile with folder path and help file name not containing a space character. hh.exe is poor coded regarding to command line argument strings parsing. It supports hh.exe "D:\gxml\test\a b\1.chm" to open a compiled help file with a space in fully qualified help file name. But on using -decompile it interprets the first series of spaces after -decompile always as beginning of the folder path and the second series of spaces after -decompile as beginning of the help file name even on using quotation marks around the two argument strings.

Decompiling the file produces a slew of HTML and image files, together with the table of contents (.hhc) file, index (.hhk) file, and a few other supporting files.

One thing to note is that the decompile/recompile process isn't a "round-trip" process. Certain features that the help author added to the original help file can't be recovered when you decompile it, so these may no longer work properly after you've recompiled. This is especially true in the area of context-sensitive help, which may be broken in the new version of the file.

Note

A special trick among help authors is to compile the project file .hhp into the CHM file. This can make decompiling much easier. Unfortunately, this is only the case in very few exceptional cases.

How to decompile using KeyTools

The only decompiler with any additional features is KeyTools, as this can try to rebuild the project (.hhp) file. You will need this file if you want to recompile the help project.

If required, you can find detailed installation instructions here.

Compiling HTMLHelp from the command line

You should download a CHM sample project (ZIP) for your own experiments with the HTMLHelp Workshop compiler. Then unzip the file to a local drive, e.g. D:/_temp.

From a folder that contains the HTMLHelp Workshop project file (.hhp) the required compiler command is:

hhc CHM-example.hhp

You must specify the relative or absolute path to the .hhp file if compiling from a folder other than the one that contains this file. And you'll need to ensure that the HTMLHelp Workshop program folder is in the path, as that's where hhc.exe resides.

• Close all instances of the HTMLHelp Workshop
• Click on the Start menu, choose Run and type cmd

• Type for Windows 10 e.g.

  "%ProgramFiles(x86)%\HTML Help Workshop\hhc" d:_temp\CHM-example.hhp

or to get a log file in the current directory (if not already declared under [Options] in the .hhp project file like Error log file=_errorlog.txt)

"%ProgramFiles(x86)%\HTML Help Workshop\hhc" d:\_temp\CHM-example.hhp > log.txt

This command assumes that you have installed HTMLHelp Workshop to the default path, so you will have to modify this command line if you installed to a non-default path.

On old 32bit Windows, %ProgramFiles% is your friend.

On 64bit Windows, things have changed, as application can be installed both in %ProgramFiles% and %ProgramFiles(x86)%.

VBA (Excel) example

Sub HTMLHelp_Compile()
'// call HTMLHelp file (CHM) compiler from Excel (VBA)

Shell """C:\Program Files\HTML Help Workshop\hhc.exe""" & _
"d:\_temp\CHM-example.hhp", vbNormalFocus

End Sub

---