Thursday, October 12, 2006

Compiling HTML Help Workshop Projects in Visual Studio 2005

Like many other software development shops, we use Microsoft HTML Help Workshop to create compiled HTML help files (.chm) for distribution with our packaged software applications. Although we add the .hhp project files, index files, pages and other help related artifacts to our Visual Studio solution so that they get vaulted along with our application source code into Team Foundation Server, I've always relied on the HTML Help Workshop UI itself to do the actual help file compilation.

In the interest of saving some time and having a few less apps open while I'm developing, I wanted to be able to compile the help project from within Visual Studio itself. Initially, I considered adding a call to hhc.exe from my Visual Studio project's post build event. The downside to this approach would be wasted CPU cycles (and compile time) for all those times when I'm compiling the code but no changes have been made to the help file content. Of course, I could mitigate the wasted cycles by putting some incremental build logic into my Visual Studio project with a bit of MSBuild code, but I really just wanted an on-demand method for compiling the HTML Help Workshop projects when I need to. The solution that seems to meet my requirements the best has been to configure an External Tool from Visual Studio 2005 to call hhc.exe on-demand when I have the .hhp project open. Here's how:

1. In Visual Studio 2005, select Tools->External Tools.

2. When the External Tool dialog pops up, fill-in the values as shown. Note that the macro $(ItemPath) indicates the item currently open in Visual Studio 2005's source editor pane.

3. Now that hhc.exe is configured as an external tool, you can open the .hhp project file.

4. And Select Tools->Compile Html Help.

The output from HTML Help Workshop's compiler will be displayed in Visual Studio 2005's Output window.

Categories: , , , ,

1 comment:

Anonymous said...

I had to do the whole re-"Import and Export Settings" trick with VS2005 before I could get this to work. But once I did it worked beautifully for building my help as well as my Inno Setup scripts.