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.
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)
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:
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.
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.
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.
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.
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:
Note#1 - Checkbox is disabled when editing
collection-level HxC collections.
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).
<?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>
<?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>
Each Drop down list contains entries from "Project Files" page.
Edit Mode 2 (run-time collections)
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.
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.
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.
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 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.
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.
|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.|