Integrate Custom Help Into MSDEV

Preface

This document describes how to integrate custom help content into the Microsoft Visual Studio (called MSDEV below) Help System.

The most interesting use case for this is to integrate OpenOffice.org source code documentation, or the OpenOffice.org IDL reference, into MSDEV.

Note that I did not investigate the matter to an end, I stopped when I saw the help collection in MSDEV, and successfully queries an identifier from the source code by pressing F1. So, I don't know whethere there are any pitfalls still waiting, and the document describes only what I found so far. However, results are quite promising ...

Prerequisites

General

• Microsoft Visual Studio .NET. Everything below is tested with the 2003-version
• Visual Studio .NET Help Integration Kit 2003 (free download)

Optional

If you plan to let doxygen generate your Compressed Help Files (.chm), then you need

• HTML Help Workshop (free download)
• doxygen itself, of course

Creating the Compressed Help File

If your documentation is already exists in Microsoft Help 1.x format (that is, as a .chm file), you can probably this step.

In your doxygen configuration file, ensure that

• GENERATE_HTMLHELP is set to YES
• CHM_FILE has a value of somename.chm
• GENERATE_CHI is set to YES
• HHC_LOCATION points to the hhc.exe from the HTML Help Workshop, if it's not in your path (and also not in your HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\App Paths registry branch).

Run doxygen with those options (and all other options as you prefer them). This should, amongst a heap of HTML files, create a .chm file with a .chi file besides.

Converting the Help 1.x to a Help 2.0 project

If you have a .chm file, then this is a "Microsoft Help 1.x" format so far. For the next steps, you need a "Microsoft Help 2.0" project, which basically is a bunch of XML files with various extensions, describing the help content and structure.

For everything below, we'll assume that your files are named MyHelp.chm and MyHelp.chi

Locate the hxconv.exe from the "Visual Studio .NET Help Integration Kit 2003". Note that the installation routine of this kit did not only create a "VSHIK 2003" directory, but also (silently) a "Microsoft Help 2.0 SDK" (both usually in C:\Program Files). You find hxconv.exe in the latter directory.

Run

 hxconv -o MyHelp MyHelp.chm

This will create a sub-folder MyHelp, where MyHelp.chm has been extracted, plus some additional files.

Compiling the Help Title

The next conversion step is to create some more *.Hx? files (the previous step already created some of them).

Locate hxcomp.exe, also from the "Microsoft Help 2.0 SDK" directory. Change to the MyHelp sub-folder created in the previous step, and run

 hxcomp -p MyHelp.HxC -l logfile.txt

Here, -p MyHelp.HxC specifies the help project file to compile, and -l logfile simply specifies a file to log the processing.

Note that this step might take a while ...

Creating a new Help Collection

Create a new text file MyCollection.HxC with the following content:

 <?xml version="1.0" encoding="utf-8" ?>
 <!DOCTYPE HelpCollection>
 <HelpCollection DTDVersion="1.0" FileVersion="1.0.0.0" LangId="1033" Title="My Help Collection Title">
   <TOCDef File="MyCollection.HxT" />
   <KeywordIndexDef File="MyCollection.HxK" />
   <ItemMoniker Name="!DefaultToc" ProgId="HxDs.HxHierarchy" InitData="" />
   <ItemMoniker Name="!DefaultFullTextSearch" ProgId="HxDs.HxFullTextSearch" InitData="" />
   <ItemMoniker Name="!DefaultKeywordIndex" ProgId="HxDs.HxIndex" InitData="K" />
   <ItemMoniker Name="!DefaultAssociativeIndex" ProgId="HxDs.HxIndex" InitData="A" />
   <ItemMoniker Name="!DefaultContextWindowIndex" ProgId="HxDs.HxIndex" InitData="F" />
 </HelpCollection>

Notes:

• Not sure what the Title attribute is good for here. Didn't find any place where it's visible.

This will be the root file of your new Help Collection. It refers to a table-of-content file MyCollection.HxT, which you also have to newly create:

 <?xml version="1.0" encoding="utf-8" ?>
 <!DOCTYPE HelpTOC>
 <HelpTOC DTDVersion="1.0" PluginStyle="Hierarchical" PluginTitle="My Help Collection Title">
   <HelpTOCNode NodeType="TOC" Url="MyHelpTitle"/>
 </HelpTOC>

Notes:

• the PluginTitle attribute specifies the title of the help collection in MSDEV, so make it human-readable and -understandable
• MyHelpTitle can be chosen arbitrarily (it's not user-visible), and is referred to in a next step

Also, the MyCollection.HxC above talks about a MyCollection.HxK, so create it, too:

 <?xml version="1.0" encoding="utf-8" ?>
 <!DOCTYPE HelpIndex>
 <HelpIndex DTDVersion = "1.0"
   Name = "K"
   Title="K-Keyword Index"
   Visible="Yes"
   LangId="1033">
 </HelpIndex>

Notes:

• not sure at all what this is good for ...

Registering the Help Collection & Help Title

Now, you need to register the previously created help collection.

Locate the hxreg.exe, again from the "Microsoft Help 2.0 SDK" directory. Run

 hxreg -n MyHelpNamespace -d "My Very Private Help Namespace" -c MyCollection.HxC

This creates a Help Collection namespace "MyHelp", with the detailed description "My Very Private Help Namespace", from the MyHelp.HxC help collection.

Notes:

• the description (passed with the -d switch) is pretty irrelevant here. It's not visible to the user.
• the namespace (passed with the -n switch) must be globally unique. org.openoffice might be reasobale here if you're going to create OpenOffice.org-related documentation
• the collection you specify here (the -n switch) is the MyCollection.HxC you created in the previous step, not the MyHelp.HxC. Don't confuse this.

Now, you have a new Help Collection, but not any content, yet. Run

 hxreg -n MyHelpNamespace -i MyHelpTitle -s MyHelp.HxS -x MyHelp.HxI

Notes:

• the title ID (passed with the -i switch must be exactly the same as the URL parameter of the HelpTOCNode element in the HelpCollection.HxT file.
• If you don't have a MyHelp.HxI file, then you probably did not start with both a .chm and a .chi, but only with a .chm which had intern index information. In this case, re-run doxygen with the GENERATE_CHI option set to YES, or de-compile and re-compile your .chm file, and re-compile it with the after you added

 [OPTIONS]
 Create CHI file=YES

to the respective Help 1.x Project File (.hhp). Thinking more about it ... it might be that you do not need the HxI file. Try just omitting the -x parameter, and report whether it works ...

Verify the Installation

To verify that the installation of your help collection was successfull, re-start MSDEV, and choose Help|Contents from the menu. This should rebuild the help index (might take a while), and then show you your new help collection ...

You can now use the content from this collection in the usual way. In particular, you can place the cursor on an identifier in your source code, press F1, and jump directly to the respective help (if there is any) ... Pretty cool, isn't it?

Trouble Shooting

In case the new help didn't materialize in MSDEV: Try namespace.exe from the Unsupported Tools sub folder of the Help SDK. It gives you a graphical overview about registered help collections, so you can compare the data of your own (not-working) collection with the one for other collections - perhaps this gives you a clue.

Also, try entering ms-help://MS.VSCC.2003/VSCCCommon/cm/CollectionManager.htm in an (Internet )Explorer instance of your choice. This gives you a UI for the Help Collection Manager. Check whether your new collection appears there, and if it's enabled (checked). If not, enable it. If this fails, check whether your system has read access to the location where your help collection is stored.

Sometimes, it happened to me that I needed to deactivate my newly registered collection, and activate it again, before it became accepted in MSDEV. De/Activation is done in the CollectionManager (URL see above), so you might want to try this, too.

Precompiled UNOIDL reference help files for OpenOffice.org 2.0.2

A set of precompiled UNOIDL reference help files for OpenOffice.org 2.0.2 can be found in the file section on api.openoffice.org.

Simply download the file OpenOffice.org2.0.2_API_Reference_Manual.zip extract it anywhere and call the register.cmd. You will need hxreg.exe from the "Microsoft Help 2.0 SDK" to register the help files.

References

• Visual Studio .NET Help Integration Kit 2003
• HTML Help Workshop
• doxygen
• Integrating Symbian Help in Visual Studio .NET by Antony Pranata