Home‎ > ‎My Notebook‎ > ‎

HH Workshop (p1)

Part 1 | Part 2
MS HH Workshop tutorial by Rob Chandler

FAQ

What is HH Workshop?

HH Workshop is the free authoring tool provided by Microsoft for creating HTML Help (.CHM help files).

First released 1997 as the help system for Internet Explorer 4. More update history on the Helpware.net site.

How do I install It?

> Download from Microsoft
The installer HTMLHelp.exe installs the following to C:\Program Files\HTML Help Workshop\
  • HHW.exe - Authoring application.
  • HHC.exe - Command line compiler.
  • HHA.dll - Compiler engine used by HHW.exe, HHC.exe and all 3rd party HATs.
  • HHUpdate.exe - Installs the HH Runtime for viewing .CHM files.
  • Other support dlls and files.
Notes:
  1. HHUpdate.exe is no longer required since the HH runtime files are now part of the Windows OS. You may see a small error at the end of Workshop installation. This is HHUpdate failing because the OS files can no longer be updated. Ignore this error. Windows update, Hot fixes, and Windows Service Packs etc are the only way to update HH runtime now.
  2. Microsoft no longer update HTML Help apart from necessary maintenance (eg. security fixes).
  3. Third party apps such as FAR, Flare, RoboHelp all required Workshop to be installed for the compiler part.

Introduction

It's fairly simple to create HTML Help. In fact compared to the old WinHelp (.RTF based) and the newer MS Help 2 (MSDN Help) and AP Help (Vista Help) it's very simple.

First create your help content (HTML files and image files). With your HAT (Help Authoring Tool) create a new project (.HHP) file. Next create your TOC (Table Of Contents) file and an optional Index (,HHK) file. That's it. Compile and you have a .CHM help file.


Help Content Files

This is your help source -- HTML document files, Images files (JPG, GIF, PNG), Adobe Flash and Video.
Most web type files can be compiled to HTML Help (however there are some minor exceptions).

When creating the HTML docs (one for each Help page) use a good HTML editor such as: MS FrontPage, MS Web Expression, Adobe Dreamweaver etc. Don't use MS Word as it does not create clean HTML.

HH Project file (.HHP)

Your authoring tool will create a .HHP project file for you. This file is NOT optional. You pass this file to the HH Compiler to create a .CHM help file.

The project file defines the project. It is a simple INI ASCII file and can be viewed / edited in any text editor (if you know the format).
It defines:
  • Which files  (your content files) to compile to .CHM help file.
  • The name of the Table of Contents file (,HHC) to use (Optional).
  • The name of the Index file (.HHK) to use (optional).
  • Defines one or more help window (color, font, languge, size, position etc)

Table of Contents file (.HHC) - Optional

This file populates the Content navigation tab. It is a simple ASCII file format like HTML, called Sitemap format.
Workshop contains a simple TOC editor that lets you create and edit .HHC files.


Index file (.HHK) - Optional

This file populates the Index navigation tab. It is also sitemap format.
Workshop contains a simple Index editor that lets you create and edit .HHK files.


Compile to .CHM Help File

Once the .HHP project file is created or opened by Workshop, you can tweak various project settings and compile (create) a .CHM help file.

When you compile (create a .CHM help file) a few things happen:
  1. All your HTML file are parsed for search terms and added to the CHM.
  2. All your content + TOC + Index is compressed and added to the CHM.
NOTE: There is a quirk with the HH compiler. The compiler searches your HHC, HHK and HTML files and finds links to other HTML files, then opens these files and finds more links etc. etc. And finally compiles all these files into the .CHM help file. So beware. :-)

Decompiling Help

CHM files can be decompiled back to "ALMOST" the original source (any keywords embedded in the HTML will be lost). Workshop cannot recover the original TOC (.HHC) file. Instead use the free tool "KEYTOOLS" from http://www.keyworks.net/. KeyWorks software is written by Ralph Walden (Ralph wrote much of MS HTML Help) and MVP Cheryl Lockett Zubak.


What's Broken in Workshop?

During 2004-2005 Windows was constantly under attack. In an effort to close the many security holes MS decided to reduce HTML Help's functionality to that of local help only.

It's important to note that while Workshop help documents the following remote features, they don't actually work anymore in Windows XP and later.
  • HTML Help ActiveX Control
    The main help code library (executable) for the HH Viewer is stored in hhctrl.ocx. So this is a DLL with some ActiveX functionality. Before the security updates you could use this control to embed the TOC and Index into web pages. 
  • The HTML Help Java Applet
    This used Sun Java as an alternative way to embed navigation (TOC/Index) into a web page. It was never maintained by Microsoft and has fallen into an unusable state (even before the crippling security updates). So just ignore this feature.

There are other documented features that don't work (development team ran out of time? Or maybe it's because Ralph left MS).
  • Background Color of TOC
    Does not work correctly. Color is patchy around the [+] [-] tree controls,
  • Information Types
    This is a kind of content filtering. Great idea but never completed. Ignore Info Type settings.
    It probably works in the MSDN version of HH (internal customers), but they never got it working for us.

See also

Tips for Beginners

You can think a CHM like a ZIP file. A single compressed file containing your entire help web, along with search, navigation and window definition data. And like a ZIP file all internal files are referenced by relative links (there is no concept of an absolute path inside a ZIP).

Content must live under the project folder.

So adding source files to a project from locations other than under the project folder (the folder containing your HHP, HHC, HHK files) just wont work. Any files with a relative path starting with ..\ such as ..\path\file.html will be dumped into the root of the CHM during compilation (where else can they be put). So links will break if files are added from locations other than  under the project folder.

For more tips see

 





Comments