MS Help 2 Utilities

Main menu |  Namespace | Decompile | Convert | Merge | XML Markup

The "H2 Utilities" window is available from the Authoring menu (main window) and from the H2 Project Editor. This window requires that you have MS Help 2.x run-time and MS Help 2.x SDK (Workshop) installed.

New to MS Help 2? Read the MS Help Primer.

Main Menu
Namespaces page
Top window pane

The top pane of the Namespace page lists all registered collections found.

Namespace - Column contains the namespace name that the collection is known by.
Collection File - Column contains the collection file (HxC or HxS) associated with the namespace.
Ext - The file extension of the Collection file. HxS collections can only contain one help file.
File Date - The file date of the Collection file.
Titles - Number of help files in the collection.
Plug-ins - Number of child collections plugged into the collection.
Description - Description string that the collection was registered with.

A red cross on a namespace icon means either a) collection file not found or b) collection contains no Titles. HxS based collections (single title, no collection-level files) have a yellow background. A tiny plus on the icon means the collection contains one or more plug-ins.
Bottom window pane

The bottom window pane displays more detail on the selected Collection. Click on an item in the top pane to fill the bottom pane.

At the top of the lower pane are some expandable sections of text. Click either the [+] or [-] graphics to expand or contract a section. If you click on the hyper-text next to the graphic, it will also perform expand and contract, plus it will also cause the system to remember the last state. IE. Expand using the underlined link, and the next time you click on a Namespace it will be expanded as well.

In the toolbar is an extra control "Font Size". This sets the font size of the lower details list.

The Plug-in, Filter and Title lists are not sorted. At the moment they are listed exactly as delivered to FAR by the H2 API.

The lower pane is an embedded Web Browser window. Right-click to get the Internet Explore popup menu. Press Ctrl+F to find text within the document.

Namespace List Popup Menu

Right-click the top pane for Namespace commands. These commands are also available in the toolbar and Namespace menu.

About H2Reg Export
The H2Reg Export command allows you to create a H2Reg.exe compatible registration command script file from information collected from the selected Namespace(s). H2Reg.exe a Helpware product that you can ship with your H2 installation files. It registers your collection during setup time (see more notes below).

Apart from creating script for the H2Reg.exe utility, we recommend you export complex collection you are working on. If the collection should become corrupted, as is often the case when you are experimenting with H2 Registration, you can simply perform a H2Reg Import (see below) to regenerate the collection. Tip: Sometimes a reboot is also needed.

 When you select the H2Reg Export command a Save dialog will appear. Enter the name of the script file (typically H2Reg_cmd.ini) you want to export to. Notice at the bottom of the Save dialog is a drop down called Parent Namespace. This controls what plug-in information is generated for the script file. Plug-in script is stored in the [Reg_Plugin]/[Unreg_Plugin] script sections.

Parent Namespace dropdown options:

  • <1> Script any existing plug-ins - Select this option (the default) to create plug-in script for other collections that are plugged into the selected namespace(s). This is useful if you are simply backing up a collection's registration settings. Reinstalling say MS VS .NET or Borland C# Builder may not be necessary if you have remembered to backup the registration settings.
  • <2> Do not script for Plug-ins - Plug-in script is not generated. Example plug-in script is written instead. This is commented out using the leading ';' character.
  • Alternatively select/enter the name of the parent namespace that the selected namespace(s) should plug into. The dropdown list is populated with any variations of ms.vscc+ or borland+ found (the most common namespaces developers plug into). If you want to generate plug-in code for a parent namespace not listed, then simply type in its name.
About H2Reg.exe Utility

Our H2Reg.exe product allows you to Register/Unregister Namespaces, Titles, Plug-ins and Filters, without using the MSI methods documented in the VSHIK documentation. You can download the full working version of H2Reg and its documentation from the Helpware website:

H2Reg Home Page: http://www.helpwaregroup.com/products/h2reg

Note: VSHIK MSI allows you to plug into ms.vscc.*, but not into other collections such as "borland.bds". H2Reg allows you plug into any collection. It even allows for wild chars such as ms.vscc+ (plug into any ms.vscc Namespace found).
Decompile page

Decompile a HxS help file. Specify the HxS help file you want to extract the files from, as well as the folder you want the files to be sent to, and press the Decompile button. Unlike the HH 1.x decompiler, you will get all files extracted (including the .HxC project file) exactly as they were at compile time. The View Help File button displays the specified .HxS help file using the assigned help file viewer (See Preferences window - F12).

You can also extract selected files from the HH Utilities window.

Explorer Output Folder button: Opens a File Explorer window at the output folder.

Convert 1.x page

Convert a MS HTML Help 1.x project into a MS Help 2 project. This simply calls the MS Help SDK utility HxConv.exe. The path to the H2 Utilities is defined in the Preferences dialog. You may specify either a .CHM or a .HHP file as the input file. Specify an output folder for the new MS Help project files to be created in, and press the Run HxConv.exe button.

Several command-line options are available. See MS Help SDK help for more info on these switches.
http://msdn2.microsoft.com/en-us/library/bb165172(VS.80).aspx

HxConv is very basic. Expect errors. Study the output log, with a bit of work you will achieve a clean compile. You may need to convert your new HTML files to Unicode to make your new H2 project compile.

Explorer Output Folder button: Opens a File Explorer window at the output folder.

Capture DOS Output checkbox: Sometimes the DOS window opens and closes so quickly that you cannot read the output text. When this happens, try checking this box before clicking the Run button. A text box will appear at the bottom of the window, and FAR attempts to direct all text output from the running application into this text box. Note: You may need to enlarge the Utilities window to view the text box.

Some important notes:
  • In VS 2005 Microsoft removed the ability to Convert a .CHM. Convert .HHP still works. Read more [www.HelpwareGroup.com].
  • In VS 2008 Microsoft forgot to ship all the Hx*.exe SDK utilities. Use the VS 2005 ones instead. Read more [www.HelpwareGroup.com].
Merge Utility page

This simply calls the MS Help SDK utility HxMerge.exe. The path to the H2 Utilities is defined in the Preferences dialog.

Introduction: The Microsoft SDK comes with a utility called HxMerge.exe. This utility allows you to create combined Query (full-text search) file (.HxQ), or a combined Attribute Query file (.HxR). In a large collection the HxQ and HxR files can speed up the time it takes to run a query. To create a .HxQ or .HxR file you first need to create a .HxM project file. This .HxM project file is an XML file that specifies the name of the output file (HxQ or HxR), as well as the name of a HxF Include file which contains a list of HxS files to extract information from. Once you have created the HxQ and HxR files, you need to register them at the same time you register a .HxS Help Title.

The HxF Include file simply contains a list of .HxS files. This type of HxF does not contain any XML markup. You can edit the HxM and HxF files using Notepad or with FAR be clicking the "HxM Project File Editor" button.

.HxM Project File: Specify the name of the project file to create, edit or compile.

Run HxMerge Button: Launches the Microsoft HxMerge.exe utility with the HxM project file as a parameter.

Explorer Output Folder button: Opens a File Explorer window at the output folder.

HxM Project File Editor: Opens the HxM Project Editor window. The file initially opened or created is the file specified in the ".HxM Project File" edit field above. Use the editor to setup your HxM project file and its list of HxS Title files.

See MS Help SDK for more information on .HxQ and .HxR files, and the HxMerge.exe utility.
.HxM files: http://msdn2.microsoft.com/en-us/library/bb164856(VS.80).aspx
MxMerge.exe: http://msdn2.microsoft.com/en-us/library/bb164570(VS.80).aspx

XML Markup

  XML Markup page has been deprecated and is no longer being maintained. Please use FAR's new Tag Editor instead to manipulate Help 2 XML markup.
 

This page helps you manage your XML data Island Markup. XML Markup such as attributes and Keywords can become very complex as the number of markup items grow. This collection of tools allow you to Find/Replace/Merge/Remove markup across hundreds of HTML files within a short amount of time.

This is accomplished by using FAR's powerful Find & Replace engine and the $M$ commands. Knowledge of the $X$ commands is not required in this page.

Examples of MS Help 2 XML Markup. See your MS documentation for details.

<xml>
   <MSHelp:Attr Name = "" Value = ""/>
   <MSHelp:Attr Name = "" Value = "" VTopic = ""/>
   <MSHelp:FTSIndex VTopic = ""/>
   <MSHelp:Include File = ""/>
   <MSHelp:Keyword Index = "" Term = ""/>
   <MSHelp:Keyword Index = "" Term= "" VTopic = ""/>
   <MSHelp:NoSearch/>
   <MSHelp:RLTitle Title= ""/>
   <MSHelp:RLTitle Title= "" VTopic = ""/>
   <MSHelp:TOCTitle Title = ""/>
   <MSHelp:TOCTitle Title= "" VTopic = ""/>
   <MSHelp:VTopic Name = ""/>
</xml>
Procedure
  1. Add the HTML files you want to search or update into the FAR file list on the main window.
  2. Click a command button. Commands in the bottom section need you to enter XML Markup in the lower list. Commands that modify your files will always display the Find & Replace preview window so you can OK changes.
  3. The main window will come to the front to show you the search progress. Press Esc at any time to quit the search job.
  4. The Find All Markup results are displayed in the top list of the XML Markup page.
    The other XML Markup commands (lower section) display matches and replacements by
    a) Setting the Match and Replace fields in the FAR file list.
    b) Files that are Found or Modified are moved to the top of the FAR list and Highlighted.
Top Section
Top List (readonly) The top list is readonly and displays the results from the Find All Markup command. Items from the top list can be selected and dragged or copy (Ctrl+C) and pasted (Ctrl+V) into the bottom list.
Find All Markup This command searches all HTML files in your FAR file list for XML data Island Markup. The resulting list (with no duplicates) is displayed in the top list box. Markup items are sorted and grouped by Markup type. The Find & Replace preview window is not displayed for this command.
Result Filter This drop down list allows you to filter the list of results (top list). It also displays the number of XML Markup items found.
Top Section Popup Commands
Mark Attr Items also found in a Namespace This command is available from the Top List right-click popup menu. It allows you to select an existing Namespace then mark all Top List Attr items that are found to be defined in that Namespace.

Example: Select MS.VSCC.2003 and any MS.VSCC.2003 attributes found in the Top Markup result list are marked with a blue tick. This is particularly handy when creating collection level HxA files. When you plug into VS .NET there is no point in redefining attributes already defined in the parent VS .NET collection.

Export Selected to HxA This command is available from the Top List right-click popup menu. It allows you to select one or more Attr Markup items and create a .HxA attribute definition file using those items.
Bottom Section
Bottom List The bottom list is a multi-line editor. Here you specify the XML Markup used by the Find/Replace/Merge/Remove commands. Markup can optionally be wrapped in the <xml>...</xml> tags (same as in the HTML file) but it makes no difference to the end result.

Example Markup:

   <MSHelp:Attr Name="DocSet" Value="Visual Studio"/>
<MSHelp:Attr Name="Locale" Value="kbEnglish"/>

Note: Indenting the first item in the list (as above) will cause all items in the replacement text to also be indented (at replace time).
Find This command finds all HTML Topics (in the FAR file list) that contain the XML markup specified in the bottom list. Note that only files that contain ALL specified markup are matched. Matched files are selected and marked as Matches = 1 in the FAR file list. The Find & Replace preview window is not displayed.
Replace ** This command searches through all HTML files (in the FAR file list) and replaces any existing <xml>...</xml> markup with the XML Mark specified in the lower list. Files with no <xml>...</xml> markup will have the specified XML markup added immediately after the </title> tag (or <head> tag if no title is found).
Merge ** This command takes the specified XML markup (in the lower list) and merges it into every HTML file in the FAR file list. Including those containing no <xml>...</xml> markup section. Merge is smart in that it does not insert duplicates markup.
Remove ** This command removes the specified markup from all HTML files in the FAR file list. If only part of the specified markup is found then that part is removed from the file.

** Modifying Commands: All files modified are highlighted in the FAR file list and marked as Replacements = 1 (FAR file list column). The Find & Replace preview window is always displayed prior to the modification (until Replace All is clicked).  Note that some files may not match because the specified markup change already exists in the target file (ie. there was nothing to do). This is different from normal find & replace behaviour.

Note: The FAR XML Markup commands do not support multiple occurrence of <xml>..</xml> data Islands in a single file.

http://www.HelpwareGroup.com/