Compiling Help File as Part of Visual Studio Solution

I think that Microsoft has dropped the ball on creating help files. The technology has not changed in about 25 years, and was never simple in the first place. The tools are primitive. Furthermore, there is no simple way to incorporate the building of the help file into a Visual Studio solution.

Building a help file is pretty much the same as building a web site. The pages are authored in HTML. The only difference is that there are some supplemental files that tell it how to build the Table of Contents (.hhc file) and the Index (.hhk file) to the help file, as well as a file to tell it what all the all the other files and provide the settings (.hhp file). There is a compiler that compiles the web site into a single .chm file.

To start with, let's go over the tools needed to build a help file. You need the Microsoft HTML Help Workshop. This provides the help compiler (hhc.exe), as well as a rudimentary Windows application for managing the files (hhw.exe). The content files are HTML. If you know HTML well, you can create them in any text editor. Despite knowing HTML backwards and forwards, I still prefer to edit them in an interface that understands HTML as it allows me to reformat the HTML and other features. Microsoft produced a tool for editing HTML that they have since abandoned called Microsoft Expression Web. You can download it for free from the Microsoft web site.

Visual Studio does not have a template that works with help file projects. So we have to kind of fake it out. Create a console application that will act as the help file project. The console application does not need to do anything, as we will be ignoring the compiled executable, and instead using the build events for the project to accomplish what we need.

Use hhw.exe to create the help project. Add HTML files to the project. The stuff below assumes that the name of the .hhp file is HelpProject.hhp, but you can rename it to anything else by making the appropriate changes below.  The HelpProject.hhp should be added to the root of the help project.

Then add compiling the help file to the build events for the console application. However, we have to work around one minor problem: the help compiler returns one on success and zero on failure, rather than the Windows standard of the other way around. Visual Studio considers a build event that returns something non-zero as a failure and terminates the build of the project. To reverse that, we need a short batch file. Add to the help project a file named helpcompiler.bat file that looks like this:

"%ProgramFiles(x86)%\HTML Help Workshop\hhc.exe" %1
if not errorlevel 1 exit /B 1

Then add this to the pre-build event in the Project Properties:

$(ProjectDir)helpcompiler.bat $(ProjectDir)HelpProject.hhp

When the help file compiles, it will produce HelpProject.chm in the same directory as where the HelpProject.hhp file is created. This is the compiled help file that you need. Add a line to the post-build event that copies the HelpProject.chm file to the final location where it is needed. For example:

xcopy /Y $(ProjectDir)HelpProject.chm $(SolutionDir)SomeOtherProject\bin\$(ConfigurationName)

With this hack,  Visual Studio will build the help file and copy it to where it needs to go as part of the build of the Solution.