MS Help 2 Primer

About MS Help 2
General Info
MS Help 2 Project Files
MS help 2 Shipped Files
File Extension Comparisons

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
General Info

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:

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


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:

HxC Collection Definition File Identifies all other key files and compiler options.
Defines navigation data monikers.
HxF Include File Lists all files to be included in the compiled HxS help file. Supports *.*, *.HTM, *.HTML type syntax.
HxT TOC Definition File Table of contents definition file.
HxK Index Defn File (Internal Name=K) KLinks. Keyword Index appear in the viewers Index navigation control. Typically named "K".
HxK Index Defn File (Internal Name=A) ALinks. Associative keywords. Typically named "A".
HxK Index Defn File (Internal Name=NamedURLIndex) The Named URL Index defines URLs for the HomePage, DefaultPage etc. Typically named "NamedURLIndex".
HxK Index Defn File (Name=F) The Context window Index contains a list of help mappings as Keyword-URL pairs. Typically named "F".
HxE Sample Definition File Optional file for defining samples.
HxV Virtual Topic Definition File(s) Virtual topic feature provides a way to treat any URL (web, pdf, image etc) as a first class help topic.
HxA Attribute Definition File Defines topic attributes and filter definitions. MS suggest a you omit this file. Doing so will cause all attributes defined in topic file headers to be enabled.
  Other Topic files, images, CSS etc Your help content files.
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.

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
MS Help 2.x HTML Help 1.x WinHelp Description
.HxC (XML) .hhp/.col (INI) .hpj Project file / Collection file.
.HxS/.HxI .chm/.chi .hlp Compiled help file. HxI is normally inside the HxS help file but can be compiled as a separate file for CDROM disks.
.HxT (XML) .hhc (Sitemap) .cnt Table Of Contents file. 
.HxK (XML) .hhk (Sitemap) --- Index file. H2 may have multiple indexes.
HTML HTML RTF WinHelp was RTF based. 
DExplore.exe hh.exe winhelp.exe Default Help viewer.
hxcomp.exe hhc.exe hcrtf.exe Command line compiler.
Help 2.x collections Merged CHMs or MSDN collections Yes Modular Help
Topic attribute filters Info Types
(did nor work)
No Content filtering.
Data services No No H2 has programmatic access to data via COM
(documentation not released by MS).
<mshelp:keyword> <object> or <meta> -- Help 2 now uses XML elements instead of object and Meta tags.
<mshelp:link> <object> -- Help 2 now uses XML links instead of objects.