Preferences Dialog

This dialog is available from the Options menu (main window), or by pressing F12 from any of the major non-modal windows. It allows you to setup global preferences for FAR. 

   General page   

Preferred Text File Editor

Enter the full path to your preferred text file editor. Whenever FAR displayed a text file or a file as text, this editor is used. Leave the field blank if you want to use the Windows default text editor (notepad). Press the [...] button to browse for a file.

In the second field enter any special command line parameters required by the editor. Make sure you include the string "%s". When FAR opens a file it will replace %s with the name of the file to open.

FAR Update Messages 

This feature requires an internet connection.

Automatically check the web for updates

If you have an Internet connection and IE4/5, FAR can periodically check the web for updates. If an update is available you will get a notification popup.  When this item is unchecked there is no attempt made to access the web. 

We strongly recommend that you keep this setting enabled. It is the primary way in which we inform you of update availability. FAR updates contain bug fixes as well as new features.

Check every n days

Set the number of days until the next automatic check is performed.

Stop Notification messages

Uncheck this setting to stop being notified about a new versions of FAR.  This setting is the same as the checkbox on the notification popup. This setting only functions if the Auto Check setting above is enabled.

Note: Whenever a new update is made available on the web, this item is automatically rechecked. That way you always get at least one notification per FAR release. 

Check Web For Update Now

Checks the  www.helpware.net web site for a new versions of FAR. 

More Info:

FAR notification messages are very safe. No information is uploaded to the web and FAR will never try and connect to the web. If you are already connected to the web when FAR is launched, then FAR simply downloads a small text file containing the version number of the current FAR download file.

   File Utilities  

File Utilities

Clear Find/Replace History

Deletes the dropdown history lists associated with the Find and Replace dropdown controls.

Show "Add Single Folder" drop file dialog

When you drop a single folder onto FAR you are prompted whether you want the folder or its parent to be the base directory. Choosing a base directory is important when Zipping or Copying the file list.

File Difference Viewer

The HTML Help Utilities window can display differences between two different help files.  Individual files in the Help file can also be compared if you specify an external file difference viewer (See dialogs right-click menu).

Enter the full path to the viewer executable. EG. FileDiff.exe is a free application by FileWare.
http://www.fileware.com/products.htm#FileDiff

Enter command line parameters for the viewer. Normally this is just %1 %2, where %1 and %2 are replaced at runtime by the two files to be compared.

If the Add Quotes checkbox is checked (the default) then quotes are placed around the %1 and %2 filenames at runtime. This is normally required so that file paths containing spaces are not broken.

   Explorer page   

Context Menus

FAR adds new items to Explorer's context menus. If there is no program associated with a file extension, then Windows (by default) will make FAR the program associated with that file type. Or to put it another way, FAR will not forcibly take over any file extension.

Fig1: "Open with FAR" has been added to the .hhc context menu.

For later versions of Windows (ie 2K/ME/XP/Vista) the rules for creating context menus have changed. You will now see a menu item called "Open With..." that will contain additional "FAR" commands. 

A .FarRun script file when run will start FAR.exe and executes the script in its [default] INI section.

FAR context menus are added for the following file extensions:

Add all File Associations

Click this button to reinstall all file context menu items. Zip & Folder menu items (see above) are only added if the Zip & Folder checkboxes are checked. These are made available since some users do not like cluttered Explorer context menus. 

In Windows 2K/ME/XP/Vista (or greater) only, if the checkbox "Make FAR default editor for .hh? and Hx? files" is checked, then FAR will become the Default editor for all help file types. We normally keep this box unchecked initially (when the preferences  dialog is opened) to encourage you not to overwrite file associations of other authoring programs. It's up to you if you want to use this.
 

Remove all File Associations

Click this button to remove all FAR file associations from the Windows registry. This command is also called when FAR is uninstalled
ie Selecting FAR Uninstall from  Control Panel > Add/Remove Programs.

Additional Notes:

• In this page the Add and Remove buttons perform the action. The dialog OK and Cancel buttons will neither confirm or cancel the action taken by Add or Remove.
• Use this page if you install more than one copy of FAR on your PC. It allows you to choose which FAR installation will use the Explorer file associations.

   Settings page   

Location of Software Settings

FAR software settings can be saved to either the Windows Registry or to a location on your hard disk. Older versions of FAR could only save to the Registry. Some users prefer "Save to Disk" so they can run from a portable drive which moves between PCs. Other users prefer the Registry so they can install multiple copies of FAR and give each installation its own settings area.

Tip: You will need to restart your FAR application after making to this page.

Save to Registry:

Choose this option to save settings to the Windows Registry under the following key:
HKEY_CURRENT_USER\Software\The Helpware Group\FAR\Settings

By entering a "Registry Key Suffix" into the entry field of say "XYZ" this will change the path to:
HKEY_CURRENT_USER\Software\The Helpware Group\FAR\SettingsXYZ

Useful for authors who install multiple copies of the FAR application.
For example use one FAR for editing a French project and one for editing an English project.

Save to Disk:

Choose this option to tell FAR to save settings on your hard disk drive not the registry. Enter the full location of an existing disk folder in the entry field.

Settings are saved to the file "FAR_Settings.ini" in the directory you specify.

Note: If you choose Save to Disk then FAR will also save some other file info to this folder instead of to the default Windows Temp folder.

Settings.ini/[main]/DataDir=

Note that the FAR location settings are saved in the registry. So if you need to put FAR onto a USB drive (simply by copying the FAR.exe folder and subfolders), then you would need to select the USB data dir every time you plug the USB drive into a new PC. To get around this problem you can now set the data directory in the FAR settings.ini file. See Settings.INI help for more info.

Note that if you do copy FAR.exe and its support files and folders to a USB drive, you will also need to locate and copy the FAR*.ID license registration file into the folder containing FAR.EXE.

Export / Import Registry Software Settings

If you only "Save to Disk" then ignore this section.

Software settings, if saved to the registry, are saved to the HKEY_CURRENT_USER area of the registry. If you log into your PC using different Usernames then each logon will see its own unique HKEY_CURRENT_USER settings. If you need to share settings between two different user logons (or different PCs), then you will need to Export the settings out of the registry to disk, log on as the other user, then Import the settings back into the registry.

ListBox

Lists the registry keys where FAR saves its settings. Normally you will see only one path. If you use the "Registry Key Suffix" option mentioned above, then you may see more than one path. In this case you will need to select a registry key location before exporting settings to a file, or importing data from a file.

Export Button

When pressed you will be prompted for a name of an INI filename. FAR settings are copied from the selected registry location and saved into the specified file.

Import Button

When pressed you will be prompted for an INI filename to load. The file should have previously been exported from FAR (or created via Save To Disk mode). The file contents are read into the selected registry location.

   HTML Help page   

When generating TOC/Index files

These settings are used by dialogs which generate Table Of Contents (TOC) and Index files  (for both HTML Help and MS Help 2 systems). 

Replace "_" with " "

TOC Labels are created by extracting the <title> tag text from an HTML file. If a TOC item does not link to a topic then the file folder name is used. Check this item to replace underscore chars in TOC labels with spaces. It is important to use underscores instead of spaces in filenames and folders because spaces often upset MS Help.

Use filenames for TOC labels

TOC labels are created using the actual HTML filenames. This is a debug aid and should normally remain unchecked. 

Include HTML Bookmarks

When searching for files the program also opens each HTML file found and searches for HTML bookmarks.
Any bookmarks found are then included in the TOC.  Note: This feature will slow down processing.

   Include empty bookmarks

Bookmarks such as <a name="xyz"></a> do not wrap a text label and are normally ignored by FAR. If this item is checked then the Bookmark is included and the bookmark "xyz" is used as the TOC label.

   Detect Bookmark <Hn> Level

Bookmarks are often associated with a <H1>, <H2> etc heading tag.
   EG1. <h1><a name="Bookmark1">My Title</a></h1>
   EG2. <a name="Bookmark1"><h1>My Title</h1></a>
When this box is checked FAR will attempt to detect the associated header level and create TOC structure (levels) for the bookmark items. Note that if only one H1 bookmark heading is detected for an HTML document, and it is the first bookmark, then FAR will skip the first bookmark in an attempt to normalize the TOC (since the HTML document TOC item and H1 bookmark item are usually doing the same job).
Note: This setting only works for documents with good heading structure. If FAR finds a document full of say only H4 and H5 heading tags it will leave the structure mostly flat.

   Bookmark Icons

Set which TOC icons to use when displaying bookmarks.

Ignore folders prefixed with text:

You can stop folders (and their sub folders) from being added to an automatically generated TOC.
Note that this does not stop files from being included in the CHM during compilation (Global Search Filter below controls this).
EG. Check the box and enter a character = "_" (single underscore). The following folders _Contacts, _Photos, _Scripts (and their sub folders) would be excluded when automatically building a TOC.

Global Search Filter

Various commands in FAR search the hard disk for web / HTML Help type files. 
EG. Main Window | File > Add Web Files, and other commands that automatically generate web file lists.
When performing a web file search FAR uses this "Global Search Filter".
Press "Reset" to set the filter to the shipped default settings.
Press "Edit" to change the filters.

Note that the "Global Search Filter" effectively sets what baggage files are included in a .CHM help file when using say the "Express Help" command. If you wanted FAR to include say *.XML files into an automatically generated help file then you would need to press Edit and add ".XML" into the "Only Incl. Files" line of the filter.

See also: File Filter Dialog

   MS Help 2 page   

MS Help 2.x Viewer

In MS Help 2.x you can use your own custom help viewer, unlike in the past where you were tied to the standard MS Help viewer. Here you can enter one or more viewers. Only one viewer can be active at a time. Using the right-click popup menu you can select which help viewer to use for MS Help 2 viewing throughout FAR.

Each entry in the viewers list box, must be in the form "FULL_VIEWER_EXE_PATH,PARAMS". Where FULL_VIEWER_EXE_PATH is the full path to the viewers executable file, and PARAMS is the required command line parameter required by the viewer. PARAMS must contain the 2 character string "%s". This will be replaced by the Namespace you are trying to view at execution time.

To use FAR's in-built viewer simply specify "FAR.EXE,ms-help://%s". The directory part or the path is not required in this case. However, if you do specify the full path to FAR.EXE, you will then be able use FAR.EXE to test your projects when authoring in MS Help SDK (Workshop).

Note that the MS Help 2 Project Editor allows you to specify a different viewer for each help project, but this setting is only used while you are testing help in the H2 Project Editor. Or in MS Help SDK (Workshop). In FAR H2 Project Editor you will see the viewers (listed above), presented in a dropdown Viewer list.

Help File Save Mode: Write All Help Settings

Normally Workshop and FAR do not write default settings when saving .Hx? help source files. For example, in the .HxC project file you don't normally see the Title= and Copyright= settings if no Title and Copyright Info has not been specified:

<HelpCollection DTDVersion="1.0"
   Title = ""
   Copyright = "">

Checking Write All Help Settings, forces FAR to save to disk all your Hx? settings, even the default values, when a save is performed. This can help to make the hx source files more readable.

Write All Help Settings (Project-Level Files): Hx? Project files are those ASCII files the Help compiler uses in creating a .HxS compiled help file.

Write All Help Settings (Collection-Level Files): Hx? Collection files are the uncompiled ASCII runtime files we ship with our collections.

Leaving these settings enabled will not effect the final help systems.

Location Of HxMerge.exe and HxConv.exe

The H2 Utilities and Batch Compile windows use these files. Click the "Set Default" button to set the default folder where the H2 SDK Utilities reside. If the path is invalid, then try searching your hard disk for the file HxMerge.exe, and paste in the correct directory path. If HxMerge.exe is not found, then you may have the MS Help SDK installed incorrectly.

   FTP page

FTP Auto-Transfer Mode

Used by the FTP Copy Files command when you select Transfer mode = Auto.

There are two main ways to transfer files to an FTP server, Binary and ASCII. Use Binary transfer type for transferring executables, compressed files, graphics, and multimedia files. Use ASCII transfer type for 7bit ASCII files, such as text or Hyper Text Markup Language.

File types added to this list are considered ASCII. All other File types are considered Binary.

Uploading to a server in the wrong mode has been known to cause file corruption (although we have never had a problem uploading everything as binary). If your ASCII files contain international characters (ie. Chinese or Japanese text), they should be uploaded as binary.

   Logging page   

Enable Find and Replace logging

Check this item to log find and replace changes to a log file. The log filename is of the form far-yyyy-mm-dd.txt, a new log file for each day. The latest batch of changes are placed at the top of the log file for ease of reading. Each batch of changes is dated and begins with a vertical line.

The list control (below) displays all files in the current log folder. Take care, this is actually a Windows Explorer control. You can delete (Del) and rename (F2) files etc. Double-click the log file to view it in the default text editor. Because you are in Explorer you can actually use the "Edit > Undo" menu in Explorer if you make a mistake. Pressing Cancel button will NOT undo changes you make in the Explorer list.

Auto show log file at end of run

Check this item to automatically view the log file at the end of searching a list of files.

Log finds

By default all modifications are logged. Select this item if you also want to log matches.

Log match text plus

This allows you to log the original text found plus n characters before and n characters after the text.

Log modified text plus

This allows you to log the modified text plus n characters before and n characters after the text.

Log File Folder

Select a folder where you want the log files to be stored. Press the [...] button to select a new folder. You can also select a folder by picking an item from the dropdown list or double-clicking a folder item in the file list. Press the Reset button to set the log folder to the original default folder. Make sure you click OK to make the change permanent.