MS Help 2.x‎ > ‎

H2 & Borland Help

by Robert Chandler (MS Help MVP) 

Original - 2-Nov-2003
Last updated 24-Apr-2004


Introduction

Borand .NET Help / Embarcadero Rad Studio Help, is the same help used by VS 2002/2003/2005/2008. That is MS Help 2.x  Many of us know how to integrate into Visual Studio help collection but not into Rad Studio help. Lost already then please see the Basics section below. This document is primarily aimed at vendors who need to integrate their help into BORLAND.BDS, the documentation namespace for the Borland C# Builder collection, but it also covers MS Help 2 collections in general.

If you find information missing in this article please Contact me. 
(Actually this document is quite old now and better help should be found on the Embarcadero web site).

H20 Basics

New to Microsoft Help 2.x? These links will bring you up to speed.

Throughout this document we will be referring to our shareware application FAR HTML. It contains a variety of HTML, HTML Help 1.x and MS Help 2.x time saving tools including wizards that take all the guess work out of creating .HxS help & collection files.

Overview of Help Registration & Help Integration

1. HxC based collections & Plug-in

The collection-level uncompressed .HxC file is registered to a Namespace name. One or more help titles are then registered to that Namespace, each under a unique TitleID. This collection known by its Namespace name is then "Plugged Into" a host collection.
Pros:
  • The "Plug-in" feature merges a collection seamlessly into a host (parent) collection.
  • Microsoft recommends using the "Plug-in" feature as a safe way to integrate content into a 3rd party collection.
  • Plug-ins are easily installed and uninstalled.
  • Plug-ins can be nested several layers deep.
  • Choice of two plug-in TOC styles: 
    Flat: Each title's TOC is inserted at level 1 of the parent collection's TOC.
    Hierarchical: Specify a base node which is inserted at level 1 of the parent collection's TOC. Each title's TOC is nested into that node.
 Cons:
  • Collection-level files are extra work to set up.
  • Plug-in TOCs cannot be ordered. Basically it's first to plug-in gets first place in the parent TOC's hierarchy.
  • Plug-ins require a special path when dealing with full paths: 
    ms-help://parentNS/ChildNS/ChildTitleId/Path/topic.htm

2. Single HxS based collections - No Integration

The single .HxS help file is both the collection file (registered to a Namespace name) and the help Title (registered to the Namespace under a TitleID). No other titles may be added. This type of collection cannot be plugged into and cannot plug into another collection.
Pros:
  • Good for simple standalone collections that contains a single .HxS help file.
  • Good for quickly testing a single help file.
 Cons:
  • This type of collection cannot be plugged into and cannot plug into other collections.

3. Add HxS Title - Not Recommended

Register your .HxS help file title directly under someone else's Namespace (collection).
Pros:
  • Last time I checked Borland did in fact support this as a valid method of integrating 3rd party help into a Borland collection. They term they used for this type of integration was "Merging".

    At the time of writing I do not know if Borland will release a tool to safely "Merge" HxS files into the Borland.BDS
 Cons:
  • Microsoft do not recommend this as a way to integrate 3rd party help.
  • The Host collection-level HxT TOC definition file must be modified to integrate a TOC. Risk of corrupting the host collection.
  • The Host collection-level HxA Attribute definition file must modified to integrate attributes. Risk of corrupting the host collection.

I strongly recommend you integrate help using the "Plug-in" method (option 1).

Collection-level files

Using option 1 above we need to create several collection-level files to ship with our .HxS help files. They define our collection and how our collection will behave when plugged into another collection (typically MS.VSCC orBORLAND.BDS).

For detailed information please see:

  • MS H2 Collection Tutorial - A full tutorial with demo collection you can download.
  • See your Help Integration Kit (Help SDK) documentation for detailed help and file formats.

If you are creating help for Visual Studio .NET you need to look into using Dynamic help. Fortunately Borland does not support dynamic help (yet?) which makes help integration much easier.

The job of creating help files and collection-level files has become very simple with the latest release of FAR HTML Version 3.6. A Wizard guides you step by step in creating help files. Another FAR Wizard now creates the collection-levels files, generates H2Reg registration script, tests the collection, and displays shipping instructions for you.

April-2003: MS have just released a Wizard that creates collection-level files and helps you create MSI registration information.

Installing and Registering your Collection

Collections can be manually registered using tools such as Namespace.exe, HxREG.exe (both free with MS VSHIK) and 3rd with party authoring tools such as FAR HTML. This is OK for testing on the development machine but when it comes to distributing and registering your collection the choices are quite limited.

MSI - Microsoft Installer Solution

Using MSI to install and register is explained in the Help 2 SDK documentation. The MSI files required for integrating into MS.VSCC are part of the VSHIK / Help SDK download. Note that the VSHIK 2002 (2.1), VSHIK 2003 (2.2) and Help SDK (2.5 - comes with VS SDK) can all coexist on the same machine. Unfortunately you cannot create a single installation that will cover plugging into more than one VS collection - MS.VSCC, MS.VSCC.2003 etc. Possibly those with a good knowledge of MSI can get around this limitation.

Installation and registration via MSI is complex if you don't know much about MSI. However it is free so maybe worth persevering with.

The other downside of MSI is you can not use it to plug into a non-Microsoft collection. Again maybe an MSI expert can get around this somehow.

April-2003: MS have just released a Wizard that creates collection-level files and helps you create MSI registration information.

H2Reg.exe - Flexible Shareware Solution by Helpware

H2Reg is a proven reliable way to register/unregister collection, titles, filters and plug-ins without the need for MSI. H2Reg.exe is a small executable you use to extend your installation program. FAR HTML can generate (export) and execute (import) H2Reg registration script. The script itself is relatively simple if you understand how Help 2 registration works. A prime example of using H2Reg.exe is seen in the Borland.BDS (Borland C# Builder) collection where ComponentOne have used H2Reg to register all there component documentation.

H2Reg is very flexible in that it supports special wildchars. Example: MS.VSCC+ means MS.VSCC & MS.VSCC.2003 etc. Thus you can target multiple namespaces to plug into. Targets not found are ignored. The H2Reg verbose log file provides ample feedback for developers debugging complex setups. See the H2Reg home page for more information.

 

Borland Delphi 8 Solution

May 28, 2004

Borland have released there own method of registering collections. It involves using MS Script control which exposes some aspects of the H2 API.

Borland C# Builder help

Like VS .NET's help, Borland's C# Builder's help is written in MS Help 2. This section talks about how to integrating your own MS Help 2 content into the C# Builder help. Unlike VS .NET, Borland C# Builder does not provide dynamic help (an embedded VS help pane that dynamically updates according to the current focus). So Borland help is somewhat simpler. Like VS .NET help, C# Builder displays its help collection in DExplore (DExplore.exe is the MS help 2 standard help viewer). Integrating help into the C# Builder's collection mostly involves setting up keyword search entries in the "A" and "F" keyword Indexes.

Don't confuse Help 2 (.HxS) with HTML Help 1.x (.CHM). Some developers think that standalone .NET applications (they create) can use MS Help 2 for their online help. There was a time when MS Help 2 was slated to become the next help system used by all application help. Unfortunately it was canned and now MS Help 2 is used only by applications such as VS .NET, MSDN, Technet, .NET Framework SDK, Office Developer and now Borland's C# Builder.

How help is accessed from different parts of the C# Builder IDE. Thanks to Borland in advanced for helping with much of this section.

1. Help from the Code Editor

When F1 is pressed help searches the "A" and "F" Indexes for a keyword match.

Tip: If the cursor is positioned on a fully-qualified name (e.g., "Borland.Data.Provider.BdpCommand"), Help is searched ONLY for the portion of the name on which the cursor rests. Help searched for the full class name ONLY if the entire string is highlighted.

Thus, your HTM files should contain target keywords for at least the fully-qualified names of your classes and properties.

Here is the XML data Island from ms-help://borland.bds/csbapi/html/BorlandDataProviderBdpCommandClass.htm.
It's set up to trap any variation in search strings for the BdpCommand class:

<xml>
<MSHelp:TOCTitle Title="BdpCommand Class"/>
<MSHelp:RLTitle Title="BdpCommand Class"/>
<MSHelp:Keyword Index="K" Term="Borland.Data.Provider.BdpCommand"/>
<MSHelp:Keyword Index="F" Term="Borland.Data.Provider.BdpCommand"/>
<MSHelp:Keyword Index="A" Term="Borland.Data.Provider.BdpCommand"/>
<MSHelp:Keyword Index="K" Term="Data.Provider.BdpCommand"/>
<MSHelp:Keyword Index="F" Term="Data.Provider.BdpCommand"/>
<MSHelp:Keyword Index="A" Term="Data.Provider.BdpCommand"/>
<MSHelp:Keyword Index="K" Term="Provider.BdpCommand"/>
<MSHelp:Keyword Index="F" Term="Provider.BdpCommand"/>
<MSHelp:Keyword Index="A" Term="Provider.BdpCommand"/>
<MSHelp:Keyword Index="K" Term="BdpCommand"/>
<MSHelp:Keyword Index="F" Term="BdpCommand"/>
<MSHelp:Keyword Index="A" Term="BdpCommand"/>
<MSHelp:Attr Name="TopicType" Value="api"/>
<MSHelp:Attr Name="Status" Value="New"/>
<MSHelp:Attr Name="Product" Value="Borland C#Builder"/>
<MSHelp:Attr Name="ProductVers" Value="1.0"/>
<MSHelp:Attr Name="DevLang" Value="CSharp"/>
<MSHelp:Attr Name="DevLangVers" Value="CSharp"/>
<MSHelp:Attr Name="Locale" Value="kbEnglish"/>
<MSHelp:Attr Name="Technology" Value="C#Builder"/>
<MSHelp:Attr Name="DocSet" Value="csb"/>
<MSHelp:Attr Name="DocSet" Value="csbapi"/>
<MSHelp:Attr Name="DocSet" Value="C#Builder"/>
<MSHelp:Attr Name="DocSet" Value="C#"/>
</xml>

A Quick look at XML Markup

Let's look briefly at the XML data Island markup above, normally found in the <head> section of a HTML topic. Do a "View Source" on a C# Builder help topic to check them out. The markup is fully documented in the VSHIK documentation:

  • TOCTitle: If the TOC (.HxT) topic node does not contain a title string then it will use this string.
  • RLTitle: This label to use if the topic is listed in a search Result List.
  • Keyword: Adds the specified Keyword to the specified (.HxK) Index file. Where "K" is the visible Index seen in the Index navigation tab. "A" is the associative Index and "F" is the context help index. The "F" Index is generally used for F1 context sensitive help. Although Borland seem to mirror the "A" and "F" indexes most of the time.
  • Attr: Topics can be tagged with attributes. Filters can be created from these attributes and used by a help viewer to filter the TOC/Index/Search content.

2. Help from the Object Inspector

When F1 is pressed help searches the "A" and "F" Indexes for a string matching whatever property is in focus when F1 is pressed.

Thus, to have the topic for the "Active" property of the class Borland.Data.Provider.BdpDataAdapter appear when the Active property is selected in the Inspector, the topic must contain the "A" or "F" keyword string "Borland.Data.Provider.BdpDataAdapter.Active".

3. Help from a component dropped onto a form

When F1 is pressed help searches the "A" and "F" Indexes for a string matching the fully qualified name of the selected component class.

Thus, if a BdpCommand component is dropped onto a form and the user selects it and presses F1, Help keywords are searched for the string, "Borland.Data.Provider.BdpCommand".

4. Help from "Non-API" topics (dialogs, menus, etc.)

When F1 is pressed help searches the "A" and "F" Indexes for a matching context ID. The ID is passed to Help through the HelpContext property of the dialog, menu, or form element.

Example: When the Help button is pressed in the Environment Options dialog, Help is searched for the "A" keyword "csb:1800". (The keyword can be any string; Borland use a merge of a "csb" identifier plus a value drawn from a set of legacy context ID numbers, but any unique string value will work.)

Here is an example: The XML data Island from ms-help://borland.bds/csbui/html/EnvironmentOptions.htm

<xml>
<MSHelp:TOCTitle Title="Environment Options"/>
<MSHelp:RLTitle Title="Environment Options"/>
<MSHelp:Keyword Index="A" Term="hc_oenvpreferences"/>
<MSHelp:Keyword Index="F" Term="hc_oenvpreferences"/>
<MSHelp:Keyword Index="A" Term="hcoenvpreferences"/>
<MSHelp:Keyword Index="F" Term="hcoenvpreferences"/>
<MSHelp:Keyword Index="A" Term="csb:1800"/>
<MSHelp:Keyword Index="F" Term="bds:1800"/>
<MSHelp:Keyword Index="A" Term="bds:1800"/>
<MSHelp:Keyword Index="F" Term="csb:1800"/>
<MSHelp:Keyword Index="A" Term="1800"/>
<MSHelp:Keyword Index="F" Term="1800"/>
<MSHelp:Attr Name="TopicType" Value="dialog"/>
<MSHelp:Attr Name="Status" Value="New"/>
<MSHelp:Attr Name="Product" Value="Borland C#Builder"/>
<MSHelp:Attr Name="ProductVers" Value="1.0"/>
<MSHelp:Attr Name="Locale" Value="kbEnglish"/>
<MSHelp:Attr Name="DevLang" Value="CSharp"/>
<MSHelp:Attr Name="DevLangVers" Value="CSharp"/>
<MSHelp:Attr Name="DocSet" Value="C#Builder"/>
<MSHelp:Attr Name="DocSet" Value="csb"/>
<MSHelp:Attr Name="DocSet" Value="C#"/>
<MSHelp:Attr Name="Technology" Value="C#Builder"/>
</xml>

Topic Attributes & Filters

As you can see each C# Builder core topic is tagged with the following set up attributes.

<xml>
<MSHelp:TOCTitle Title="Environment Options"/>
<MSHelp:RLTitle Title="Environment Options"/>
<MSHelp:Keyword Index="A" Term="hc_oenvpreferences"/>
<MSHelp:Keyword Index="F" Term="hc_oenvpreferences"/>
<MSHelp:Keyword Index="A" Term="hcoenvpreferences"/>
<MSHelp:Keyword Index="F" Term="hcoenvpreferences"/>
<MSHelp:Keyword Index="A" Term="csb:1800"/>
<MSHelp:Keyword Index="F" Term="bds:1800"/>
<MSHelp:Keyword Index="A" Term="bds:1800"/>
<MSHelp:Keyword Index="F" Term="csb:1800"/>
<MSHelp:Keyword Index="A" Term="1800"/>
<MSHelp:Keyword Index="F" Term="1800"/>
<MSHelp:Attr Name="TopicType" Value="dialog"/>
<MSHelp:Attr Name="Status" Value="New"/>
<MSHelp:Attr Name="Product" Value="Borland C#Builder"/>
<MSHelp:Attr Name="ProductVers" Value="1.0"/>
<MSHelp:Attr Name="Locale" Value="kbEnglish"/>
<MSHelp:Attr Name="DevLang" Value="CSharp"/>
<MSHelp:Attr Name="DevLangVers" Value="CSharp"/>
<MSHelp:Attr Name="DocSet" Value="C#Builder"/>
<MSHelp:Attr Name="DocSet" Value="csb"/>
<MSHelp:Attr Name="DocSet" Value="C#"/>
<MSHelp:Attr Name="Technology" Value="C#Builder"/>
</xml>

Topic attributes are use to create Filters. Filters allow the help viewer to restrict what TOC/Index/Search information is displayed. Here are the default filters that C# Builder IDE creates at setup/registration time. These can all be modified in the help viewer's filter editor.

 Name: (no filter),            Query: 
 Name: C#Builder only,         Query: "DocSet"="csb"
 Name: Language: C#,           Query: "DocSet"="C#" OR "DevLang"="CSharp"
 Name: Crystal Reports,        Query: "DocSet"="CrystalReports"
 Name: NET Framework SDK,      Query: "DocSet"="NETFramework"
 Name: Borland Help,           Query: ("DocSet"="BDS")

Example: If you wanted your integrated help to show when the "Language: C#" filter was selected then make sure your topics are tagged with one or both of the following attributes in the topics XML data Island.

<MSHelp:Attr Name="DevLang" Value="CSharp"/>
<MSHelp:Attr Name="DocSet" Value="C#"/>

Here is an example of a more complex Filter Query.

(("TType"="script") OR ("TType"="introduction")) AND (NOT ("DocType"="Article"))

See VSHIK documentation for more detailed information on attributes and filters. 
Registration programs such as VSHIK MSI and H2Reg allow you to define Filters at setup/registration time.

Note that the FAR HTML "H2 Utilities > XML Markup page" allows you to add/remove/find/merge XML Markup for 1000's of files in just a few seconds.

Attributes need a correctly setup (.HxA) collection-level attribute definition file (see next section).

Some general tips on support files:

.HxA Attribute Files

Microsoft advises that you do not need to include a project-level (.HxA) attribute definition file. Include only a collection-level .HxA file which defines all attributes used by your collection. Doing this will expose all attribute markup correctly to the host collection you are plugged into.

For addition reading see: MS H2 Attributes & Filters

Note that the FAR HTML "H2 Utilities > XML Markup page", allows you to find all XML topic Markup in your topic files and then Export the Attribute information out to a collection-level .HxA file. This utility can save you many hours of work.

.HxT Table of Contents

The TOC is straightforward using a FAR HTML. Each project needs a project-level .HxT TOC file which gets compiled into the .HxS help file. FAR can generate a basic HxT file automatically for you using the file and directory structure found. You can then drag and drop TOC entries using the FAR TOC Editor to form the TOC structure you want.

The collection-level .HxT file can be generated quickly using the FAR Collection Wizard. The file contains a bunch of TitleIDs which indirectly represents the TOCs (stored in .HxS Titles) to merge in the collection's master TOC. If you ever change the TitleIds used to register the Titles (.HxS help files) make sure you also change them in this .HxT file. The collection-level HxT also defines whether your TOC is Flat or Hierarchical style when plugging into another collection.

.HxK Index Files

We have talked previously about the various types of .HxK index files above. Generally the "A", "F", "K" Indexes (both project-level and collection-level) contain no Keyword entries at all. This is because MS H2 index entries are normally defined in the topic headers via an <xml> data Island.

You can still define indexes in the old fashioned way if you want, by inserting the Keyword/URL data pairs directly into the appropriate .HxK definition file. FAR includes a nice little Index editor. Many authors still like to manage the Visible "K" Index keywords (displayed in the Index Navigation tab) in this way. What makes a .HxK file an "A", "F" or "K"  Index? These index names are defined inside the .HxK XML file and in the accompanying .HxC collection file.

Whether you decide to add some or all keyword entries into the project-level .HxK file(s), make sure the collection-level .HxK files stays free from keywords. Both the project-level and collection-level files are required if you want your Index entries to correctly merge into the Parent collection's indexes.

Notice that the FAR H2 Viewer includes an Index dropdown so you can view any Index not just the "K" visible index. A handy debugging feature.

Borland Integration -- The Easy way

For those of you using FAR HTML here is a check list to help you create and integrate your C# builder help content. FAR really makes it very easy now to quickly create MS Help 2 content and plug it into 3rd party collection such as C# Builder's help.

  1. Create your Help topics. Use your favourite HTML editor to create a help web. Do not use a program like MS Word. Use a proper HTML or Text editor which will create clean HTML code (eg. Frontpage, Dreamweaver, HomeSite or Notepad).
     
  2. Add <XML> Data Island to each file. Add XML Markup to the top of each topic file so that F1 help works (see above). TOCTitle and RLTitle are option. Add any required attribute markup for filtering. 
    Tip: Use the FAR "H2 Utilities > XML Markup page" to quickly manipulate topic markup.
     
  3. Open the "FAR HTML" Help Wizard. Follow the steps and generate a HxS help file. 
    If you have other HxS files to create repeat the previous steps and create them.
     
  4. Open the "FAR HTML" Collection Wizard. This is available from the H2 Project Editor (File menu). Follow the steps and generate the required collection-level files and registration script. Test the collection.
     
  5. Create a Collection-level .HxA file. FAR does not automatically populate this file. Use the FAR "H2 Utilities window > XML Markup page" to find all markup then export attribute information to a collection-level .HxA attribute definition file. Remember Microsoft's advice to excluding project-level .HxA files completely.
     
  6. Install & Register files. Configure your Setup program to Install & Register all files (as specified in Shipping list created by the Collection Wizard).

Controlling the Help Viewer

DExplore.exe is the standard MS Help 2 viewer application the comes with MS Help 2 runtime. The first release of C# Builder has adopted it as its standard viewer. DExplore has a weak set of command line parameters but hidden beneath is a rich COM interface. This is what Borland uses to control the viewer.

The DExplore COM interface is undocumented. However you can find info about it here:

Comments