H2 Primer

This document is designed as a quick introduction to MS Help 2, the new help engine from Microsoft used by VS .NET, MSDN, Borland C# Builder etc.

About MS Help 2

• See the VS SDK Help documentation.
• See the Helpware H2 FAQ

General Info

• MS Help 2 is a completely new help system. New file extensions. New API DLLs.
• MS Help 2 requires a minimum of MS IE5.0 because of its XML requirement.
• Like MS HTML Help 1.x before it, MS Help 2 uses HTML topics, TOC, Index, Search, Favorites, as well as KLinks & ALinks.
• MS Help 2 can have multiple indexes. Think of an index as a list of Name-Value pairs. These lists are static in that they are set at compile time.
• MS Help 2 Data Services allow you to interface with the help file data via COM interfaces (not published by MS).
• Some MS HTML Help 1.x features may not have been implemented in MS Help 2. Note however you can use a mixture of HTML Help 1.x and MS Help 2 in your projects. Remember that some features such as HH 1.x Shortcuts will not work outside of a CHM.
• MS provide a conversion tool HxConv.exe which does a good job of converting .CHM or .HHP over to a MS Help 2 project.
• The compiler no longer strips info from source files. And round trip compiles mean that when you decompile a HxS file you get all the original source files back, including the .HxC project file.
• You must specify the exact list of files to be compiled into target .HxS help file, unlike HH 1.x which could crawl hyper-links to find files. The H2 file list is kept in a .HxF file and may contain wild cards such as "*.htm" and "images\*.gif".
• No more confusion over Binary or Non-binary TOCs and Indexes. They are always stored in the help file as binary.
• MS Help 2 collections can be very big. Bigger than MS HTML Help 1.x merged document sets.
• MS Help 2 dynamic filters work on TOC, Index and Search items, and even right down to the paragraph level in a topic file (with some help of JScript). Filters are based on topic attributes embedded in each topic.

Registration

Each MS Help 2 collection must be registered before it can be viewed. Registration simply means giving each collection a unique name (text label). This name is called a "Namespace". An MS Help collection path now starts with a Namespace, not a disk directory path as with MS HH 1.x. This fixes some problems, but creates some new problems. You can no longer move or install a help system without registering. An unregistered help system is useless since you cannot view it.

There are two types of collections. Collections that contain just a single .HxS help file, and collections that contain one or more .HxS help files plus a number of uncompiled collection-level files. In the first case, the single .HxS help file is registered under a namespace name and a single help title is added, itself. In the second case, a .HxC collection-level file is registered under a namespace then all .HxS help files making up the collection are registered as Titles under that namespace.

But isn't the .HxC file, the MS Help project file used to build .HxS help files? Yes, it can be both. As a project file it contains information about how to build a .HxS help file. The equivalent in HH 1.x is the .HHP file. The .HxC project file is needed at build time only. The HxC collection-level file defines how all the help files merge at run-time and must be shipped to the customer with the other HxS compiled help files.

Because a collection is now accessed via its Namespace, URLs are now location independent. Thus we can install software on different machines, to different folders, and the same topic URL will work on all machines -- as long as we register each collection using the same Namespace and TitleID(s).

Warning - DTD Files: Note that only HxC project files should contain an XML reference to a DTD file. The DTD file validates the XML syntax at compile time. DTD files are part of the Workshop installation (not the runtime), so it is very important NOT to include a DTD reference in the collection-level files. If this is done your collection would run OK on your development machine, but produce errors on your customers machines.

MS Help URLs

An absolute path to a topic looks like this:

ms-help://namespace/TitleId/internalpath/topic.htm

It looks more like a web URL. After the MS Help protocol " ms-help://" the namespace identifies the collection we want to access. Next the "TitleId" identifies the help file in the collection. The rest of the path is the internal path to the topic in the help file. The rules are similar to those in HH 1.x which used something like ms-its:path\help.chm::/internalpath/topic.htm. To link to a file topic2.htm in the same internal folder requires a normal relative link <a href="topic2.htm"> click me</a>. Also, absolute paths such as ms-help://.. , are understood by Internet Explorer, just as HH 1.x absolute paths were (eg. ms-its:c:\path\file.chm::/path/topic.htm).

There are 2 stages to registering a MS Help collection:

1) Register the Collection (.HxS or .HxC) file under a unique Namespace (some text label).

2) Register one or more help (.HxS) files to the collection. Each help file must be registered under a unique TitleID (some text label). HxS based collections can only contain a single title (itself).

In the case of a single help file collection, the Namespace and TitleID are often the same.

EG. Help file testhelp.HxS may have a URL ms-help://testhelp/testhelp/file.htm

Here's an interesting example (below). The single slash, takes us to the top of the Help Title (Compiled HxS help file), while the "../fileid" then takes us up and over into an adjacent Help Title called "MyTitle". In this way our internal relative links can be made independent of the Namespace name.

EG. ms-help:/../MyTitle/internalpath/topic.htm

Plug-ins

MS Help 2 also offers a "Plug-in" feature. Here your namespace (a HxC based collection) can be plugged into a Parent namespace (such as MS.VSCC or BORLAND.BDS). If done correctly the plug-in integrates fully with the parent collection -- TOC, Index, Attributes, Filters and Full-text search information.

The full URL for reaching a plug-in is slightly different. Both Parent and Child namespace names must be used in the path.

EG. ms-help://nsParent/nsChild/Childfileid/Childinternalpath/topic.htm

EG. ms-help://MS.VSCC/hw.h2reg/h2reg/html/index.htm

Note: HxS based collections can not be plugged into and cannot plug into other collections.

MS Help 2 Project Files

The following files can be compiled to a .HxS binary help file by compiling the .HxC file:

MS Help 2 Shipped Files

Collection-level XML files do not contain DTD statements and must be shipped uncompressed with the .HxS help files. HxF files are not shipped.

• HxC - The main XML collection-level file containing info about the entire collection. This is registered to a Namespace name.
• HxT - XML collection-level file. This Table Of Contents file contains a list of TitleIds. These Ids are the same ones used to register each help file under the Namespace. This is the way each Help file's TOC is merged at runtime.
• HxK - XML collection-level Index files are normally empty of index entries. This sounds useless, however their presence exposes the Index entries at the collection level (and to any collection plugged into).
• HxA - Defines the topic attributes you want made visible at the collection level (and any collection plugged into). Note that if you plug into say MS.VSCC then there is no point in redefining attributes already defined in the MS.VSCC collection.
• HxR/HxQ - These binary files contain combined index and search terms used to speed up data access. See VSHIK documentation for more info.
• HxS/HxI - One or more binary Help file titles are registered under the Namespace. Optionally (a compiler setting) you may ship a separate .HxI Index files (normally stored within the HxS help file).

As stated above it is possible to ship a single .HxS file collection. However this type of collection cannot plug into Microsoft or Borland collections. Borland may allow you to directly register your .HxS help title directly into a Borland collection. However I do not recommend this. Microsoft do not allow this at all.

File Extension Comparisons