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.
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.
Here are the demo project files that get compiled to the help file TestTitle.HxS:
|TestTitle.HxC||Main Project File - Contains references to all other project files.|
|TestTitle.HxF||Include File - Contains a list of files to compile into the target .HxS help file.|
|TestTitle.HxT||Table of Contents - Required if doing Plug-ins otherwise optional.|
|TestTitle.HxA||Attribute Defn File - Attributes are required if you want to make custom filters.|
|TestTitle_K.HxK||Keyword Index - Define your Index page entries.|
|TestTitle_A.HxK||Associated Index (optional).|
|TestTitle_F.HxK||Context Links Index (optional).|
|TestTitle_NamedURL.HxK||NamedURL Index - Defines the Home Page URL etc.|
|HTML\*.HTM||Some dummy topic files.|
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:
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. Note that FAR authoring will check this kind of mistake. Here is the TestTitle_K.HxK file header:
<!DOCTYPE HelpIndex SYSTEM "MS-Help://hx/resources/HelpIndex.DTD">
<HelpIndex Name="K" Visible="Yes" DTDVersion="1.0" FileVersion="1.0" LangId="1033">
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.
sent in this suggestion:
The collection-level NamedURLIndex is not optional if you want to launch your collection stand alone from the command line -- "C\Program Files\Common Files\Microsoft Shared\Help\dexplore.exe" /helpcol ms-help//MyCollection. In this case, you MUST have a collection-level NamedURLIndex for the proper start page to show up in the viewer.
Rob Chandler (Helpware):
Correct. If you are plugging your collection into MS.VSCC and only open your help collection via VSCC then forget about trying to define NamedURLIndex. But if you want to open your collection directly then create a NamedURLIndex so that you can define a DefaultPage and HomePage.
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:
|COL_Master.HxC||Main collection file contains references to all other collection-level files.|
|COL_Master.HxT||Table of Contents - This defines the master TOC and which Titles to include.|
|COL_Master.HxA||Attribute definition file.|
|COL_Master_K.HxK||Keyword Index- Name = "K".|
|COL_Master_A.HxK||A-Link Keyword Index - Name = "A" (optional).|
|COL_Master_F.HxK||Context Index - Name = "F" (optional).|
|COL_Master_NamedURL.HxK||NamedURL Index - Name = "NamedURL" (not required for plug-in).|
Some key points:
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
|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>
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:
We now have a Collection registered — let's add our single Title.
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:
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".
Open the Parent namespace (MS.VSCC) in the FAR H2 Viewer and check that the plug-in is working. Check that:
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?
1. A full MS Help 2 URL looks similar to a web link. Here's the VS .NET Help Start Page:
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.
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:
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:
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.
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"
H2Reg can register/unregister - collections/titles/filters/plug-ins all without the aid of MSI. Good news.
This shareware program is a must have for all MS Help 2 authors (if we do say so ourselves).