H2Reg Script Example

Background

H2Reg.exe is driven by a command script file. This is a simple INI file that can be edited using any text editor. You can also generate command script files using the shareware program FAR HTML by exporting existing collections. FAR also contains a Collection Wizards that can generate the collection level files required as well as the required H2Reg script.

When you ship H2Reg.exe (or H2Reg.dll) you also need to ship a companion file, h2reg.ini, which defines language display strings etc. In the example below we chose to add our command script (see blue text below) to the top of h2reg.ini (since we ship a simple system). Alternatively you can ship one or more separate command script INI files and run them one at a time from the h2reg.exe command line.

For now lets say we have placed our command script inside the system file H2Reg.ini (so no additional command file is required). All we need to do now is run H2Reg.exe:

H2Reg.exe -r

Configure your installer to call H2Reg.exe -r after you have installed all help collection files. This executes the [Reg_...] sections of the command script file (see top half of blue text below).

H2Reg.exe -r -m

Alternatively you can add the -m switch which forces a Merging of TOC and Index files of all namespaces affected by registration. If you have specified a [Merge_Namespace] section then only those namespaces listed in that section will be merged. Note that for VS 2005 you must merge both ms.vsipcc.v80 and ms.vscc.v80 (ms.vsipcc.v90 and ms.vscc.v90 for VS 2008).

H2Reg.exe -u

Configure your installer to call H2Reg.exe -u during its uninstall phase. This executes the [UnReg_...] sections of the command script file (see bottom half of blue text below).

So you would normally install H2Reg.exe and H2Reg.ini into the same folder as your .Hx? files using your favourite installation program. Configure your installation program to run "H2Reg.exe -r" during installation and "H2Reg.exe -u" during de-installation.

Looking at the Command Script

The registration script below (in blue) first creates a Namespace called "hw.h2reg". It is associated with a file called COL_Master.HxC (found in the same folder as the INI file). We have also give the Namespace a description (3rd param). The [Reg_Namespace] section can contain as many command lines as you want.

Next we added a help title to the "hw.h2reg" namespace called "h2reg.HxS" and gave it a name of "h2reg" (this name must match the name you used in the collection level HxT TOC file). Again you can add as many help title command lines as you want.

Next our namespace "hw.h2reg" is plugged into Visual Studio help collection. We plug into whatever VS help collection we can find -- VS 7.0 help (ms.vscc), VS 7.1 (ms.vscc.2003), VS 8.0 (ms.vsipcc.v80). Something by the way that the Microsoft MSI solution cannot do. H2Reg can also use wild cards so we used "MS.VSIPCC+" which means our collection will plug into ms.vsipcc.v80, ms.vsipcc.v81... and all future collections (whatever VS collection H2Reg can find starting with MS.VSIPCC).

The [Reg_Filter] section creates a filter for our "hw.h2reg" collection. Because our collection is plugged into VS it will be visible also when viewing the VS collection.

The other four section deal with unregistering your collection (when h2reg.exe -u is run). Here H2Reg actually runs [UnReg_Filter] first (to remove a filter), then runs [UnReg_Plugin] to unplug "hw.h2reg" from "MS.VSCC", "MS.VSCC.2003" and all "MS.VSIPCC.*", then runs [UnReg_Title] to remove our title, then finally runs [UnReg_Namespace] to remove our namespace. Note however the act of unregistering our namespace effectively performs the Title and Filter removal for us (since a title and filter cannot exist without a namespace). So the Title and Filter removal commands could in fact be deleted from the script.

Note: We placed the Command Script INI file in the same folder as our .Hx? files. This means that no path info was needed when declaring the .Hx? filenames in the script.

Script to pre-merge the collection (requires the -M merge switch)

This section allows you to merge your help into the host collection at registration time. Remember to use the -M switch when running h2reg.exe.

Note: VS 2005 Express uses a collection called MS.VSExpressCC.v80 instead of ms.vscc.v80.

Note: VS 2008 Express uses a collection called MS.VSExpressCC.v90 instead of ms.vscc.v90.

To merge all versions of VS use

[Merge_Namespace]

ms.vsipcc+

ms.vscc+

ms.vsexpresscc+

To merge VS 2003 and above

[Merge_Namespace]

ms.vscc.2003

ms.vsipcc+

ms.vscc.v*

ms.vsexpresscc+

To merge specifically VS 2003 + VS 2005 + 2008 + VS Express versions

[Merge_Namespace]

ms.vscc.2003

ms.vsipcc.v80

ms.vscc.v80

ms.vsexpresscc.v80

ms.vsipcc.v90

ms.vscc.v90

ms.vsexpresscc.v90

Back to H2Reg Home Page

;------- Register -r switch

[Reg_Namespace]

;<nsName>|<nsColfile>|<nsDesc>

hw.h2reg|COL_Master.HxC|H2Reg.exe Documentation - www.helpware.net

[Reg_Title]

;<nsName>|<TitleID>|<LangId>|<HxS_HelpFile>|<HxI_IndexFile>|<HxQ_QueryFile>|<HxR_AttrQueryFile>|<HxsMediaLoc>|<HxqMediaLoc>|<HxrMediaLoc>|<SampleMediaLoc>

hw.h2reg|h2reg|1033|h2reg.HxS|h2reg.HxS||||||

[Reg_Plugin]

;<nsName_Parent>|<HxT_Parent>|<nsName_Child>|<HxT_Child>|<HxA_Child>

MS.VSCC|_DEFAULT|hw.h2reg|_DEFAULT|COL_Master.HxA

MS.VSCC.2003|_DEFAULT|hw.h2reg|_DEFAULT|COL_Master.HxA

MS.VSIPCC+|_DEFAULT|hw.h2reg|_DEFAULT|COL_Master.HxA

[Reg_Filter]

;<nsName>|<FilterName>|<FilterQueryStr>

hw.h2reg|h2reg helpware documentation|("helpware"="h2reg")

;------- UnRegister -u switch

[UnReg_Namespace]

;<nsName>

hw.h2reg

[UnReg_Title]

;<nsName>|<TitleID>|<LangId>

hw.h2reg|h2reg|1033

[UnReg_Plugin]

;<nsName_Parent>|<HxT_Parent>|<nsName_Child>|<HxT_Child>|<HxA_Child>

MS.VSCC|_DEFAULT|hw.h2reg|_DEFAULT|COL_Master.HxA

MS.VSCC.2003|_DEFAULT|hw.h2reg|_DEFAULT|COL_Master.HxA

MS.VSIPCC+|_DEFAULT|hw.h2reg|_DEFAULT|COL_Master.HxA

[UnReg_Filter]

;<nsName>|<FilterName>

hw.h2reg|h2reg helpware documentation

;------- Merge -m switch

[Merge_Namespace]

ms.vsipcc+

ms.vscc+

ms.vsexpresscc+

;------ Optional Stuff

[MAIN]

DebugMode=0 ;Set to 1 to log everything - Checks your resources (ship with =0)

DumpNSToLog_before=0 ;Very verbose but good for debugging - dumps all NS info to log file before Registration

DumpNSToLog_after=0 ;Very verbose but good for debugging - dumps all NS info to log file after Registration

OKtoReport_FinalRegError=0 ;Report general error at end if a registration error was logged

OKtoReport_FinalUnRegError=0 ;Report general error at end if a unregistration error was logged

;Advanced feature - These can be set then used as <userdir1> etc specifiers. They can

;also be set via the H2Reg.exe command line. Command line has preference over INI file.

UserDir1=''

UserDir2=''

UserDir3=''

UserDir4=''

; Strings Resources & Translation

[en] ; English

ErrSt_SysFileNotFound = 'Installation Error. Error reading system file or file not found.|%s'

ErrSt_MSHelp2RTNotFound = 'MS Help 2.x runtime files are not installed on this PC.'

ErrSt_NotAdminMode = 'You must be logged on as an Administrator.'

ErrSt_Extra = 'Installation/registration of Help files cannot proceed.'

Msg_Registering = 'Registering Online Documentation Files:'

Msg_UnRegistering = 'Unregistering Online Documentation Files:'

Msg_LoggingNSInfo = 'Logging Namespace Info'

Msg_Registering_Namespaces = 'Registering Namespaces'

Msg_Registering_Titles = 'Registering Titles'

Msg_Registering_Plugins = 'Registering Plug-ins'

Msg_Registering_Filters = 'Registering Filters'

Msg_UnRegistering_Namespaces = 'Unregistering Namespaces'

Msg_UnRegistering_Titles = 'Unregistering Titles'

Msg_UnRegistering_Plugins = 'Unregistering Plug-ins'

Msg_UnRegistering_Filters = 'Unregistering Filters'

Msg_Merging_Namespaces = 'Merging Help Indexes. This may take several minutes'

PopupSt_FinalRegError='There were errors reported while Registering help files.||View Log file?'

PopupSt_FinalUnRegError='There were errors reported while Unregistering help files.||View Log file?'

; International Strings - Defaults to [en]

[de] ; German

[ja] ; Japanese

[fr] ; French

[es] ; Spanish

[it] ; Italian

[ko] ; Korean

[cn] ; Chinese (Simplified)

[tw] ; Chinese (Traditional)

[sv] ; Swedish

[nl] ; Dutch

[ru] ; Russian

[ar] ; Arabic

[he] ; Hebrew

[da] ; Danish

[no] ; Norwegian

[fi] ; Finnish

[pt] ; Portuguese

[br] ; Brazilian

[cs] ; Czech

[pl] ; Polish

[hu] ; Hungarian

[el] ; Greek

[tr] ; Turkish

[sl] ; Slovenian

[sk] ; Slovakian

[eu] ; Basque

[ca] ; Catalan