Help 2 Collection Wizard

The Collection Wizard is available from the H2 Project Editor (File menu) and also from the Authoring menu (main window). It is for MS Help 2 authors only and provides step by step assistance in creating, registering and shipping an MS Help 2 collection. Before beginning make sure you have created the help title(s) (compiled .HxS help files) that will part of this collection.

Why do I need these collection level files?

If you plan to integrate your help into (plug into) another collection (typically ms.vscc or borland.bds) then you must create a collection-level files, even if you have only a single help file. Collection level files form a kind of container for your .HxS help file(s). This container is registered and plugged into the host collection.

Introduction

MS Help 2 collection-level files ship with your .HxS help file(s). They define how your help files merge together to form a single document set (collection) at run-time. Although it is possible to create a collection simply using a single .HxS help file (no collection-level files) this type of collection is very limited and cannot be plugged into another collection.

Plugging into another collection, is done at registration time and if done correctly, merges your collection's TOC(s), Index(es), Attributes, Filters, Search terms etc seamlessly into the host collection. Your position in the host's TOC will be initially at the end. Plug-ins work on a first in gets first position basis. This wizards will also help you register and ship your collection.

MS Help 2 content must be registered before it can be viewed (unlike MS HTML Help 1.x). The HxC Collection file (defined on page 1) will eventually be registered on the target machine using a Namespace name (some unique label). Then all .HxS help files (Titles) that make up the collection will then be registered under that Namespace name using unique Title Ids.

Background information: Collections

The Collection Wizard contains the following buttons and pages

Next	Move forward to the next page. This button is often disabled until page content is filled in. The button text changes to "Finish" on the last page. Clicking the finished button loads the HxC file into the main project editor.
Back	Move back a page. This button is disabled on the first page.
Close	Close this window.
Help	Display this help.

Page 1 - Enter a Collection File Name

Enter the full path of the .HxC collection file. This is the main XML file that defines your collection.

You can enter the name of an existing file or the name of a new HxC file you want to create. The dropdown list contains a history of HxC collection files you have used in the past. The browse button allows you to select an existing HxC file, or specify the folder location and name of a new HxC file.

The HxC collection file stores information about all other files so we define it in the very first page. It is very similar to a HxC Project file except it cannot be used to compile anything (any compiler info is ignored) and does not contain a XML DTD statement. By default all other collection-level files take their name from this file (filenames can be changed later).

Page 2 -  Add Help Titles

Fill the list with all help Titles that will make up this collection. Each Title must be given a unique Title ID (typically the .HxS help file name minus the file extension). The Title IDs will be used to registration each title (.HxS help file) under the collection's Namespace name at registration time. They are also used to define the master TOC (the collection-level .HxT Table of Contents file which is created later on). The list defines which Title TOCs are included in the master TOC and what order they will appear in. So list order is important. Use drag and drop to change the list order.

Add

Uses a Windows standard Open dialog to add a HxC project file (recommended) or .HxS help file. (FAR can get the .HxS help file name from a .HxC project file. Also .HxC file names are remembered by FAR and used next time you open a collection for editing). The choice is yours. If you choose to add a title via the HxC project file name, then make sure it has been compiled to a .HxS help title before proceeding.

Remove

Remove the selected list item.

Replace

The lower entry fields allow you to edit a selected list item. Click a list item to fill the lower entry fields. Now change the name of the TitleID and click "Replace" to modify the selected list item.

A help collection requires one or more help titles (.HxS help files). These are registered under the collection's namespace using a unique name called a TitleID.

Page 3 - Choose a Table Of Contents Plug-in Style

These settings only take effect when you plug your collection into another collection such as ms.vscc (VS .NET doc) or borland.bds (Borland C# Builder).

Flat

The merged Title TOCs are inserted at the top level of the parent collection's TOC.

Hierarchical

Specify the name of a TOC Node that the Merged TOCs are inserted into. This single TOC node is then inserted at the top level of the parent collection's TOC.

Page 4 - Enter Collection Namespace and Description

This information will be used if you choose to register & test the collection, or create a H2Reg registration script file. Also FAR stores this info as Meta data inside the HxC collection file for other dialogs to use.

Page 5 - Create All Files

This page lists all collection-level files that will be created. The Wizard forms this list automatically by examining all Titles you previously listed. The right-click popup menu allows you to Add/Remove items, as well as Edit the selected file name. The Edit button can also be used to edit the selected file name.

Click Next to create all files. You will be asked to select a File Type (since MS Help 2 supports both ANSI and UNICODE). Notice that some items have a "Tick" next to the name indicating that the items already exists on disk. Before an existing item (with Tick) is overwritten you are asked to "Overwrite Yes/No".

Page 6 - Create Registration Script File

This page allows you to generate a H2Reg registration script file for your new collection. The script file is a simple INI file you can ship with your collection files. It provides registration of all files in the collection on the target computer without the need for MSI. Even if you go the MSI route, a script file provides a fast clean way to test your collection locally before shipping (FAR can import H2Reg script files using the FAR H2 Utility window).

Click Next to create the script file. The script file will be generated and displayed on screen.

Create H2 Script file

Uncheck this box to disabable the creation of a H2Reg script file.

Script file name

Name of script file to create. The file will be created in the same folder the HxC collection file you defined on page 1.

Parent Namespace

If your collection will be be plugged into a parent namespace such as ms.vsipcc.v80 or borland.bds then enter that Namespace Name here otherwise leave this field blank so that plug-in script is not generated.

A Trailing "+" character acts like a wild character (eg. ms.vscc+ means plug into both ms.vscc and ms.vscc.2003, etc). One of H2Reg's strengths is that you can plug into multiple collections at once, unlike Microsoft's MSI solution.

Note: Visual Studio 2005 has brought with it some changes.
- For VS 2002 (v7.0) -- The parent namespace is "ms.vscc".
- For VS 2003 (v7.1) -- The parent namespace is "ms.vscc.2003".
- For VS 2005 (v8.0) -- The parent namespace is now "ms.vsipcc.v80".

Notice that prior to VS 2005 you plugged into MS.VSCC+
For VS 2005 and greater Microsoft now recommend that you plug into MS.VSIPCC.* . This is an attempt at keeping 3rd party collections isolated from the main MSDN documentation.

18-Nov-2006: Parent Namespace can now be a list of Namespaces (separated by a semi-colon). Each item will create a separate plug-in statement in the H2Reg script output.

Under H2Reg here is the recommended way to plug into all versions of Visual Studio: "ms.vscc;ms.vscc.2003;ms.vsipcc+"
Notice the trailing "+" after ms.vsipcc? This plugs into VS 2005 and greater.

At run-time H2Reg ignores any Parent Namespaces you specify that do not exist.

---

About Registration & H2Reg MS Help 2 content must be registered on the target machine before it can be viewed. VSHIK (Help 2 SDK) documentation guides you though how to use MSI (MS Installer) to register your collection. Many find MSI too complex to use. MSI is only designed for integrating help into a single VS .NET collection. If you want to avoid MSI or plug into a 3rd party collection such as "Borland.bds" we recommend you use our non-MSI registration solution H2Reg.exe. We are proud to say that many of the worlds top component vendors use H2Reg. H2Reg Home Page - Register Collections without MSI

Page 7 - Register & Test

This page allows you to optionally register and test your new collection.

H2Reg Import

If you created a H2Reg registration script file (previous page), then use the H2Reg Import dialog to register your collection using that script file. The H2Reg Import dialog allows you to select which parts of the script to execute. You can even modify the script and experiment with it then save or not save the changes. The H2Reg Import log can also help in debugging your collection.
Tip: Never changes the TitleIds, used to register each .HxS help file, without also changing the TitleIds used in the collection-level .HxT TOC file.

Auto-Register

This command automatically registers your collection, according to what was entered previously, so you can immediately view it. The result should be the same as using the H2Reg Import command. Although not as flexible as H2Reg Import it is a very quick way to register your collection on your development machine.

Register Window

Opens the Register window. This window allows you to view registration info for the current collection or manually register the collection. Probably of more use to the experienced developer/author.

View Collection

Open the collection in the configured H2 Help viewer (see the preferences window)

The above commands are also available in the H2 Utilities window and H2 Project Editor window.

Page - Finished

Click the Finished button to now load the project into the H2 Project Editor, or click Close to simply close the window.

This page also displays a list of shipping instructions. Click Save to save these instructions to disk.

Additional Notes

You now have a set of collection level files. These need to be shipped with your HxS help titles.

• HxC - The main Collection file contains info about all other files. The HxC file is registered to a unique name (called a Namespace) then each .HxS help file (title) is registered under this Namespace using a unique name called a TitleID (typically the .HxS file name with no extension).
• HxT - The TOC collection-level file contains a number of include statements. Each statement specifies a TitleID. This indirect method is the way we specify a Title's TOC file. This TitleID is the same one used to register each .HxS help file at registration time.
• HxK - Collection-level Index files are normally empty of keywords, but required if you want your index entries visible at the collection level or in a parent collection you plug into.
• HxA - Attributes defined in the collection-level attribute definition file make your attributes (defined in the XML data Islands of each topic) visible at the collection level or in a parent collection you plug into. The wizard does not fill in this file as it would require scanning all HTML files in all your projects. Use the H2 Utilities window (XML Markup page) to automatically generate the content for this file. There is no need to include attributes defined in the host collection (as they are already defined). Don't include project-level .HxA files (MS recommendation).
• HxV - The Collection-level virtual topic definition file is not currently supported by FAR. FAR will flesh out the file for you but not add data.
• HxE - The Collection-level sample definition file is not currently supported by FAR. FAR will flesh out the file for you but not add data.
• H2Reg_cmd.ini - Default name for the optional H2Reg registration script file.