Last update: 19-Nov-2006; Original: 19-Nov-2006
Programs like SandCastle, NDoc and HelpBuilder are tools used for creating MSDN-style documentation from .NET assemblies and their associated XML comments files.
Today I tried Microsoft SandCastle (currently in Beta). I used SandCastleBuilder as the GUI for SandCastle. It all went very smoothly once I had both items installed. First I went into my C# project's build properties and enabled XML documentation output. I compiled my project and observed the new XML file next to my usual output file. Next I ran SandCastleBuilder, selected my assembly (and its XML file), set the output to MS Help 2.x, and clicked Build.
The output was a single .HxS help file. Not very useful by itself. The user still needs to:
This stuff is not for the faint hearted. And it's also complicated by the need to deal with .MSI (Microsoft Installer).
Prior to Microsoft Help Integration Wizard, we wrote H2Reg.exe to provide a simple, intuitive, non-MSI solution for registering help collections. With H2Reg all you have to do is install your .HxS and collection level files in the usual fashion, then run H2Reg.exe to register / unregister the collection. An INI file containing H2Reg Script tells H2Reg what to do.
We still prefer to use H2Reg as do the many others who use it.
Background Reading:
If this all sounds very foreign then please do some background reading before continuing:
Our shareware utility FAR HTML has a collection wizard which creates the collection level files (that must be shipped with your .HxS file(s)). It also creates the a H2Reg Script file which tells H2Reg.exe what to register. All this stuff can be worked out from first principles. But why would you?
Let's walk through the wizard:
First open the H2 Collection Wizard from the FAR Authoring menu.
This .HxC file contains references to all other files. Enter any file name but use a .HxC file extension.
Add the .HxS help files generated by SandCastle.
Hierarchical simply allows you to specify a root TOC node to plug into. Good for grouping several help file titles together. If unsure select Flat.
Every collection is known by a text name. Like a handle. Give your namespace
a meaningful name.
Something like CompanyName.ProductName is good.
Far creates the extra files needed to ship with this collection. Our original .HxC is included in this list. You can edit the file names if you want to but usually there is no need.
The important thing here is to specify any namespaces we want to plug into. Here we will attempt to plug into any version of VS documentation we can find. At runtime H2Reg ignores any namespaces that don't exist.
The generated H2Reg Script will open so you can review it.
Like or not H2 documentation must be registered before it can be viewed.
Typically you would click H2Reg Import (this will invoke the H2Reg utility code
to run the Registration Script you just created). Once that's done you can click
View Collection to see how your collection looks.
Once the doc viewer is open, you can also open say MS.VSCC.V80 to see if your collection successfully plugged in or not.
The final screen lists the files created and how to install and register them.
