The MS Help 2 Register dialog is available from the H2 Utilities dialog and the H2 Project Editor. It allows you to register and unregister collections, as well as add and remove help titles, plug-ins and filters. Take care with this utility as you can very quickly stop a help system from working.
Demo Collection
Having trouble creating and plugging in your collection? We have created a demo collection you can play with. It comes with brief documentation.
Notice that when you enter a valid Namespace name (i.e. one representing a valid registered collection), the name is displayed in the title bar of the window, and the other page tabs become visible. We will refer to this Namespace as the "Current Namespace".
Each collection must contain one or more help files. These are called Titles. As you select each Title in the top list, the bottom list will display information about that title. Notice that each Title requires that you specify a unique Title ID. This Title ID is often the help file filename with no file extension.Commands to Add, Edit and Remove Titles are found at the bottom of the page and in the right-click menu. Add and Edit are the same except that the Edit command will fill in all fields from the selected Title.
The Titles page tab displays the number of titles registered to the current namespace.
Note: If more than one title is selected in the titles list then
- The Remove button will remove all selected items.
- The Edit button will still open the "Edit Help Title" dialog however the Title, HxS and HxI fields will be non-editable.
The Plug-in page displays a list of Namespaces that have been plugged into the current namespace. This is a tree view control. Notice that if a plug-in item itself contains plug-ins then these too will be displayed as branches in the tree.
Click the Add button to plug a namespace into the current Namespace. The tree selection does not effect this command.
Click the Remove button to remove the selected Namespace (Plug-in) from the parent Namespace.
The Plug-ins page tab displays the number of plug-ins registered to the current namespace. If nested plug-ins are displayed then the page tab will display for example "Plug-ins (3+2)". Meaning the current namespace has 3 immediate children, while these children have a total of 2 children of their own.
Plug-ins are yet another way of creating a modular help system. Plug-ins are a quick way to add-on to a preinstalled help system, even a third party help system like the Visual Studio .NET help collection. The Add/Remove Plug-in services are normally used at Help Installation/De-Installation time, but made available here so you can quickly test your help system.
Here's how we would plug our collection (called the "Child") into the Microsoft VS.NET collection (called the "Parent). The correct Namespace to plug into for VS.NET is called "MS.VSCC" (VS 7.0) or "MS.VSCC.2003" (VS 7.1) etc.
- The Child Collection must be .HxC based:
Make sure your collection is based on a .HxC file, not a .HxS file. Even if you only have one .HxS help file, it must be accessed via Collection level files. You must also have a collection level .HxT file. Thus the minimum required files are -- A Collection level HxC and HxT, and one or more compiled help (.HxS) files.
- Register your Collection:
Before you can plug into the parent collection, make sure your collection is registered. Go to the Namespace page (above) and register the .HxC file under a Namespace name. Then go to the Titles Page (above), and add your .HxS help(s) files. Finally test your Collection and make sure you can view it.
- Plug-in to MS.VSCC:
To set the Parent Collection, go to the Namespace Page and select "MS.VSCC" from the Namespace dropdown list. Next go to the Plug-ins Page and select the Add button. Select your child Namespace and click "OK" to add your namespace.
The Add/Remove Plug-ins dialog has a number of fields. Choose the HxT TOC for the Parent and Child. Most Collections only have one HxT TOC so these can normally be set to the "default" option. If you want to add your attributes into the parent collection then you should specify a HxA file. Unlike the HxT fields, the HxA filename must be a full file path. If the Child collection file references a .HxA file, then it will appear in the HxA dropdown list.
Generally its just a matter of choosing a valid HxC based child and clicking OK.
Only collections which contain attribute information (.HxA file) may contain filters. That is you can add filter names to any namespace but if there are no attributes available then you can not create valid query strings.
The filter list displays all filters definitions for the current Namespace. The list is sorted by the filter name.
Check the checkbox "Include Plug-in Filters" to additionally display Filters of Child Namespaces (plug-ins), and Filters of Children of Children (nested plug-ins) etc. This may be helpful since the basic H2 Viewer uses all NS Filters including the Filters of all children and sub-children if available. Notice that the list can display duplicates filter names if 2 or more namespaces contain the same filter name. These duplicates are normally suppressed in the basic H2 Viewer by showing the first unique Filter name found.
The Add/Edit button opens the Edit Filters dialog. This is the same dialog available in the FAR H2 Viewer. If "Include Plug-in Filters" is checked, then the Edit Filter dialog will edit all Filters including filters of all plug-ins. Duplicates will be visible. If "Include Plug-in Filters" is not checked, then the Edit Filter dialog will only edit those filters belonging to the current namespace.
The Remove button allows you to remove Filters you have selected in the List of Filters above. This command allows you to also remove filters in plug-ins.
The Filter page tab normally displays the number of filters owned by the current namespace. When "Include Plug-in Filters" is checked you may see a display such as "Filters (3+2)". This would mean there are 3 filters belonging to the current namespace, and 2 filters belonging to child (plug-in) namespaces.
Large complex collections can take time to setup. In the H2 Utilities dialog you will notice a menu command "Namespace > H2Reg Export". This command exports all configuration data, of the selected Namespace, out to a H2Reg command script (INI) file (see H2Reg Home Page).
You can import Title, Plug-in or Filter data from a H2Reg command script file by right-clicking the Title, Plug-in or Filter page list and selecting H2Reg Import. This opens the H2Reg Import dialog.
Example: Go to the Filters page. Right-click the filters list and select H2Reg Import. When the Import dialog appears select a H2Reg_Cmd.ini file (your h2reg command script file), click the Set NS button if required, then click the Register button. FAR will extract the information from the [REG_FILTER] section of the INI file and add the specified Filter information into the "Current Namespace" (the Namespace current selected in the Registration dialog).
You can also Import from the H2 Utilities window.
The Title, Plug-in and Filter pages all contain a popup menu (right-click the list box) which you can use instead of clicking the Add, Edit, Remove buttons. The Import command (discussed above) is also included in the popup menus. There is one other command we have not discussed yet called "Go To Namespace". Use "Go To Namespace" is quickly change the "current namespace" to the namespace (plug-in) selected in list of either the Plug-in and Filters page.
For more information on Namespaces and collections see the MS Help SDK documentation.