Help Builder can easily create Html Help 2.0 content. However, to do anything useful with the content generated you have to perform a few extra steps after you've created the Help 2.0 file. Note that in order to create Html Help 2.0 output you will need to download and install the Visual Studio Help Integration Kit which includes the Html Help 2.0 Help Compiler.

Let's start by creating a Help 2.0 Help file from your project. Use the Build Help Wizard. Make sure you select Generate Html Help 2.0 output checkbox on the Build Dialog.

Select the topics to generate

The second screen of the Wizard is designed to allow you to optionally choose the topic trees that are used to generate the final help file. Sometimes you might want to generate documentation just for your end users so it might make sense to not generate the developer documentation into the final help file.

The dialog allows you to select and unselect top level topics that are to be included in your final help file or HTML output. By default all topics are selected - if you want to exclude certain topic trees from inclusion simply uncheck the checkbox for this topic. When you uncheck a topic this topic and all child topics are removed from the help file resulting in smaller size.

Set the Help 2.0 Namespace for your Help file

When you select this option clicking Next will yield a secondary Html Help 2.0 page where you can select the name of an Html Namespace and name of the collection.

A namespace uniquely identifies your Help project. Generally this will be your company name plus something that identifies your project. By default it's the company name plus the name of the project.

Help 2.0 files can be made up of multiple 'Collections' and each help file that you build can potentially be merged with another to build a a collection of help files. For example, MSDN help in Visual Studio consists of a number of collections that you can view. By default the name of the collection is the name of your project file.

A namespace is typically in ProgId like format <company>.<someId>. You shouldn't use spaces or symbols in either of these fields.

Once built you have a number of options for your help file.

Run Help File
You can preview the help file directly from within the IDE. This operation goes out and registers your help file as a single Help file and displays it in the MSDN viewer. Please understand that in order for your help file to be viewable must be first registered. Help Builder performs this task for you and once registered you can view the Help file easily with the MSDN viewer with:

d:\program files\common files\Microsoft Shared\Help\dexplore.exe /helpcol 
 "ms-help://<YourHelpNamespace>/<YourHelpCollection>/"

Registration requires the Help 2.0 runtime files (which can be installed as part of your application) or by using a third party utility from Far Technologies which makes the process much easier and requires much less install space. To manually register a Help 2.0 file you need the have the HTML Runtime installed (VS Help SDK or the Visual Studio 2005 SDK). If installed you can use something like the following

<pre>"C:\Program Files\Visual Studio 2005 SDK\2006.09\VisualStudioIntegration\Archive\HelpIntegration\hxReg.exe" -n "WestWindTechnologies.webmonitor" -i "webmonitor" -s "c:\users\rstrahl\documents\html help builder projects\west wind test tools\west wind test tools.HxS"</pre>

where -n is the namespace -i the collection and -s the output Hxs file.

Note that this should be used only for development testing of the help file because Microsoft does not actually allow redistribution of the SDK tools nor do they provide a tool to register Help 2.0 collections. Additional work is required for merging into Visual Studio.

More on a better alternative later.

In addition to the standard output options available for any help file - view as HTML and Upload project to FTP Site, you can also open the Help 2.0 project in Visual Studio's Help 2.0 Workshop. This allows you to possibly manually add files, or change compiler options that aren't set through Help Builder.

Copy Help File
This option copies the entire Help 2.0 output files to a new location along with some helpful support files. This operation copies the HxS file, all the COL_*.* index files that can be used to merge into other collections, plus H2Reg support files. H2Reg is a very worthwhile Help 2.0 registration utility and if H2Reg.exe (requires a separate license from Helpware) exists in the project directory it's copied as well. A batch file Help20Register.bat runs the H2Reg command and generated script so you can easily register your help file into the VS.NET help collection for testing. Finally a shortcut was generated so you can easily view your help file in the Help 2.0 viewer without remembering the lengthy URL and path to the Help Viewer application.

The next section talks in more detail what you need to do in order to distribute your help file and register it in Visual Studio.

Merging Help files and integrating into Visual Studio Help

If you're building Html Help 2.0 output most likely your goal is to integrate your Help content into Visual Studio/MSDN content. Help 2.0 supports the concept of merging help files into a single comprehensive collection of help files.

Unfortunately this process is rather complex, badly documented and requires a number of support files that might not be available on your customer's machine where the merging needs to occur. If you go the Microsoft route you need to install about one meg's worth of support files and run several complex command line utilities to register and merge your help file. In addition there are licensing issues involved that require for these tools. We wouldn't recommend using this approach.

In order to facilitate the process I'll introduce you to a utility from the Far Technologies called H2Reg, which is a self contained application that can register Html Help 2.0 files, and merge them with other collections all from a single small Executable. This tool is free for personal use and fairly cheap for commercial use and well worth it if you need to deploy into VS.NET. You can install this EXE and an associated command file with your application and then have your installer run the Exe and script as an after install or uninstall action. H2Reg is FAR easier than distributing the MS Help runtime files as long as you are installing to a system where the viewer is already available (such as VS.NET developers).

The tool can register help collections for Html Help 2.0 as well as merge help collections into the Visual Studio collections with a single configuration file which Help Builder automatically generates for you.

What do you need?

Help Builder creates all the files necessary for a single Html Help 2.0 file and the files required for merging into Help 2.0 collections. It creates the HxS file, and the merge Collection files as well as the Command script to work with H2Reg. To distribute the Help File copy the following files:

(in this sample the project is called WebMonitor. Replace with your project name)

Help Builder generated:
WebMonitor.HxS
COL_WebMonitor.*
H2Reg.ini
Help20Register.bat

H2Reg Application files:
H2Reg.exe
H2Reg.ini

Copy all these files into your distribution directory so these files get installed with your Application perhaps in a Documentation folder.

The HxS file is the compiled Help 2.0 file. The COL_ files are the global collection merge files that you can use to merge the help file with another collection. The H2Reg.ini file contains the command script for H2Reg to merge into Visual Studio.NET 2003/2005. If you want to merge into a different collection you'll need to change the generated script here:

[Reg_Plugin]
;<nsName_Parent>|<HxT_Parent>|<nsName_Child>|<HxT_Child>|<HxA_Child>
MS.VSCC+|_DEFAULT|WestWindTechnologies.WebMonitor|_DEFAULT|COL_WebMonitor.HxA

and change the MS.VSCC+ to whatever the master namespace name to merge into is. You can find this out by viewing the content in the viewer and picking up the namespace from there.

Once all this in place you can now have your Installer fire a post install action to register the help file. To do this, simply run H2REG.EXE like this:

H2Reg.exe -r 

Make sure you copy and run H2Reg.exe in the same directory as the help collection files. To make this even easier there's a batch file Help20Register.bat that performs the above command line using H2Reg.exe. You can pass a -U switch to uninstall along the same lines.

The end result of all these steps is that you have your Help Project showing up inside of Visual Studio.NET.