TOC & Index Editor

Introduction | Tree Control | Main Menu | Page Tabs | Other Info

This dialog is available from "Authoring menu (main window) and from the "HTML Help Wizard" and "HTML Help Project Editor" windows.  Alternatively right-click a TOC or Index file in Windows Explorer and select "Open With FAR".

Introduction

Help sections relating to only MS HTML Help 1.x are marked as [HH 1.x only] and sections relating to MS Help 2.x (Visual Studio help) are marked as [H2.x only]. Please refer to the MS Workshop/SDK help for further detail on editing MS TOC and Index files.

As you load different file types into FAR, some controls and menu items will become disabled or invisible. The TOC menu is always called "TOC" even when editing index files.

| File Types | File Encoding | Additional Features | FAR Indexing | Multi-Select | Special Keys |

File Types

The TOC and Index Editor supports the following file types.

.hhc MS HTML Help 1.x Table Of Contents (TOC) file.
Ref: its:htmlhelp.chm::/dscnt.htm
.hhk MS HTML Help 1.x Index file.
Ref: its:htmlhelp.chm::/dsidx.htm
.hxt MS Help 2.x Table Of Contents (TOC) file.
Ref: ms-help://ms.vshik.2003/dv_mshlpwrk/html/hxgrfMicrosoftHelpProjectFiles.htm
.hxk MS Help 2.x Index file.
Ref: ms-help://ms.vshik.2003/dv_mshlpwrk/html/hxgrfMicrosoftHelpProjectFiles.htm
.toc TOC files have a WinHelp type file structure and were used in an discontinued product.
Ref: #FAR .toc files


Note that FAR can also import and export a number of other file formats (see File menu).
File Encoding

MS HTML help 1.x (.hhc/.hhk) supports only ANSI.
MS Help 2 (.HxT/.HxK) supports ANSI, Unicode and UTF-8 file encoding.
Use "File > Save As" to change the current files encoding. Read more about Unicode support.

Additional  Features

FAR TOC & Index editor supports most Workshop/SDK features plus these additional features:

One of the main difference between HH Workshop editor and the FAR editor, is that Workshop tends to hide links and settings away in property dialogs. FAR on the other hand lays it all out in the open.
FAR Indexing

Having trouble moving from Workshop Index editor to FAR Index editor?
These short tutorials were written by friends of FAR:

Multi-Select

FAR offers limited multi-select options for the tree control. Multi-select is used by the delete, drag and drop and Cut/Copy/Paste commands, as well as the TOC Icon dropdown list. To select more than one item, hold down the SHIFT key then either click the mouse or use your keyboard arrow keys for a contiguous list of selections. To create a non-contiguous list of selections hold down the CTRL key then click the required items.

You will notice that only TOC items at the same level can be selected. You can not select both a parent and child nodes at the same time.

Note also that you only need to drag the root item of a branch in order to move the entire branch. IE. Multi-select is not required to move a branch and all its sub items.

Special Keys

These special keys are not mentioned in the main menu and so need to be mentioned here:

Other special actions

Note: Some TOC keyboard shortcuts require that the Tree control have the focus.

TOC/Index Tree Control

Your objective is to build a Table of Contents or an Index file. The Tree control (left) in someway represents the TOC or Index you want to see displayed in your final help at run-time. Most of the time you will be building the tree structure, saving to disk, recompiling and viewing help. 

You can test the TOC or Index file immediately by selecting "TOC > Test (F9)" [HH 1.x only].

Right-Click the Tree control for quick access to most commonly used commands.

[x] Use Topic Title if Label is Empty

At any time you can delete a Tree entry text and FAR will automatically enter the Title information as found in the linked HTML topic file.

MS Help 2 HxT file

Since .HxT files do support blank entries, they have a "<Title>" prefix added to indicate that the item is really blank and the Title will be extracted from the linked HTML topic file at run-time.

This design time feature requires that "Use Topic Title if Label is Empty" (Entry Page) be checked.

Rules applying to MS Help 2.x [not MS Help 1.x]]

In MS Help 2.x TOC (.hxt) files you don't have to specify a TOC entry label (tree control label). If you leave the entry blank then Help will instead use the Title info found in the linked HTML topic file. Both Workshop and FAR display these items as "<Title>xxx", where xxx is the title extracted from the linked topic file.

The following rules apply to finding MS Help 2.x Title information in the header section of an HTML file. For a Table Of Contents (.hxt) use the title declared with <MSHelp:TOCTitle> if defined, else use <MSHelp:RLTitle> if defined, else use the standard HTML <Title> tag info. 

For Index (.hxk) files only result items will show "<Title>xxx" labels. That is items marked as Popup List Items. Index (.hxk) files use <MSHelp:RLTitle> if defined, otherwise they use the standard HTML <Title> tag info. Similarly all FTS (Full Text Search) results use <MSHelp:RLTitle> if defined otherwise they use the <Title> tag info.

Main Menu

Sections: File | Edit | TOC | Options

File Menu
Edit Menu
TOC Menu
Special - Some miscellaneous commands:
Options Menu
Page Tabs

Pages: TOC Entry | Properties | Help 3 | Files | Chm Files | File System | Preview

TOC/Index Entry Page
Add, Drag & Drop Mode Effect how items are inserted into the TOC.
See also Edit > Drag & Drop Mode.
TOC Entry Setting  (*.hhc, *.hxt, *.toc files)

The following settings relate to each tree node. As you select each tree node you will see the information in this group box change. To edit TOC Entry settings first select a tree node. 

Fields Alternate, Window and Frame fields are not available in MS Help 2.x editing. 

Icon Highlight one or more tree items then select which Icon to use. 
Note: When editing .HxT files [H2.x] you can specify a set of custom icons on the Properties page. Custom icons were never fully supported in HH 1.x help.
Reset The Reset button is a quick way to set the Icon back to the default value.
Link Highlight a tree item and enter a topic link for that node. This is  normally a relative path to a local topic file, or a path to a web based document (http://server/htmlFile), or a file in a CHM help file (its:helpfile.chm::/path\file.htm) [HH 1.x only], or a file in a HxS help file (ms-help://namespace/file/docpath/file.htm).
Alternate [HH1.x only] Enter a path to use if the Link field (above) fails.

Example:  Link to a topic in another chm file using "its:file.chm::/topic.htm". If the chm is not found then HTML Help will use the Alternate link. The Alternate link may be to a file that simply says "Help module xx.chm is not installed".
Window [HH1.x only] Specify the HTML Help window definition to use.
Example: You may want the link topic to open in a HH secondary window. Secondary windows can be defined in the HH project editor.
Frame: [HH1.x only] Specify a Window target just like in HTML editing.
Example: Set the Frame to "_Blank". This will open the link topic in a new Internet Explorer window. Very handy if the link is to a web site and you want to see the page load progress information.
Index Entry Setting (*.hhk, *.hxk files)

When you are editing Index files you will see the following settings. Again, for HxK Index files (MS Help 2.x) the Alternate, Window and Frame fields are not support and so are hidden: 



Most of the settings are the same as they are when editing TOC files (above). Notice though that the Icon select control has been replace by three new checkboxes.

Popup List/Popup List Items checkboxes

Instead of Index items linking directly to HTML topic file you can link them to a result list of items, or to another index item. 

Look at the picture on the left. Books has the "Popup List" checkbox selected. Flight and Fishing entries both have the "Popup List Items" checkbox selected. MS Help will only display the single entry "Books" in the index at run-time, which when selected will display a popup list containing items "Flight" and "Fishing". "Books" does not require a link to be set.

Note: If you open the .HHK Index file in HH Workshop, "Flight" and "Fishing" will not be seen in the Workshop Index edit control. This is because Workshop hides these settings away in a dialog.

Notice that "Automobiles" is also on the same level as "Flight" and "Fishing" but is not a list item. It will appear indented under Books.

So here is the final compiled index. Our two items marked as "popup list items" are not visible until "Books" is double-clicked, then they are displayed by the help viewer in a results window.


 

MS Help 2 Index Note:

In MS Help 2.x (.hxk files) the popup list item labels ("Flight" & "Fishing") are extracted from linked topic file at run-time. You cannot define the visible labels in the .hxk file. The editor displays them as "<Title>Flight" and "<Title>Fishing" to indicate that the text has been extracted from the Title information found in the linked HTML topic file. The text "<Title>xxx" is not stored in the .HxK file. Thus if you move the .HxK Index file away from the other files, or specify an invalid link, it will appear blank. If you do see text other than "<Title>xxx" on a popup list item, press F2 and delete the text. FAR will automatically enter the "<Title>xxx" label if a linked file is found and contains valid Title information.

Link is another Keyword checkbox:

Select this check box to indicate that the Link entry field actually defines a keyword to link to and not an HTML topic file as it normally does. In our screen capture (left) the "Golf" entry is marked as a "Link to another Keyword" item.

 

Example: If the "Golf" link field contains the keyword "Books", then double-clicking the "Golf" item at run-time would move the selection up to the "Books" Keyword entry. Why would we do this? The example above is poor, but typically you might want to move the user to the area of the index that contains a bigger group of links relating to Golf. 

Indention:

Some authors like to stagger their index entries over 3 or 4 levels like in a TOC. This provides a nice way to group entries but creates a very long list to scroll through. Unlike the Table Of Contents you cannot expand and collapse index levels at runtime. Consider using popup items for the deeper levels.

Tip: If the parent node contains a blank link you will find that the HTML Help viewer hides the node at runtime. To avoid this set the node type to "Link is another keyword (F8)" and link to itself. For example a keyword called "Golf" would simply link to "Golf". When the user double-clicks "Golf" nothing will be seen to happen (Thanks Kelly Holcomb from BMC for that great tip).

See Help Workshop for further information on creating indexes.

Link File Options

Topic <title> / Set Label  (See Note#1)

This field display the link file's topic title. FAR extracts the <title> tag text when you click on a tree item.
Click "Set Label" to set the selected tree entry label using the Topic Title text.

"Use Topic Title if Label is Empty" checkbox (See Note#1)

See also MS Help 2.x HxT and HxK files.

If this control is checked, then entries with blank labels are replaced with the titles extracted from the Topic file. EG. Try deleting a tree label (when this control is checked) and the label will be set automatically to the link file's topic title.

You would normally leave this checked, however some big .HxT files containing thousands of empty labels may load too slowly. This is because each link file must be opened and the title information extracted.

Validate Links - This is a repeat of the "TOC > Validate Links" menu command (also in main toolbar).

Toggle this command to enable/disable automatic validation of TOC/Index link entries. If a TOC entry link or alternate link points to a non-existent file a red cross appears next to the TOC entry icon. A red question mark will appear next to entries that cannot be tested such as http:// and ftp:// links.

Additional Validate Options: Allows you to check additional link conditions (When Validate Links is checked). These options are especially useful when authoring MS Help 3.x which requires: No Empty links; No Bookmarks; No Duplicates; And all link files included in the FAR File list (main window).

The checked settings work only when the "Validate Links" button is down (checked).

Note that some options cannot be shown at the same time. EG. Files not in FAR List marks tend to override Bookmarks or Duplicate File Links marks. So sometimes you may need to view Files not in FAR List results separately from the other options.

Mark If Not <title> - Marks all entries with labels that don't match their link file <title> text.  This command is also available from the TOC > Special menu. This is for authors that want to make their TOC or Index labels the same as the link file <title> text --  I.E. <title>text</title>.

Edit - Click to edit the selected tree item in the editor of your choice. Similar to clicking the Edit button in the Preview page.

Note#1: For MS Help 2 files the document title is not always the <title> tag text.  See MS Help 2.x HxT and HxK files.

Properties Page

These are general properties that effect the entire table of contents or Index. This page will change significantly when loading different file types.

HTML Help 1.x has the following problems.

A number minor features in HTML Help were never fully completed by MS.

  1. The Background color option was not completely implemented. You may find it useful even with the obvious cosmetic defects.
  2. TOC styles. Some work some don't. Some require an international versions of Windows.

.HHC (HH1.x TOC File):

.HHK (HH1.x index File):

.HxT (H2.x TOC File):

.HxK (H2.x Index File):

See Workshop/SDK help for more info. Some MS Help 2 fields require XML compliant strings. If you stick to 0..9,a..z,A..Z,. and avoid spaces you should be fairly safe.

Help 3 Page [Help 2.x Only]

The Help 3 page TOC fields are available only when a Help 2.x .HxT file is loaded.
Note that the Help 3 Import and Export commands are always available from the File menu.

See also
MS Help 3 Primer
http://kb.helpwaregroup.com/ms-help-viewer

MS Help 3 TOC & Index file format

H3 TOC and Index data is embedded inside HTML topic files using meta tags. Editing these meta tags directly would be very tedious, so FAR allows you to Import meta tags, Edit as .HxT/.HxK files, then Export back to topic meta tags. When you do this it's important that all project HTML files are listed in the FAR File list (FAR main window) so that meta tags can be added or removed.

.HxT and .HxK files are MS Help 2.x TOC and Index files. These files support Unicode unlike Help 1.x .HHC/.HHK files. We recommend you maintain your TOC and Index data by storing them in .HxT and .HxK files. Why? If you remove just a simple topic file from the project, or disturb the meta tag data accidently, you can trash your entire TOC. So please store your TOC and Indexes as .HxT and .HxK files, exporting out as meta tags whenever required.

Note: We that we store some H3 TOC attributes (from this page) in the Help 2.x .HxT file. This wont upset the Help 2.x compile as the data is stored as H2 tooldata (nice feature of .HxT files). But if you edit these files in a 3rd party editor you could loose this info if the other editor does not respect tooldata.

Project Topic Files

Since TOC and Index are defined in your projects HTML files, the Editor needs access to all project HTML topic files. These files should be loaded into the main FAR file list before you perform either an Import or Export. To make this easy you can save the list to a .FAR file (see FAR main window) so you can reload your project files easily at any time. Or you can quickly load all HTML files in a folder, and its sub-folders, by clicking one of the speed links provided ("Add HTML files now" & "Change FAR folder").

Load & Save Help 3 TOC or Index

To load your H3 TOC or Index either click "Import from Meta Tags" or open a .Hx? file you previously saved. It's up to you how you maintain your H3 TOC and Index data.

The Import dialog asks you to select the type Meta Tag to import from the HTML files.

When you are done editing your TOC or Index click "Export to Meta Tags" to update your Topic file meta tags (from the Editor info). Notice again the Export dialog asks which type of meta tags you want to update.

TOC Node Attributes

Use these 4 fields to define attributes for the top level items. These define where and how your TOC will parent into the host TOC. For level 2..n TOC nodes the parenting is already defined of course with the TOC design tree.

Parent ID:  Specify the Help ID (TOC Topic) that will host and parent your TOC. Typically an MSDN TOC topic. An ID of "-1" can be used to parent into the top level of the host TOC.

Every HTML document must have a unique Help ID defined via a meta tag <meta name="Microsoft.Help.Id" content="UniqueValue">. Do a "View Source" on a VS/MSDN topic to find the Help ID you want. Both Microsoft and FAR often use GUIDs for IDs since these are almost guaranteed to be unique.

TOC Order: 1..n. Allows you to specify where in the host TOC your TOC will appear. IE. The order among surrounding sibling nodes.

 

Editing H3 TOC Files

In normal TOC editing you can edit the TOC labels and various H2 Properties. In Help 3 editing the TOC node labels have no meaning since document <title> tags define the labels. You will notice that when you Export then Import, the labels will all revert to the document titles.

For more information see MS Help 3 Primer.

Editing H3 Index Files

With HH 1.x and Help 2.x we had "Link to Another Keyword", and "Popup lists". MS Help 3 does not support these link types. When you Export your Index you will find that FAR converts these into standard links.

Only 2 levels are support in Index hierarchies (Even though the FAR TOC & Index Editor allows you to author more than 2 levels).

For more information see MS Help 3 Primer.

 

Files Page

This powerful feature allows you to check which HTML files have not yet been used (linked to) by the TOC (or Index). Click Refresh button to populate the list with files.  Use your mouse to drag and drop files from the file list onto the TOC (or Index) Tree control. After updating the main tree control you will need to click Refresh once more to updated the file list.

Current Folder: In this mode we search for files in the folder (and sub-folders) of the current TOC or Index file. Search uses the Global Search Filter (see Main window > Preferences dialog). The Global Search Filter ensures that you do not see FrontPage VTI, back up files or any other unwanted files in the list.

FAR File List: In this mode the file list is built from the FAR file list (main window).

Filter Dropdown: Allows you to filter the list of files. The most useful filter is "Unused HTML Files" which shows only those HTML files not currently used in the TOC (or Index).

Refresh: Press this button to refresh the list of files.

Note: The right-click menu contains extra file commands.

Chm Files Page [HH1.x only]

The Chm Files page is available only when a .HHC or HHK file is loaded.

Select a .Chm file and FAR will display the files stored inside that Chm file in the list control. Drag and drop any of the list items onto the Tree control. Drag and drop .hhc TOC files to add Include entries to the TOC designer control.

File System Page

This page allows access to the file system. Double click folders to move down into the directory system.

You can drag and drop files onto the Tree control.  Multiple files can be selected by using Ctrl+Click or Shift+click. Note: Folder drag and drop is ignored.

Warning: You are really in the file system. If you delete, move or rename files, it is as if you modified them from Windows Explorer. Also the right click menu works as in explorer.

Preview Page

This page contains an embedded Internet Explorer webbrowser control. As you click on each TOC item, the topic is display in the preview page. If you have specified both a link and an alternate link for the TOC item then you can select which link to preview via the two radio buttons (which will appear) above the browser control. 

Detach to Separate Window

To view files displayed in file lists on other page tabs you can detach the Preview Page as a separate window. Close the preview window at any time to restore the preview tab to its normal location. Use the shortcut key F6 to achieve this using the keyboard.

As with Internet Explorer you can right click the browser to access the Internet Explorer popup menu commands. Example: View Source, make changes then click refresh (or press F5) to view the changes. Preview page requires Internet Explorer 4 or above.

The Preview Page toolbar buttons work the same as they do in Internet Explorer except for:

Note: FAR can not always distinguish between URL changes due to clicks on document links, and URL changes due to automatic redirection. If you click links within a document (or hit backspace) and get blocked then either set the button to the Down state, or click the prompt when it appears to allow the URL change.
Other Info

Meta Tags | Umlauts and Special Characters | TOC/Index Meta File | FAR .toc files

Meta Tags

Note: We added a small feature for a user who wanted to create TOC files and have the ICON Index set from information in the header section of the HTML file. To do this we used the Meta name "FarImageNumber".

Example: <Meta name="FarImageNumber" value="12">

Umlauts and Special Characters

This section describes how FAR handles umlauts and other special characters. Just as we "Escape" or encode special characters in HTML documents, we must also encode some characters in TOC and Index files.

Example

 '<' is stored as '&lt;'
 '>' is stored as '&gt;'
 " is stored as '&quot;'

In HTML Help (.HHC and .HHK files) some special characters should be encoded, and some should not. HTML Help is a little inconsistent here. FAR does its best to encode the correct ones. If you see a '?' character appear in your HH TOC and Index navigation pane, where a special character is expected, you may have to Encode or Un-encode the character.

Note: Some more exotic special characters may not work at all (encoded or decoded). These may always display as ? or may require a certain font or Character Set to be set (see TOC Editor properties page).

FAR encodes most special characters except for "«¨¬§©ª/–—…". These do not work when you both encode them and select a character set (properties page). Using the raw un-encoded character works fine however.

In MS Help 2 you may find that you keep getting XML compiler errors. In this case try converting your ANSI files to UTF-8.

At the time of writing, MS Help 2 is still immature and the rules for using special characters are still unclear.

How to stop FAR from encoding certain characters

If a special character is found in a TOC editor tree control label, it is normally encoded when stored to file - Example Ö is stored as '&Ouml;'. You can stop FAR from encoding certain characters. See Settings.ini to see how to do this.

See Also: Menu command: TOC > Special > Encode All Special Chars

TOC/Index Meta File

9-Dec-2005: User Request: I parse our HTML/XML to various folders. When editing the TOC or Index file I want the preview window to open files from an alternate location. Also when I access a file I want the HTML Title to be read from the Preview folder file.

Response: FAR now allows an optional Meta file to be associated with each TOC/Index file. The Meta file is simply a Text INI file which has the name of the current TOC/Index file + ".INI" file extension added.

Notice that when a Meta file is used the Preview Icon (in the Preview page and in the main toolbar) changes:

To Create/Edit/Delete a Meta file simply right-click the Preview Icon (see image above).

Here are the INI commands currently available:

PreviewDir=

By setting this INI file variable you are telling FAR to get files from an alternate folder when previewing HTML files in the Preview page.

For example if I open a TOC file SuperHelp.HHC in the folder c:\projects\Super\
then create a file SuperHelp.HHC.INI (in the same folder) containing the following text (see below). As I click on TOC nodes the preview window will now display the files from under the G:\Help folder instead of the c:\projects\Super\ folder.

Why would you do this? Your source files may need to be pre-processed before IE can preview them correctly.

[MAIN]
PreviewDir=G:\Help
;PreviewDir=http://company.com/help/

ReadTitlesFromPreviewDir=

When you drag and drop HTML file items from a list onto the TOC/Index Treeview, FAR extracts the <title> tag text (HTML Title). Set ReadTitlesFromPreviewDir=Y if you want FAR to read title text from the PreviewDir instead. This command does nothing unless PreviewDir= is set.

[main]
ReadTitlesFromPreviewDir=Y

FAR .toc files

Earlier versions of FAR maintained the table of contents in FAR .toc file format.  The .toc  file has a simple WinHelp .cnt format allowing the user to easily edit the TOC using any text file editor.  The newer graphical TOC Editor makes this file format less important.

You can still save and load .toc files in the newer versions of FAR.  Working with .toc files in a text editor has some distinct advantages:

The down side however is that it is possible to lose some information during the conversion from one file type to another. Only use .toc format if your Table of Contents is simple and straight forward.

Of cause you can also edit .hhc and .HxT files in a text editor but the sitemap / XML formats makes them more difficult to clearly read.

Working in .toc file format

The easiest way to edit your .hhc file in .toc format is to select "File > Edit in .toc Text format".

This command exports the current .hhc/.hxt file to a .toc file using the same file name but with .toc file extension. Once created the .toc file is opened in your preferred text file editor (See main window menu "Options > Preferences").

Make your changes in the text editor, save and exit. When FAR becomes the active program again it will detect that you have changed the .toc file and ask you if you want to import the changes into FAR. Click Yes to pull the .toc changes into the current .hhc or .hxt file.

Other Info

The first lines of the .toc file looks like this: ":Base <homepage>". Replace <homepage> with the name of you webs home page. EG. Index.htm OR default.html OR Myweb\Index.htm. And ":Title <title>", replace <title> with a title you want in the CHM window. These fields are a hangover from old products.

Once you get past the .toc header lines the file looks like a WinHelp .cnt file.   Each line contains a number indicating the indent level (1..n), followed by a space, followed by an entry label, followed by "=" and an option URL, followed by an optional icon index.

Example:

1 FAR Introduction
   2 FAR Introduction=index.htm
1 FAR Dialogs
   2 Main Window=farhelp.htm, 12
   2 Create HTML Help Window=farhh.htm

The example above is indented to make reading easier, however FAR ignores leading spaces. 

.hhc files can carry extra information such as window name and frame target. This info is represented in the .toc file in the same format as in the .hhc file, that is as lines starting with a "<" character.

Example:

1 Test folder=
   2 Test=test/myJump.htm
       <param name="WindowName" value="TP">
       <param name="FrameName" value="_blank">
    2 Another Item=web1\Umlauts\Umlauts.htm

http://www.HelpwareGroup.com/