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.

Original Upload: 12-June-2002

Last update: 6-Nov-2002; Add a note to Section 7 from Cathy Kerr

Download the demo collection that accompanies this tutorial.

• Download TestPlugIn.zip

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 FAR Product page.

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:

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").

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. Note that FAR authoring will check this kind of mistake. Here is the TestTitle_K.HxK file header:

Notice that line 2 contain a reference to an XML DTD file. It defines the syntax/structure of the Hx XML file. For Index type files we use "HelpIndex.DTD". The DTD files are stored in the Hx collection, which is only available on PCs with VSHIK installed. So don't use DTDs in your collection level files (see below), since your customers wont have VSHIK installed.

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.

2.5 HxA Attribute file

Topic attributes are defined between the <xml></xml> tags in each topic file header (do a View Source on any MS topic file). Note that you don't actually need a project level HxA file. I have included one with this demo but it is unnecessary according to the MS Help team. You do however need a collection level HxA (see below) if you want to expose these attributes to your HxC based collection or to a parent collection you are plugging into.

See Also MS Help 2 Attributes.

The next stage is to add the "collection-level" files. These files are shipped uncompressed with your HxS help titles. 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 and registered anywhere, they do not need to remain together. Authors however often do install the lot into the same folder. 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 name we used to identify the single HxS Title at registration time (Note that the VSHIK documentation is incorrect).

<?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 orHierarchical.

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:

The collection-level attribute files define all attributes used in your collection and expose your attributes (defined above) at the collection level. When you plug into a parent collection, such as ms.vscc, the parent will then see these attributes. Note that 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 Reference: ** 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. Plugging into another collection fails. Default and Home Page may not work; Index and TOC may not show;

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 Product H2Reg), 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:
3. * Namespace: Enter Test123 as the name for our collection.
4. * Description: Enter any descriptive text you like.
5. * Collection File: Use the browse button next to the field and select our collection file "COL_Master.HxC".
6. 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.

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: Your Named URL Index has no effect if you view a parent collection you have plugged into.

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" (MS.VSCC.2003 for VS .NET 2003). 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 (above), 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.

Child TOC or entire Parent TOC Missing?

• Check the Hx file syntax using IE - IE can display XML files.
• Also try a fresh Namespace name - Some times while we experiment things muck up and a reboot or new NS name is required.
• Before registering with MSI, try registering manually using FAR or H2Reg.
• Check that the TOC Include statements (in the collection level HxT file) are using the correct TitleIds (the ones used to register your HxS Titles).
• If the TOC shows on your development machine but not on others, then make sure the collection-level Hx files do not contain DTD references (see above)
• Lastly check your Hx file syntax very carefully against a working collection (eg. this tutorial's demo collection).

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

5. XLinks

When linking to topics in 3rd party collections use XLinks (See your VSHIK documentation). Most MS collection topics are given an ALink-Keyword. It's safer to link to MS topics using XLinks than using URLs (which change over time). This is in fact what MS themselves do. You will find the Keyword declaration embedded in the XML data island of the topic's header.

This has been a quick tour of creating a collection. Read as much as you can. The VSHIK/Workshop documentation (Namespace = "MS.VSHIK" or "MS.VSHIK.2003") 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"

H2 Dynamic Help

H2 Collection Registration Utility

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

H2Reg

H2 Shareware Utilities - FAR

This shareware program is a must have for all MS Help 2 authors (if we do say so ourselves).

FAR HTML

Other Helpware Links

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