MS H2 Collection Tutorial by Rob Chandler (MS Help MVP)

New to MS Help collections? This demo and tutorial may be just what you need to get you going.

Last update: 1-July-2002; Original Upload: 12-June-2002

Download Demo Collection

Download the demo collection that accompanies this tutorial.

• Download TestPlugIn.zip

1. Introduction

I'll try and cover all the typical things that authors get stuck on: Adding Default and Home pages; Plugging into other collections; Project files versus Collection-level files. From time to time I will refer you to FAR. FAR is our H2 shareware utility and the only H2 Utility tool of its kind at the time of writing. FAR is available from http://helpware.net/FAR.

2. Project Files

Here are the demo project files that get compiled to the help file TestTitle.HxS:

This is about as far as MS Workshop gets you. It can take the above files and compile them to a compressed .HxS help file (Help Title). Workshop can also register the .HxS file as a collection so you can test it. But single .HxS based collections (the .HxS being both the Title and Collection file) are limited. This type of collection cannot plug into other collections, cannot host other collections as plug-ins, and cannot host other HxS Titles to form a multi-Title collection.

Most authors will be OK up to this point. It's pretty similar to an MS HTML Help 1.x project in many ways. Here are some extra notes:

2.1 HxC Project file

The HxC project file is a bit strange at first glance. It lists all the TOC, Index, Attribute files etc used:
 

... <AttributeDef File="TestTitle.HxA"/> <TOCDef File="TestTitle.HxT"/> <KeywordIndexDef File="TestTitle_NamedURL.HxK"/> <KeywordIndexDef File="TestTitle_F.HxK"/> <KeywordIndexDef File="TestTitle_K.HxK"/> ...

Then it assigns the files to Monikers. These Moniker Names and ProgIDs should never be altered unless you are intend to write your own help viewer. The InitData= defines the file associated with the Moniker. !DefaultTOC simply uses the TOC file name minus the file extension. But the Index files are more interesting. Here the InitData= specifies the Index indirectly by specifying the Index "Name" embedded in the Index file (Typically K, A, F and NamedURLIndex).

... <ItemMoniker Name="!DefaultFullTextSearch" ProgId="HxDs.HxFullTextSearch" InitData="FTS"/> <ItemMoniker Name="!DefaultTOC" ProgId="HxDs.HxHierarchy" InitData="TestTitle"/> <ItemMoniker Name="!DefaultKeywordIndex" ProgId="HxDs.HxIndex" InitData="K"/> <ItemMoniker Name="!DefaultNamedUrlIndex" ProgId="HxDs.HxIndex" InitData="NamedUrlIndex"/> <ItemMoniker Name="!DefaultAssociativeIndex" ProgId="HxDs.HxIndex" InitData="A"/> <ItemMoniker Name="!DefaultContextWindowIndex" ProgId="HxDs.HxIndex" InitData="F"/> ...

Within each index file header there is embedded a Name="K" or Name="A" etc. These Names can be changed if you also carefully change the HxC file references, and any other Index files that use the same Name. Get this wrong and your help will break. Here is the TestTitle_K.HxK file header:

<?xml version="1.0"?> <!DOCTYPE HelpIndex SYSTEM "MS-Help://hx/resources/HelpIndex.DTD"> <HelpIndex Name="K" Visible="Yes" DTDVersion="1.0" FileVersion="1.0" LangId="1033"> ...

 

2.2 HxT TOC File

In HTML Help 1.x each CHM Table Of Contents could include other table of contents files. This is not the case in MS Help 2. Typically it's only the Collection-Level TOC file (see below) that contains TOC include statements.
 

2.3 TestTitle_NamedURL.HxK

MS Help 2 stores all its special URLs such as DefaultPage and HomePage in yet another index file called the Named URL Index. Moniker = !DefaultNamedUrlIndex. You can edit this file in your Index Editor. Set the "DefaultPage" entry to the URL of the page initially displayed when help opens. Set the "HomePage" entry to the URL of the page to display when the home button is pressed. These are the 2 most common Named URLs authors will use. See your SDK help for more information on Named URLs.
 

2.4 HxF Include file

In MS Help 2 projects you must specify a list of all files you want included in the final HxS help file. This differs from HTML Help 1.x where the compiler would automatically include any file you linked to within a topic file. Typically you don't need to add Hx? project files to the HxF list. The HxF file is not required at the collection-level. Note that you are allowed to specify wild cards such as "html\*.htm" in the HxF include file.

 

3. Collection-Level Files

The next stage is to add the "collection-level" files. The syntax of these files is similar to the project files used to compile the .HxS help files. They define how the collection (all the Help Titles) hang together. Here are the demo "collection-level" files:

Some key points:

3.1 Shipping/Installation:

Ship ALL collection-level files as they are, uncompressed. Keep them together in the same folder. Ship also any .HxS Titles created in the previous section. These can be installed anywhere, they do not need to remain together. Authors however often do install the lot into the same folder. The registration of the files under a single Namespace, means that the system can pinpoint the location of any help title at any time. Just remember that if you move a file, you must re-register that file in its new location.
 

3.2 Registration Overview:

Once installed we must register the collection. Access to a collection is now via a "Namespace", and not via the file system as it was in HTML Help 1.x and WinHelp.  We register our Collection-Level HxC file to a unique label called a "Namespace" name. Then we register each HxS help file to the Namespace under a unique name called a "TitleID". The TitleID is typically the HxS file name minus the file extension.

The full path to a file in a collection is: ms-help://namespace/titleId/path/file.htm
 

3.3 HxT Collection-Level Table Of Contents:

The collection-level Table of Contents normally contains one or more include TOC statements. Each statement specifies a "TitleID" (the TitleID used to registering the HxS file under the namespace). At runtime the main TOC of the Title is included into the TOC. In the example below "TestTitle" is used since this is the label we use to identify the single HxS Title at registration time.

<?xml version="1.0"?>
<!DOCTYPE HelpTOC>
<HelpTOC DTDVersion="1.0" LangId="1033" PluginStyle="Hierarchical" PluginTitle="Test Plug-in Title 1">
<HelpTOCNode Title="Test Node1">
  <HelpTOCNode NodeType="TOC" Url="TestTitle"/></HelpTOCNode>
</HelpTOC>

 

Notice the PluginStyle="Hierarchical" (default value, alternatively you can set PluginStyle="Flat"). When set to Hierarchical the table of contents will contain a root tree node which contains all your TOC items. This root tree node is named by the PluginTitle= setting. These values are only used when we plug-in our collection to another collection. This root node acts like a folder for any child plug-ins. Experiment with using Flat or Hierarchical.
 

3.4 HxK Collection-Level Index Files:

The collection-level Index files typically contain no keywords at all. They are simply there to expose the project level Index files (embedded in the HxS Titles) at the collection level. Leave them out and you wont see your Keywords, HomePage URL etc. Embedded in the index file header is the index name. If you are having problems check this name is correct.
 

3.5 HxA Collection-Level Attribute Files:

These files typically are the same as Project HxA files but without the DTD reference. You do not need a collection-level HxA file if your HxS content is simply using attributes already defined in the parent collection (the collection you are plugged into), but if you want to define your own attributes to make custom filters then you definitely need one.
 

3.6 Do Not Add The DTD Refernence:    ** This is very important **

Collection-Level .Hx files must NOT contain a reference to a DTD file. DTDs are installed by VSHIK (H2 SDK/Workshop), so your customers probably wont have them on their machines. The DTDs should only be used in project files (which get compiled to a .HxS help file).  So please take care, a collection can test OK on your development machine, but break on your customers machine. A DTD reference in a collection-level file can cause the help collection to fail in some way (on machines that don't have the SDK DTDs installed), E.G. Default and Home Page may not work; Index and TOC may fail.
 

All Project files must have a DTD reference: <?xml version="1.0"?> <!DOCTYPE HelpIndex SYSTEM "ms-help://hx/resources/HelpIndex.DTD"> <HelpIndex Name="A" DTDVersion="1.0" Visible="Yes"> </HelpIndex> All Collection-Level files must not have  a DTD reference: <?xml version="1.0"?> <!DOCTYPE HelpIndex> <HelpIndex Name="A" DTDVersion="1.0" Visible="Yes"> </HelpIndex>

 

4. Registration

We now have our HxS Title and our collection level files. Next copy these files to the desired location and register them at that location.

We will now register the collection manually using the FAR Registration window. For registration on your customers PC you will normally use a registration tool like H2Reg (see http://helpware.net/mshelp2/h2reg.htm), or the Microsoft Installer (see MSI instructions in VSHIK documentation). Here we go:

1. Open the FAR Registration window (from H2 Utilities window or H2 Project Editor).
2. On the Namespace Page (page 1) enter the following:
   * Namespace: Enter Test123 as the name for our collection.
   * Description: Enter any descriptive text you like.
   * Collection File: Use the browse button next to the field and select our collection file "COL_Master.HxC".
3. Click the "Register" button.

We now have a Collection registered — let's add our single Title.

1. Open the FAR Registration window (from H2 Utilities window or H2 Project Editor) and select the namespace "Test123" from the first page.
2. Go to the Titles Page (page 2) click the "Add" button. The Add Help Title dialog will appear.
3. Click the File Browse button next to the Help File (HxS) entry field.
4. Select our compiled help file TestTitle.HxS.
5. Make sure the Title ID field says TestTitle.
6. Click OK to complete the addition of the Help Title to the Namespace.
7. If you want to add more Titles to the collection repeat steps 2-6.

5. View and Test the Collection

So we now have a collection "Tes123". Open it in the FAR built-in H2 Viewer and test it.

At this stage the most common problem is that the NamedURL Index may not work. If this is the case:

1. Check that the project TestTitle_NamedURL.HxK file contains valid DefaultPage and HomePage entries.
2. Check that you have a collection level NamedURL Index and that both Index files use the same Index name E.G. "NamedURLIndex".
3. In the FAR Viewer, open the Index navigation page. At the top of the Index list is a list of Index Monikers. Select "!DefaultNamedUrlIndex". If the list does not populate with items then you have made a mistake somewhere.

Note: The Named URL Index has no effect if you view a parent collection you have plugged into.

6. Plug-ins

Let's say you need to plug your collection into another existing collection. Typically this is the VS .NET collection or some other master collection. For VS .NET we need to plug into Namespace = "MS.VSCC". Here's how we manually plug our demo collection "Test123" into "MS.VSCC".

1. Open the FAR Registration window (from H2 Utilities window or H2 Project Editor).
2. Go to the Namespace Page (page 1) and select the parent collection to plug into. In this case "MS.VSCC".
3. Go to the Plug-ins Page (page 3) and click the "Add" button. The Add Child Plug-in dialog will appear.
4. From the 3rd field select the Child Namespace "Test123".
5. Leave the other fields and click OK to complete the Plug-in operation.

Open the Parent namespace (MS.VSCC) in the FAR H2 Viewer and check that the plug-in is working. Check that:

1. "Test123" TOC is visible in the Table of Contents navigation page.
2. "Test123" Index items are visible in the Index navigation page.
3. "Test123" search items appear in the Search navigation page.
4. "Test123" attributes are visible in the Edit > Filter dialog.

H2Reg Note: Notice there is a long delay the first time you open the updated parent collection. MS Help 2 is rebuilding its merged indexes and TOC files. You can force this rebuilding to happen at installation/Registration time. If you use the H2Reg utility you need to specify the -M switch. For MSI installs it automatically rebuilds these files if the collection is MS.VSCC otherwise it does not rebuild.

At this stage, many find that all is OK except #1, the Child TOC does not appear in the parent TOC. Or maybe the parent TOC has disappeared completely. Recheck your syntax, fix up any mistakes, unplug and reregister your collection and plug-in. You can open Hx? files in MS IE5/6 and IE will report any XML syntax errors.

7. Trouble Shooting

Child TOC or entire Parent TOC Missing?

1. Check the syntax - Use IE to check XML syntax.
2. Also try a fresh Namespace name - Some times while we experiment things muck up and a reboot or new NS name is required.

8. URLs

1. A full MS Help 2 URL looks similar to a web link. Here's the VS .NET Help Start Page:

     ms-help://MS.VSCC/vsccCommon/html/vsccCommon_Start_Page.htm

• ms-help - is the protocol. It tells the system that this is a MS Help 2 link.
• MS.VSCC - is the Namespace representing the VS .NET collection.
• vsccCommon - is a .HxS Title registered under the MS.VSCC Namespace.
• /html/... - is the path to a topic within the vscccommon.hxs help Title.

2. In our demo we just registered a Namespace "Test123" as a child (plugin) of MS.VSCC. Here's a URL to a page in Test123.

    ms-help://MS.VSCC/Test123/TestTitle/HTML/webpage1.htm

• Here the pattern is now ms-help://ParentNS/ChildNS/ChildTitle/Path

3. Can we have nested plug-ins? Yes we can.

Say we added a Child plug-in "Fred" with Title "FredTitle1" under our demo Namespace "Test123". It would show up in MS.VSCC with a URL like:

• ms-help://MS.VSCC/Test123/Fred/FredTitle/PathToTopic...
• ms-help://ParentNS/ChildNS/ChildOfChildNS/ChildOfChildTitle/PathToTopic...

4. More Links.

If you are creating a link within a Namespace topic then you can omit the ms-help: part. The same is true for MS HTML Help 1.x where you can drop the ms-its: prefix within a CHM help topic.

Here are some more link examples:

1. Relative path
   href="ms-help:html/topic.htm"  or  href="html/topic.htm"
2. Path from top level namespace root (//)
   href="ms-help://namespace/titleID_01/html/topic.htm"
3. Path from root of current compiled collection (/)
   href="ms-help:/titleID_01/html/topic.htm"  or  href="/titleID_01/html/topic.htm"
4. Path from root of current HxS Title_01 into adjacent HxS Title_02 (/../)
   href="ms-help:/../title_02/html/topic.htm"  or  href="/../title_02/html/topic.htm"
   
   #4 is handy given that you don't need to specify the Namespace to get into an adjacent HxS Title.

9. Links & Further Reading.

This has been a quick tour of making a collection. Read as much as you can. The VSHIK/Workshop documentation (Namespace = "MS.VSHIK") is a good place to start.

VS .NET Dynamic Help

Michael Waltuch from ESRI has written a great paper on:
"Setting up an H2 help project to work with Visual Studio .NET's Dynamic Help Window"

http://helpware.net/mshelp2/demo/DynamicHelp.htm

H2 Collection Registration Utility

H2Reg can register/unregister - collections/titles/filters/plug-ins all without the aid of MSI. Good news.

http://helpware.net/mshelp2/h2reg.htm

H2 Shareware Utilities - FAR

This shareware program is a must have for all MS Help 2 authors.

http://helpware.net/FAR/

Other Helpware Links

• MS Help 2 Information
• MS Help 2 Primer
• MS Help 2 FAQ

Helpware Home Page | Back to MS Help 2 Info Page | Contact us by email