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.
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:
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:
- 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:
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:
- 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:
- Open the FAR Registration window (from H2 Utilities window or H2 Project
Editor).
- 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".
- Click the "Register" button.
We now have a Collection registered — let's add our single Title.
- Open the FAR Registration window (from H2 Utilities window or H2 Project
Editor) and select the namespace "Test123"
from the first page.
- Go to the Titles Page (page 2) click the "Add" button.
The Add Help Title dialog will appear.
- Click the File Browse button next to the Help File (HxS)
entry field.
- Select our compiled help file TestTitle.HxS.
- Make sure the Title ID field says TestTitle.
- Click OK to complete the addition of the Help Title to
the Namespace.
- 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:
- Check that the project TestTitle_NamedURL.HxK
file contains valid DefaultPage and HomePage entries.
- Check that you have a collection level NamedURL Index
and that both Index files use the same Index name E.G. "NamedURLIndex".
- 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".
- Open the FAR Registration window (from H2 Utilities window or H2 Project
Editor).
- Go to the Namespace Page (page 1) and select the parent
collection to plug into. In this case "MS.VSCC".
- Go to the Plug-ins Page (page 3) and click the "Add"
button. The Add Child Plug-in dialog will appear.
- From the 3rd field select the Child Namespace "Test123".
- 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:
- "Test123" TOC is visible in the Table of Contents
navigation page.
- "Test123" Index items are visible in the Index
navigation page.
- "Test123" search items appear in the Search navigation
page.
- "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?
- Check the syntax - Use IE to check XML syntax.
- 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:
- Relative path
href="ms-help:html/topic.htm" or href="html/topic.htm"
- Path from top level namespace root (//)
href="ms-help://namespace/titleID_01/html/topic.htm"
- Path from root of current compiled collection (/)
href="ms-help:/titleID_01/html/topic.htm" or href="/titleID_01/html/topic.htm"
- 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
Helpware Home Page |
Back to MS Help 2 Info Page
| Contact us by email