I love how the Visual Studio Document Explorer (help viewer) has a topic named "Help on Help". I've often wondered whether it should say "Help Upon Help", like there was several layers piled up on top of each other. Or how, if you can't figure out how to use the Help file, a help topic within it would be useful. Still, I suppose it's better than the old days when you had help items such as "The Range property sets or returns the range" and "To close the window, click the Close button".

But if your responsibilities include the creation of help sections for Document Explorer (as mine do on a regular basis), you'll know how fiddly it is to get the right stuff to appear in the right place, at the right time, and with a matching index. I suppose help-generation tools have never really been cutting edge, although there are some good third-party tools out there. And, of course, we have our own p&p Doc Tools to help us create the content. But it's the "massaging it all into a merge module" thing that has blood-boiling capabilities.

Of course, you can create Help files using Visual Studio itself - if you can figure out the instructions in the help file, or even find the appropriate section. Here's a clue: you'll need to install the Visual Studio SDK and then find the topic Visual Studio SDK | Visual Studio Development Environment SDK | User Interfaces | Help Authoring and Integration | Help Authoring | Getting Started with Help Content and Integration. I guess that shows how important help authoring actually is...

Anyway, as usual, I'm here to offer some useful nuggets of assistance (no laughing at the back please). Building a merge module for DocExplorer involves three stages: build the HxS and associated content files (TOC, index, etc.), use the VS Help Integration Wizard to compile these files into a merge module, and then test the merge module in DocExplorer by using a VS Setup project to install it. In our case, the p&p Doc Tools create the HxS and the other input files, though you can do this using other tools. Where I encountered problems was the conversion into a merge module.

The issue is that, as the dev team builds stuff, they like to do regular CTP releases so that people can see where they are going and provide feedback (and, dare I venture to say, help them find the bugs). So our help docs get compiled into merge modules at regular stages. Each release has to have the correct headers, release dates, pre-release text, and internal namespace (each merge module is identified by a unique namespace). These details are specified in a combination of ways in both the input HxS files and in the VS merge module project.

To build the merge module, you run the VS Help Integration Wizard. It collects all the information it needs to build a "plug-in node" (the root node of the set of help files in the Doc Explorer TOC), and then assembles all the files so that VS will merge the contents correctly into the existing sections of DocExplorer. The problem is that, despite spending many hours on many occasions searching, I can't find any way to re-run the Wizard when I want to change the settings.

So, I thought, no problem. The input files are mainly XML so I can edit them. However, Windows is clever. I naively assumed that searching from Windows Explorer for files containing the text I wanted (such as the release date) would locate all the files I needed to edit. What I forgot was that the search feature only searches the contents of file types it knows about. Give it a mass of files with extensions like HxF and HxK and it simply turns its nose up in a kind of "you don't really expect me to look inside there, do you?" way. So I never could figure which files I needed to edit.

But then, with the latest project, I decided I was going to solve the problem and used a "proper" search tool (actually TextPad, but don't tell anybody). Bingo! (or "Eureka" if you are posh). After some experimentation I'd found all the places that you need to change stuff. After that, I recompiled the merge module, recompiled the setup project, installed the merge module into Doc Explorer, and it worked. No need to nuke the merge module and setup projects and start over each time. Here's some pointers that might help:

• To change the text of the "plug-in node" that appears in the list of installed technologies in DocExplorer, edit the PluginTitle attribute of the HelpTOC element in the _TOC_xxx.HxT file in the CollectionFiles subfolder of the project (the full name of the file includes some kind of project-specific GUID).

   

• To change the title of the document set, edit the Title attribute of the HelpCollection element in the _Collection_xxx.HxC file in the CollectionFiles subfolder of the project.

   

• To change the namespace for the document set, edit the content of the Namespace element in the IntegrationWizard.xml file in the CollectionFiles subfolder of the project.

   

• To change the description of the document set, edit the content of the Description element in the IntegrationWizard.xml file in the CollectionFiles subfolder of the project.

   

• The Filters element at the bottom of the IntegrationWizard.xml file specifies the filters you define in the Integration Wizard. These allow users to filter all of the DocExplorer content using the drop-down list of installed products and technologies. All of the pages in the HxS should have a DocSet specified in the form:
  <MSHelp:Attr Name="DocSet" Value="MyCTP1Docs" />
  If you changed the DocSet name, edit the Query child element of the Filter element to specify this, for example:
  <Query>"DocSet"="MyCTP1Docs"</Query>
  To change the description for this filter, edit the content of the Description child element of the Filter element.

   

• To open your help file from a shortcut or code in an application, you use the rather convoluted shortcut path such as this:
  "%CommonProgramFiles%\Microsoft Shared\Help 9\dexplore.exe" /helpcol ms-help://MS.VSCC.v90/MS.VSIPCC.v90/[your-docset-namespace] /LaunchFKeywordTopic [keyword-in-target-page] /filter "your-filter-description"
  
  • The [your-docset-namespace] value is the one you specified in the Namespace element in the IntegrationWizard.xml file.
  • The [keyword-in-target-page] value is the value of the Term attribute of an MSHelp:Keyword "F" keyword element in the source page that you want to display, such as:
    <MSHelp:Keyword Index="F" Term="mycompany.myproject.yearmonth.introduction" />
  • The "your-filter-description" value is the value you used in the Description child element of the Filter element in the IntegrationWizard.xml file.

As a side note, when you do test installs of merge modules, I'd sincerely recommend using a VPC with Visual Studio installed, but not much else. The merge process happens automatically when you open DocExplorer after installing a new merge module, and it can take ages if you have lots of other merge modules (lots of help topics from lots of other installed products). Using a VPC means you can test the installation, then abandon (delete) the changes to the VPC so you don't have to uninstall the merge module again.

If you don't use a VPC, remember to open DocExplorer and then close it again before you install the merge module to ensure that there are no other merge changes pending. And after you uninstall a merge module, make sure you open DocExplorer again to let it sort itself out - it remerges all the remaining content again. If you uninstall and then reinstall a merge module without allowing it to remerge, you may well see the old module content instead of the new content unless you changed the namespace in between.

Or just give users the original Word documents and let them print out their own help file...