H2 Project Editor

The "H2 Project Editor" window is available from the Authoring menu (main window), and from Windows Explorer when you right-click a .HxC project file and select "Open with FAR". Use the Help 2 Project Editor to create or modify Hep Project and Collection files.

Alternatively you can create these files using the FAR Help 2.x Project or Collection wizards.

Introduction

The H2 Project Editor allows you to create and edit MS Help 2 collection (.HxC) files, as well as other associated (.Hx?) project files. There are two types of HxC files:

(1) HxC Project file used to compile a .HxS help file.

(2) HxC Collection-Level file used to merge several help files at run-time. Collection-Level files are installed and registered with your .HxS help files. If you want to merge your .HxS help file with another collection (eg. MSDN Help) then these files are required. Usually the Help Collection wizard is an easier way to generate these files.

Note that MS Help SDK Application (Workshop), does not support creating the latter but does providing relevant documentation.

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

About Green Links:

Throughout this help, and throughout the FAR Help 2 dialogs you will observer several green links. Click these links to access relevant VS SDK help located online (from the MSDN Web site)

Getting Started

MS Help 2 (.HxC) project files differ from the older MS HTML Help (.HHP) project files. MS Help 2 project files keep their list of content files in a separate (.HxF) Include file. Also, with MS Help 2 you must specify every file you want included in the final .HxS Help file (with HH 1.x the compiler would auto-included files for you). The TOC and Index information are still kept in separate files, but are now .HxT and .HxK XML files. URLs for the Home page, Default page, etc are now defined in yet another Index file typically called NamedURL.HxK.

All project file are now in XML format. These can be viewed in a text editor and are reasonably easy to read. The MS Help 2 SDK (VSHIK) documentation describes their format. You will find plenty of documentation about XML on the web. The MSDN web site is a good source of XML info.

.HxC Project definition file. Contains all project settings and references to other project files. This is the file type you load into this editor.

.HxF Include file. Contains a list of content files to be compiled into the final .HxS help file. The Collection-level files do not need a HxF file.

.HxT Table Of Contents definition file.

.HxK Index definition file. Each Index file is given a unique "Index Name". It's very important to get the Index names right. It's the Index Name, not the file name, that defines the type of index. Name "K" is typically used for the Keyword Index; Name "A" for the Associative Index; Name "NamedURLIndex" for the Named URL index - it contains URLs for the HomePage, DefaultPage etc. Name "F" for the Context help mapping Index; All these index files are optional since index entries can be embedded directly into topics (.HTML) files.

Read about others Hx? project file types in the MS Help SDK documentation:
http://msdn2.microsoft.com/en-us/library/bb164947(VS.80).aspx

Unicode Support

Unlike MS HH 1.x, MS Help 2 now supports Unicode. Use "File > Save As" to change the file encoding of the current project. When you change the HxC file encoding, FAR will ask you if you want to change the encoding on all other associated Hx? project files.

Tip: For those working with foreign language characters you may find that ASCII files causes compile errors. In this case try converting your files into UTF-8 format.

Read more about Unicode support.

File Menu

The two Wizards included in the File menu provide a fast and painless way to create projects or collections. They do the same job as this window does except they automate and simply the process. You may find (as we have) that the Collection Wizard is actually more useful than manually creating the collection level files.

New - Create a new .HxC project file. When the Open dialog appears, select a folder, enter a new .HxC project filename and press the Open button. If you enter an existing .HxC project file then the standard Open action will be performed.
Open - Loads the selected .HxC project file into the H2 Project Editor.
Reload - Reopen a previously loaded project file. Newer files are on the top of the list. The top item is the currently loaded .HxC project file. You can also click the reload toolbar button to reload the current file. If there are unsaved changes you will be prompted to first save the current project to disk.
Save - Save editor settings in memory, permanently to disk.
Save As - Save editor settings to a different .HxC disk file. Internal references to other component project file are not altered. Note that the Save As dialog (like Win2K/XP Notepad) has an encoding drop down list. Use this to change the encoding of the file.
Help Project Wizard - New to MS Help 2? Let the Help Wizard guide you in creating your new project and compiling it into a .HxS help file.
Collection Wizard - Get full assistance in creating, registering and shipping a multi-help file collection. If you plan to integrate your help into say ms.vscc or borland.bds then you must create a collection (even if it contains only one help file).
View Source - Displays the current .HxC project file loaded, in the preferred text file editor (See Preferences dialog - F12).
Windows Explorer - Opens Windows File Explorer at the project folder (folder containing the .HxC file loaded).
Exit - Close this window.

Command Menu

Edit Include file - Opens the specified .HxF include file for editing. If more than one .HxF file is defined in your project (this is allowed), you can edit specific .HxF files by selecting them first on the "Project Files" page, or by double-click them. See Note#1.
Edit TOC file - Opens the Table of Contents file (.HxT) in the FAR TOC & Index file editor. Again if more than one TOC is specified then edit from the "Project Files" page.
Edit Index file - Opens the Keyword Index file in the FAR TOC & Index file editor. Again if more than one Index is specified then edit from the "Project Files" page.
Compile - Same as command button on the Compile page. Evokes the MS Help 2 compiler. Note that the MS Help SDK must be installed to compile.
View Compile Log file - View the compilation output in a text editor.
Auto-Register Collection - Automatically registers your collection. Does same action as the Auto-Register in the Register page.
Register Collection - Opens the FAR H2 Register window so you can manually register your collection.
View Collection - After compiling and registering stages are complete, use this to open the collection in the specified Help file viewer. Does same action as the View Collection button in the View Page.
H2 Utilities - Opens the FAR H2 Utilities window.

Note#1 - This command is disabled when editing "collection-level" HxC files. Collection-level files do not require content file lists, nor can they be compiled.

View Menu

Previous / Next Page - Move between editor pages.

Help Menu

Help - Displays this help.
MS Help 2.x Error Info - Opens a page containing info about all compile time errors. H2 SDK must be installed.
Show MS Help SDK documentation - Also known as Workshop help or VSHIK help. Configure the viewer in the FAR preferences dialog (Press F12).

H2 Project Page

About Project Types
There are two types of HxC files. The first type can be compiled to a help (.HxS) file. The second type is a "collection-level" .HxC file. Collection-level files (.HxC, .HxT, .HxK, .Hx?), are shipped uncompressed, and define how the .HxS help files merge together at run-time.

About Collection-level .HxC files:

Are not compiled.

Are shipped uncompressed, along with other associated collection-level .Hx? files.

Look like normal HxC files, but contain no compiler settings (or compile settings are ignored).

The Hx? files do not use a DTD file. Example: A HxC header will be
<!DOCTYPE HelpCollection> instead of
<!DOCTYPE HelpCollection SYSTEM "MS-Help://Hx/Resources/HelpCollection.DTD">.

Collection-level files do not require a HxF include file.

The Project page allows you to select the HxC file editing mode:

Create a Project .HxC file used to compile a (.HxS) help files.

Create a Collection. Create a set of Collection-level files.

You'll pick it up as you go along.
Use 1) to create help (.HxS) files.
Use 2) if you want to create a multi-help file collection. Only this type of collection can plug (Merge) into another collection such as ms.vscc or borland.bds.

When moving between editing modes some fields and pages will be disabled or become hidden. The Compile page is only available in mode 1 although in Mode 2 the editor does allow you to list your collections Mode 1 projects and compile them as batch compilation.

Wizards:

If you get stuck then use the wizards instead of manually setting up things in this project editor window. The first Wizard guides you in creating a help project. The second guides you in creating a collection. The second is a late addition to FAR. We find it extremely useful and now create and register all our collections using the Collection Wizard.

Types of Registration:

Single Help file Collections Ship only the compiled help file. At install time register (under a unique Namespace) the single HxS help file as both the collection file and the collection help title. This kind of collection can NOT plug (merge) into another collection. So its main use is for test purposes.

Multiple Help file Collections Ship all compiled help files (created in mode 1) and the Hx? collection-level files (created in mode 2). At install time you register (under a unique Namespace) the collection-level .HxC file as the main collection file, then register all the compiled help files as collection help titles. Make sure the collection-level HxT includes all help titles (by registered TitleId) so they appear in the master TOC.

Collection-level Hx Files: (Edit Mode 2)

Table Of Contents (.HxT) The collection-level HxT file typically contains include file statements. Example: An include statement of "TestCol1" will cause the TOC of the Help Title (.HxS file) registered under a Title ID of "TestCol1" to be included into the master TOC at run-time.

Index (.HxK) Each collection-level Index file is normally gutted of all Name-Value data pairs. The important thing here is to specify the correct INDEX NAME. The name can be edited using a text editor. Example: <HelpIndex Name="K" ...>. The name "K" specified as a "Keyword Index" in the Navigation Page, tells the system that at run-time, all K Indexes found in the help files, should be merged together to form a single Keyword Index.

Include File (.HxF) Don't use .HxF files in Edit Mode 2.

See SDK Help for further information:
http://msdn2.microsoft.com/en-us/library/bb164947(VS.80).aspx
http://msdn2.microsoft.com/en-us/library/bb165287(VS.80).aspx

General page

Title - This text will be displayed in the title bar of the help viewer that displays the final .HxS help file.
Collection ID - Option text sets the XML ID tag for the .HxC file. Ignored by help compiler.
Version Numbers - When you right-click a .HxS help file and select properties, you will see an author defined four segment version number.

Check the Auto-Increment check box if you want FAR to automatically increment the last version number every time you perform a compile. See Note#1.
Copyright - Enter any required copyright message here.

Note#1 - Checkbox is disabled when editing collection-level HxC collections.

Project Files page

Project File List - Add all required project files to this list. Right-click for the options menu. Typically you will need to add a .HxF Include file (Collection-Level HxC only: HxF contains your list of topic, image etc files), a .HxT Table Of Contents file, a HxK Keyword file named "K" (containing Keywords for the index navigation tab) and a HxK Index file named "NamedURLINdex" containing URLs for HomePage, DefaultPage etc.
Popup Menu commands (Right-click the list):

Edit - Edit the selected file. At the moment FAR provides a simple .HxF editor, and a .HxT & .HxK TOC and Index Editor. Other .Hx? file editors will follow, for now use a text editor or 3rd party tool.

Edit As Text - Loads the selected file into the default text editor (See Preferences dialog - F12).

Open In IE Browser - This is a good way to check for syntactical errors in your XML file.

New Project File - Opens the New Project File wizard dialog. This dialog helps you to create fully functional .HxF, .HxT, HxK files. The Index files are given default Index Names which you can change if required. The Named URL Index is setup with the default Named URLs. You will need to edit this and define the HomePage and DefaultPage URLs.

Add - Allows you to add an existing .HxF, .HxT, .HxK etc file into the file list.

Remove - Remove a file from the list. The file is NOT deleted from hard disk.

Change File Encoding - Change the file type to ANSI/Unicode/UTF-8.

The Project List itself contains a File Type column. This displays the File Encoding of the file so you can see at a glance if your project files are ANSI/Unicode/UTF-8 encoded.

As project files are added, FAR tries to automatically setup the appropriate Navigation page setting for you. EG. Add a Index file named "K" and if the Keyword Edit field (Navigation Page) is unassigned, FAR will assign "K" to it.

Note that all project files you add to this list, are automatically included in the final .HxS help file at compile time. Project list files need not be added to the HxF include file.

The .HxF include file may contain wild cards such as *.*, *.htm, images\*.*, etc. Enter these type of file entries via a text editor (select "Edit As Text" from the popup menu), as the supplied HxF editor only supports entering real filenames.

HxF include files are NOT required in project edit mode 2 (collection-level file editing).

HxF Project file Example:

<?xml version="1.0"?>
<!DOCTYPE HelpFileList SYSTEM "MS-Help://Hx/Resources/HelpFileList.DTD">
<HelpFileList DTDVersion="1.0">
    <File Url="*.gif"/>
    <File Url="*.htm"/>
    <File Url="*.html"/>
    <File Url="*.jpg"/>
    <File Url="images\*.gif"/>
    <File Url="images\*.jpg"/>
    <File Url="test\tester.htm"/>
</HelpFileList>

HxK Named URL Index Example:

<?xml version="1.0"?>
<!DOCTYPE HelpIndex SYSTEM "MS-Help://hx/resources/HelpIndex.DTD">
<HelpIndex Name="NamedUrlIndex" DTDVersion="1.0" FileVersion="1.0">
<Keyword Term="HomePage">
    <Jump Url="dl.htm"/>
</Keyword>
<Keyword Term="DefaultPage">
    <Jump Url="dl.htm"/>
</Keyword>
</HelpIndex>

Navigation page

Each Drop down list contains entries from "Project Files" page.

Table Of Contents - Select the required TOC file from the drop down. If a .HxT TOC file is not available in the drop down then you must add one on the "Project Files" page.
Keyword Index - Optional. Select the required Index from the drop down. If the required Index name (typically "K") is not available in the drop down, then you must add one on the "Project Files" page. The Keyword Index is a visible index. At run-time it is displayed in the Index of the navigation pane of the help viewer.

About Index Files:

Notice that the actual .HxK file is not listed here, but instead the "Index Name" defined inside the .HxK file (see page tab 2 of FAR Index Editor). This is the way that MS Help operates. We need specify an Index file indirectly using its Index Name. If you added several index files to a project, and gave 3 of the files an index name = "K", and selected "K" as your keyword index, then these 3 files would be merged together to form one Keyword index at run-time.

Index Dropdown Controls:

Holding the mouse pointer over any of the index controls will display the name of the file(s) using the selected index name. The other index drop down fields should always use different Index Names. The Index Name of a .HxK file can be changed in the TOC and Index editor (page tab 2).
Named URL Index - This is required if you want to define HomePage, DefaultPage at the project file level. Typically the Index Name is "NamedURLIndex". Remember all these Index file settings can be defined within the topic files, using XML data islands, instead of in .HxK Index files. In most cases however it is best to create a NamedURL Index file.

Typical items in the Named URL Index are -- HomePage, DefaultPage, NavFailPage, AboutPageInfo, AboutPageIcon, FilterEditPage, HelpPage, SupportPage, SampleDirPage, SearchHelpPage. Most of the time HomePage and DefaultPage are all you will need to use. See your MS Help SDK documentation for further information.
Associative Index - Optional. ALinks in MS Help 2 work the same as they did in MS HTML Help. Typically we give an Associative Index file the Index Name "A". Explaining the meaning of ALinks is beyond the scope of this help.
Context Window Index - Optional. This index is typically named "F". Like all indexes it contains a list of Name-Value pairs but in this case we have "TextID-URL" pairs used for context help mappings. Remember in MS HH 1.x we used "Integer HelpContext ID - URL" mapping. MS are moving way from "IntegerID-URL" type mappings to these new "TextID-URL" mappings.
Create Full-Text Index - Check this if you required Full Text Search information - FTS information will be available at run-time in the search control (navigation pane) of the help viewer.

You can set the FTS Moniker InitData field if you want. At the time of writing this setting has no known effect on FTS for single or multi-file collections. Although an empty string stops FTS from working in early versions of MS H2.
Stop Word File - Specify a .txt file containing a list of words which should be ignore when the user performs a full-text search. No special formatting is required. Each word should be on a new line in the text file. The Stop Word filename normally has path relative to the HxC's project directory. You can however use an absolute path.

Typically the stop word file is created in the project folder where the .HxC project file resides. If you use a relative path that begins with "..\" you will get a compile time warning, however this is only a warning and the stop list will still seems to work. Note that the Stop list Open file dialog has checkbox "Store as full path" so you can use a full path or relative path.

Note: This control is not available in Edit Mode 2.

Edit Mode 2 (run-time collections)

Collection-level index files can be guttered of index items. Only header items are required.
Collection-level TOC files normally contains one or more include statements. These statements reference TOC files in the help titles. Normally all that is required is to enter the help TitleID. Example: A help TitleID "Fred" containing TOC "ms-help://mynamespace/Fred/contents1.hxt" can be included via a TOC include statement "Fred".

Appearance page

Here you set Font and Language information. The sample area at the bottom of the page contains sample text (which you can changed).
Font & Font Size: The font info is not actually used by the help viewer. It is currently stored in the .HxS help file and could be retrieved if necessary.
Language - Like the MS Help SDK, this drop down list contains all supported language codes. When a new language is selected, the corresponding Character Set is also selected below it. Note the reverse is not true - Changing the Character Set will not change the Language setting.

Compile page

Mode 1 Editing - Project-Level

These settings are used at compile time by the MS Help 2 compiler. This page is not available when editing a Collection-level .HxC.

Output (.HxS) File - Specify the name of the .HxS help file to be created when the compile is performed.

Output File Type - Normally you create a Single .HxS help file. The single .HxS file has the .HxI index file information compiled into it. The setting "HxS with separate .HxI" will cause the compiler to create a .HxS help file and a separate .HxI Index file. There is no harm in always using a separate .HxI file however it makes registration and installation more complex.

Log File - All compiler output is saved to the specified log file.

Log Level - Allows you to reduce the size and detail of the compile log.

Compile Project - Evokes the MS Help Compiler to generate a .HxS (and .HxI if specified). The MS Help SDK must be installed for compile to work.

View Log File - View the log file in your text editor.

Mode 2 Editing - Collection-Level

MS Help collection-level files cannot be compiled to anything. They simply define how the collection (document set) hangs together at run-time. However in Collection-Level Editing, FAR allows you to optionally setup a list of HxC Projects files (used to create HxS Help files). These can are compiled as a single batch job when you hit the compile button.

Log File - When compiling all files in the Projects list, the combined output is sent to this file.

Log Level - Allows you to reduce the size and detail of the compile log.

Compile All Projects - Compiles all projects in the Projects list.

View Log File - View the combined compiler log file in your text editor.

Projects page (Mode 2 only)

The projects page is only available in Mode 2 editing. You can add any HxC or HxM project files to the list and when you press Compile FAR will compile them all. When you press Auto-Register FAR will register them all. We did this so you can open one file and compile all of its associated project files that create HxS, HxI, HxR and HxQ files, in one go.

Some notes on format and order:

You can add full or relative paths to the list. Full paths are simply more portable, while relative paths are easier to use. You can toggle between full and relative paths by using the lists right-click popup menu.

You can add HxM files (used by HxMerge.exe to make HxQ and HxR combined query files). These will normally come last in the list since the HxM needs the HxS Help files to be compiled first, as it needs then to build the HxR/HxQ combined query files.

When performing an Auto-register, FAR registers each title, and will also add to the title HxR or HxQ files if they are found down the list below the titles project file. If you don't want HxR, HxQ files to be linked to a HxS file at registration time, then the HxM files must be moved up in the list above the titles HxC project file. If you really have troubles, then use the separate Batch Compile window to make several batch jobs.

Information on the controls and functionality of this page can be found in the Batch Compile window help. The only differences for the H2 Editors batch compile page are:

The Projects list is stored inside the HxC Collection-level file. The batch compile window stores its list in a .fbat file.

You can specify the name of the log file (on the Compile page). The batch compile windows log filename is fixed.

The projects list right-click popup menu contains a few extra commands. Including commands to import/export the list from/to a .fbat file (The format used by the FAR batch compile window).

There is also an Expand command so you can see more of the list. Press F3 to toggle the list size.

Register page

MS Help 2.x help files can only be viewed once they are register. This page helps you to quickly register a collection so you can test it.

Namespace - Each help collection is referred to by a text label called a Namespace.

Namespace Description - Optional description for the Namespace.

TitleID - Each help file registered under a collection (Namespace) must be given a unique Title. This is only available when creating and testing compiled HxS files (Edit mode 1). The TitleID is also used when you perform a Batch Compile (in Edit Mode 2 or the FAR Batch Compile window).

Note that at the time of writing spaces within the Namespace or FileID Identifiers cause big problems. Try to avoid spaces.

Auto-Register button (Edit Mode 1) - The HxS help file is registered using the Namespace/FileID/Desc above. Note that each collection must have a unique Namespace name. Each Help File within a Collection must have a unique FileID for that collection.

Auto-Register button (edit Mode 2) - Registration of multi help file collections is a little more complex. We need to register the namespace, then register to that namespace all the Titles (HxS help files) that make up the collection/document set. Luckily FAR Auto-Register makes easy work of this. FAR first registers the specified Namespace/Description, then runs through the list in the Compile>Projects page adding all the HxS files (created by the projects) as Titles to the Namespace.

Register Window button: Use the Register window to manually register Namespaces/Titles/Plug-ins.

Tip: To check which Namespace and FileIDs are in use by other collections, open the H2 Utilities window from the Commands menu. It is a good idea to prefix your Namespace with your company or product name. EG. "MS.VSCC"

View page

View Collection - View your collection in the viewer of your choice. The collection to viewer is specified by the Namespace field in the Register page.

HxS Viewer - Specify the full path (or relative path) to the executable used to view the compile help file. If this field is left blank then the default viewer as specified in the Preferences dialog (press F12) is used. The drop down list contains all the viewers you have specified in the Preferences dialog (F12).

Viewer Params - Specify any command parameters used by the H2 Viewer. This line must contain the text "$NAMESPACE" - at run-time this is replaced by the Namespace you specified in the Registration page. Note that if you select a viewer from the dropdown list of available viewers (above), then this field will be updated to match the selected viewer.

Toolbar

The items in the tool bar are shortcuts to the most popular menu and button commands.

	There are many features of MS Help that neither Workshop or FAR have begun to touch on. Keep an eye on the Helpware web site for FAR updates. http://www.helpwaregroup.com/products/far
	Remember information on how to create Virtual Topics, Samples, Attribute definition files etc are detailed in the MS Help SDK documentation. Like Workshop, FAR will not inhibit you from using these advanced features of MS Help.

http://www.HelpwareGroup.com/

.HxC	Project definition file. Contains all project settings and references to other project files. This is the file type you load into this editor.
.HxF	Include file. Contains a list of content files to be compiled into the final .HxS help file. The Collection-level files do not need a HxF file.
.HxT	Table Of Contents definition file.
.HxK	Index definition file. Each Index file is given a unique "Index Name". It's very important to get the Index names right. It's the Index Name, not the file name, that defines the type of index. Name "K" is typically used for the Keyword Index; Name "A" for the Associative Index; Name "NamedURLIndex" for the Named URL index - it contains URLs for the HomePage, DefaultPage etc. Name "F" for the Context help mapping Index; All these index files are optional since index entries can be embedded directly into topics (.HTML) files.

Table Of Contents (.HxT)	The collection-level HxT file typically contains include file statements. Example: An include statement of "TestCol1" will cause the TOC of the Help Title (.HxS file) registered under a Title ID of "TestCol1" to be included into the master TOC at run-time.
Index (.HxK)	Each collection-level Index file is normally gutted of all Name-Value data pairs. The important thing here is to specify the correct INDEX NAME. The name can be edited using a text editor. Example: <HelpIndex Name="K" ...>. The name "K" specified as a "Keyword Index" in the Navigation Page, tells the system that at run-time, all K Indexes found in the help files, should be merged together to form a single Keyword Index.
Include File (.HxF)	Don't use .HxF files in Edit Mode 2.