
                  The tool for easy file comparisons, 
                         alteration and analysis
                         1993,94 by David Reitter
              gale is Shareware and may be copied unchanged.
______________________________________________________________________________

                 Version 2.4i, dated 12th December 1994

==============================================================================



                                 Manual
                














***** Contents

 1.    Introduction
 1.1   What's gale for?
 1.2   Features
 1.3   Distribution and your Shareware obligations
 1.3.1 Updates
 1.3.2 gale UK Support and Registration
 1.3.3 gale registration outside the UK
 1.4   gale origins
 1.5   User interface
 1.5.1 Using dialogs
 1.5.2 Pop-up menus
 1.5.3 Keyboard shortcuts
 2.    'File' drop down menu
 2.1   Open...
 2.2   Open binary...
 2.3   Close
 2.4   Discard
 2.5   Save as...
 2.6   Create list...
 2.6.1 Why use a patch program?
 2.6.2 How to create a patch program
 2.6.3 How to use a patch program
 2.7   Information...
 2.8   Quit
 3.    'Find' drop down menu
 3.1   Find...
 3.1.1 'Find' examples
 3.2   Find next
 3.3   Jump...
 3.3.1 Jump into action
 3.4   Line equalisation...
 3.4.1 Equalise: A step by step tutorial
 3.5   - Automatic...
 3.6   First difference OR First identical line
 3.7   Next difference OR Next identical line
 4.    'Edit' drop down menu
 4.1   Undo
 4.2   Insert text line...
 4.3   Edit text line...
 4.4   Insert line
 4.5   Delete line
 4.6   Load status log...
 4.7   Save status...
 4.8   Clear status...
 5.    'Window' drop down menu
 5.1   Cycle
 5.2   Help
 5.3   Files
 6.    'Options' drop down menu
 6.1   Comparison mode...
 6.2   Number lines
 6.3   Emphasis...
 6.4   Display...
 6.5   Fonts...
 6.6   Colours...
 6.7   Save settings...
 6.8   Load saved settings...
 6.9   Quick save and exit
 7.    Other functions
 7.1   Display functions
 7.2   Single line comparison using one-line windows
 7.3   Moving files
 7.5   Iconifying
 8.    Advanced gale features
 8.1   Passing parameters
 8.2   Passing parameters using EGALEPAR.PRG
 9.    Technical notes
 9.1   Protocols supported
 9.2   Known bugs
 9.3   Hints & tips
 10.   Miscellaneous
 10.1  Credits
 10.2  Warranty and liability

Hinweis: Es gibt eine deutschsprachige Version.
____________________________________________________________________________

*****1. Introduction



1.1 What's gale for?

Here's a few examples:
Two identical filenames on different disks, same filesize, same datestamp 
but are they really exactly the same? When gale loads two identical files 
a dialog is displayed confirming they are identical, and you can either 
select other files, exit or continue and display the files.

You update a program or document, then decide some of the changes you've 
made are a backward step, and would like to review all the changes made 
since you last saved a back-up. Load the current and back-up files into 
gale and the differences between the two files will be highlighted. You 
can save the differences as a file and review these as desired.

You discover a minor but nasty bug in a program you've already released! 
Load the original and updated executable files into gale and after 
following a simple procedure gale will generate a compact patch program 
which you can release to your users.

gale provides a solution for everyone who has been confronted with these 
or similar problems. gale is useful to anyone who needs to compare or 
'hack' files, programmers, journalists, etc.

In principle these tasks could be performed using a text editor or other 
application but gale (as far as we are aware) is the only custom 
application designed to manage these tasks which it does with the minimum 
of fuss via an enhanced GEM interface. Save your brain, let gale take 
the strain!

1.2 Features

- Two files are loaded in each window and displayed side by side, 
  adjacent to one another, with the window divided vertically.
- gale can also load a single file so that you can analyse its format 
  or amend it. This feature turns gale into a binary editor for patches 
  and similar applications.
- Any file size up to the limit imposed by the available working memory 
  in your machine can be loaded...
- Compare both text and binary files.
- Delete individual lines or characters or insert dummy (blank) lines 
  between them.
- Various features available to assist in locating differences:
+ Individual lines can be displayed one above the other in an extra 
  one-line window to make visual comparison easier.
+ Can locate inserted and deleted parts of a file in comparison with 
  another file automatically.
+ Line numbering, optional.
+ Comparison of characters OR by interpreting each line as a numerical 
  value (handy for adjusting spreadsheet data). The numerical value can 
  be asigned a 'tolerance'. Any value which falls within the defined 
  tolerance range are considered equal by gale.
+ Status log/Diff file (containing the position of inserted and deleted 
  lines) can be saved and loaded.
+ Wildcard search function.
+ Jump (Goto) to any desired line number, relative to the current line 
  or from the start line (absolute).
- Loaded files can be exported directly to an editor of your choice for 
  further processing.
- Vertical divider bar separating two files in each window can be 
  freely positioned.
- [Help] key displays keyboard shortcuts, and context-sensitive help in 
  dialogs if ST-Guide or other hypertext system is installed.
- Enhanced GEM interface, runs on ST, TT and Falcon030 computers. Supports 
  multitasking systems under TOS at all screen resolutions from 640x200 
  pixels (ST medium) upwards.
+ There are minor problems with the display of small text at 640x200 so 
  a seperate RSC file EGALEMID.RSC is provided. To use this rename the 
  existing EGALE.RSC file to EGALE.RSH, then EGALEMID.RSC to EGALE.RSC.
  Remember to reverse the process when you want to run at higher 
  resolutions or gale will behave strangely!

1.3 Distribution and your Shareware obligations

Distribution of gale is encouraged for non-commercial purposes. PD and
Shareware libraries may also distribute gale so long as I am informed 
in writing. The following files comprise gale and must be distributed
together and intact:

EGALE.PRG         gale executable
EGALEPAR.PRG      Utility to pass parameters to gale
EGALE.RSC         RSC file for all resolutions above 600x200
EGALEMID.RSC      RSC file for 600x200 (ST Medium resolution); rename 
                  EGALE.RSC to EGALE.RSH then rename EGALEMID.RSC to 
                  EGALE.RSC when you want to run gale in ST Medium 
                  resolution
ICON_BW.RSC       Monochrome gale icon
ICON_COL.RSC      Colour (16 and 256) gale icon
EGALE.TXT         This documentation
READ_ME.TXT       Registration and history text
EGALE_E.HYP       ST-Guide format on-line help
EGALE_E.REF       ST-Guide references file

EXAMPLES          Folder containing tutorial examples

gale may only be included on magazine cover disks, CD-ROM or other 
compilations with the author's prior written permission.

Any contravention of my wishes is a breach of Copyright and this Shareware 
statement and will be strongly challenged!

gale is Shareware. The current UK Shareware fee is 10.00 and if you 
use gale regularly your obligations under Copyright law are clear. 
After a short evaluation period, either register your copy or stop 
using gale.

The future development of gale depends largely on the support from you. 
Although the unregistered version of gale is perfectly usable the 
benefits of registration are considerable:

o Option to compare files for similarities as well as differences.
o One can save parts of the files.
o One can create lists of differences or similarities.
o One can create patch programs which can be used to 
  alter a source file to correspond with a (so-called) target file.
o Instead of simply toggling the Emphasis option on/off a dialog appears
  from which the following extra options are available:
  Use colours, Bold, Hide the rest, Divider only, Mark each character,
  First target, All and Inserts.
o Automatic line equalisation is available for whole files.
o The form of the line-cursor can be changed to give a clearer display 
  under some conditions.
o Pop-up menu offers extra options to make tab characters in text 
  visible in different ways and to vary the width of tab stops.
o Another pop-up menu in 'Display...'  allows one to view the displayed files 
  subdivided with faint horizontal lines. gale can draw thin graphic 
  lines at 2 or 4 line intervals which is particularly useful in binary 
  mode to indicate word or longword boundaries.
o An Info line provides information about the line at the cursor.
o Registered users will get a printed quick-reference summary giving 
  an overview of the functions and options offered.
  (If registered via Joe Connor)
o Access to the UK Update and support service.


1.3.1 Updates

You can get the actual version of gale

- at the KGB Wiesbaden Mailbox:
  Call +49-611-375201, log in as "EGALE", password "EGALE".
  You will be asked which version (International English language version 
  or the German one) you'd like to get. The BBS will transmit gale using 
  the Z-Modem protocol.
- from Joe Connor (see 'gale UK Support and Registration')
- from David Reitter (see 'gale registration outside the UK')

1.3.2 gale UK Support and Registration

On registration you will receive a 'Key' to 'unlock' the Registered user 
only features. To register your copy of gale in the UK follow the 
procedure below:

a) Make a cheque for 10.00 payable to Joe Connor
b) Be sure to include your surname, forename and full address.
   The gale 'Registration dialog' offers a convienent method of ordering 
   your key with the added benefit of checking the format of your 
   details. Enter your details and press [Alternate]+[R] or click on the 
  'Order' button. After validating your details a further dialog appears 
   from which you can output the letter either directly to the printer or 
   to a file for further processing, for example to send as Email.
c) Send letter and cheque to the UK Address below:


                    Joe Connor
                    65 Mill Road
                    Colchester
                    CO4 5LJ
                    England

                    Email: jconnor@cix.compulink.co.uk 



Update service
Registered UK users can obtain the latest English Version from Joe Connor 
at any time, free of charge until otherwise notified, by sending a Stamped 
Addressed Envelope enclosing a floppy disk - so long as the latest version 
has not become commercial.

Installing your Key
Enter your key details into the registration dialog and press [Return] 
twice to clear the dialogs, then select 'Save default settings' from the 
 'Options' menu to save the registration details (in EGALE.INF). So long as 
you don't delete your copy of EGALE.INF and I don't change the format you 
won't be troubled by the registration procedure in future gale updates.

Remember gale uses the EGALE.INF file to store your personal preferences 
and key so be sure to delete EGALE.INF before passing copies of gale on to 
friends or other users.

1.3.3 gale registration outside the UK

You can either register as detailed in gale UK Support and Registration 
above or as follows:

1) By Email
   If you have a modem and access to the Maus net send your details to
   the following address:
   From inside the Maus net: David Reitter @ WI2
   Via the Internet: david_reitter@wi2.maus.de

   Transfer 20.- DM to me. Here's my Bank details:

                        David Reitter
                        KTO (Account No.): 0229 773
                        BLZ (Sort code)  : 550 700 40
                        Deutsche Bank Mainz

   A suitable key will be returned by Email.

2) By post
   Send me:
   A 20.- DM note together with your registration details, a self addressed
   envelope (or label) and 2 International Reply Coupons.

   Your key will follow by return of post.

Important!
o If anything is missing, nothing will come back, you have been warned!
o Those that register agree that their data may be stored in electronic 
  form on a computer.
o Registered users will get a printed quick-reference summary giving an 
  overview of the functions and options offered (only if registered via
  Joe Connor!). They can also send me a formatted disk, a self-addressed 
  envelope and two International Reply Coupons at any time to receive the 
  latest version of gale, as long as this version is not being distributed 
  commercially, or may, if they wish and have a modem, obtain the latest 
  beta-test version from the Wiesbaden Mailbox.
o Unregistered users can obtain a new version from me (once only) by post.


                              David Reitter
                              Albinistr. 10
                              D-55116 Mainz
                              Germany

1.4 gale origins

gale was originated by Christof Schardt. At that time the program was 
still called COMPARE and did not use GEM, so ran only in ST high 
resolution. At the start of 1993 COMPARE was completely re-programmed and 
incorporated the usage of GEM. It's now called 'gale'.

Why 'gale'? 'gal' in French means 'equal', 'gale' is the feminine form. 
And why should all programs bear some sort of English name?! We've 
graciously ignored the fact that one doesn't use accents with (French) 
capital letters !

                   ..The programmer:...................
                   :                                  :
                   : David Reitter                    :
                   : Albinistr. 10                    :
                   : 55116 Mainz                      :
                   : Germany                          :
                   : Tel.: +49 6131 233255            :
                   : Email: david_reitter@wi2.maus.de :
                   :..................................:

1.5 User interface

Thanks to its GEM operation the usage of gale is largely self-explanatory. 
That makes it that much harder to explain everything in these instructions 
in a way that is easily understood. Instead of listing all the menu points 
these instructions are divided into sections related by meaning.

gale uses all the popular features of the enhanced GEM interface. Most of 
these features are now in common usage in other software. Here's an 
overview:


1.5.1 Using dialogs

gale dialogs can be displayed in windows. The following features are 
available:

- Selectable objects include an underlined character.


- The 'Cancel' button in dialogs and alert boxes can be selected by 
  pressing the [Undo] key.
- The 'Asses ear' at the top right of most dialog boxes can be used to 
  move dialog boxes around the screen. A click and drag operation is used; 
  during flight dialogs become invisible.

1.5.2 Pop-up menus



Each bold dialog option button contains a pop-up menu. Click on the button 
to display all the menu options or click on the circular arrow box to cycle 
through the available options. Further options can be selected using either 
the mouse or keyboard. Click on an option using the mouse to select it or 
click away from the pop-up menu to close without making a selection.

The following keyboard commands are active within pop-up menus:

Key                                 Action

[Up-arrow]      Move selection bar up.
[Down-arrow]    Move selection bar down.
[Return]        Select entry.
[Undo]          Exit pop-up without selection.
[Esc]           Exit pop-up without selection.


1.5.3 Keyboard shortcuts

'Within this document square brackets' '[...]' ' are used to denote keys 
on the keyboard.' 

The [Shift] keys within gale are 'NOT' interchangeable. Use the left 
[Shift] key for the left part of a divided window and the right [Shift] 
key for the right part of the window; logical, eh? Keyboard shortcuts are 
listed next to each menu entry. Here are the details:

(Top hat).......................... '^' = [Control] key.
(Up-arrow)......................... ' ' = [Shift] key.
(Looks like Window fuller icon).... ' ' = [Alternate] key.

Keyboard control

[Left-arrow]            Window scrolls 5 characters left.
[Right-arrow]           Window scrolls 5 characters right.
[Up-arrow]              Marker moves 1 line up, window scrolls if at edge.
[Down-arrow]            Marker moves 1 line down, window scrolls if at edge.
[Shift]+[Left-arrow]    Window scrolls 1 character left.
[Shift]+[Right-arrow]   Window scrolls 1 character right.
[Shift]+[Up-arrow]      Window scrolls 1 screen page up.
[Shift]+[Down-arrow]    Window scrolls 1 screen page down.
[ClrHome]               Marker positioned on first line.
[Shift]+[ClrHome]       Marker positioned on last line.


____________________________________________________________________________

*****2. 'File' drop down menu



2.1 Open...

Select this option to load and display files in text mode. Unless gale 
is passed file/s as parameters, e.g. from a command line, the file 
selector appears in which one or two files must be selected in turn 
followed by 'OK.'  

If the first selected file is executable (ACC, APP, PRG, TOS or TTP) a
dialog appears asking whether the file should be loaded in binary mode.

If you select 'Cancel' in the second file selector, i.e. specify only
one file, then gale will only load a single file. This can be useful
for analysing file formats, as well as for editing (binary) files.

Wildcards are allowed in the file selector, for example: FILE?.TXT
would load the first two matching files - if you had a series of files 
FILE1.TXT, FILE2.TXT, FILE3.TXT ...  then FILE1.TXT and FILE2.TXT 
would be loaded. If two matching files are found they're loaded and the 
second file selector isn't displayed.

If you're using Selectric and you select more than two matching files 
the first two matches are loaded.

If there's not enough memory to load files, they can be compared. 
The position of the first difference is displayed.

If one is loading in text file mode (i.e. 'Open binary...' has not been
used) and the file being loaded contains ASCII 0 (NULL) characters, 
then these have to be converted. gale will ask you to what character 
they should be converted: 
  - 'SPACE'  (Space character ' ', ASCII 32)
  - ''     (ASCII 179)
  - 'TAB'    (Tabulator 'clock' character, ASCII 9)

Then the files will be loaded and displayed in a newly opened single 
GEM window. All the 'gadgets' and scroll bars behave normally.

2.2 Open binary...

Select this option to load and display files in binary mode. Unless gale 
is passed file/s as parameters, e.g. from a command line, the file selector 
appears in which one or two files must be selected in turn followed by 'OK.' 

In binary mode only one byte per line is displayed on screen. Each byte is 
displayed in hex, decimal, binary and ASCII format. Some functions are 
unavailable (greyed out) in binary mode.

Otherwise the loading of binary files proceeds in the same way as for 
loading text files.

2.3 Close

Selecting 'Close' or clicking on the 'close' icon (top left hand corner) 
closes the window but holds the files in memory, which means it may be 
re-opened by clicking on one of the entries in the 'Window' menu, or 
pressing [Alternate]+ corresponding number.

2.4 Discard

One-line window/s can be discarded by clicking on their 'close' icon or, 
if you are closing the file window which called them, by clicking on the 
'close' icon of that file window.

File windows must be discarded (rather than closed) to remove them from 
memory, which may be neccessary if you're running short of memory.

2.5 Save as...

Select this option to save a file to disk. Enter or select a filename
using the file selector then select 'OK'. The file is stored in the
original format. Insertions are stored as a blank line or (in binary
mode) as a NUL byte (ASCII 0).

2.6 Create list...

Select this option to display the 'Output' dialog. 
The following options are available:


Save part of the file

Select this option to save any parts of a file. Having selected 
'Save part of the file' , you can setup the following options:
























'File:' 
Select which file is to be saved. The filenames of the file(s) in the 
topped window are displayed. If you have loaded two files you can toggle 
between them. A round filled button shows the selected file.

'As bytes list:'  [Alternate]+[B]  --* Binary files ONLY *-- 
A check box offers a choice between:
'Unchecked:' Default. Binary file saved in the same format as loaded, thus an 
           executable file remains executable.
'Checked:'   File saved as character list (as displayed in the file window)
           with hex, decimal, binary and ASCII columns.
           Optionally, only if this box is checked, line numbers can also 
           be saved and the 'Print' button is available.

'Number lines:'  [Alternate]+[N]
This option is not available (greyed out) if a binary file is selected in 
binary format.
A check box offers a choice between:
'Unchecked:' Default. Line numbers are not saved with the file.
'Checked:'   Line numbers are saved with the file.

'Insertions and deletions:' 
'Omit insertions:'  [Alternate]+[I]
A check box offers a choice between:
'Unchecked:' Default. Insertions made with the 'Insert text line...' function 
           are saved with the file.
'Checked:'   Insertions are not saved with the file.

'Text:' An editable text field (22 characters max) enable a text string to 
be written to the file in place of the inserted lines. If this field is 
empty (by default this field contains '-') a blank line is written.

'Write deletions:'  [Alternate]+[W]
A check box offers a choice between:
'Unchecked:' Default. Deleted lines are not saved to the file.
'Checked:'   Deleted lines are saved to the file (losing your changes!).

The defaults are set to save all the changes you make to a file.

'What?:' 
It's easier to handle the 'From line:' and 'to:' options if the 
'Number lines'  option from the 'Options' menu is turned on.

'From line:' (Default '1') Select the first line to be saved.
'to:'        (Defaults to last line of file) Select the last line to be saved.

To enter hexadecimal values, precede the number with a '$'
e.g  $20 for decimal 32.

'Only different ones' OR 'Only identical ones:'  [Alternate]+[Y]
A check box offers a choice between:
'Unchecked:' Default. All lines between the 'From line:' and 'to:' options are
           saved to the file.
'Checked:'   All differing OR matching lines, depending on the 'Search for'  
           setting in the 'Comparison mode'  dialog, between the 'From line:' 
           and 'to:' options are saved to the file.

Hints & tips
The option to save only the different (or identical) lines, used together 
with line numbering, makes it easy to keep track of the changes between 
files.

'Print:'  [Alternate]+[P]
This button outputs the selected data to the printer. This option is not 
available (greyed out) if a binary file is selected in binary format.

--> Unregistered?
    The 'Save file' function is not available in the unregistered version.

List of differences/correspondences

A list of difference/correspondences, depending on the 'Search for' setting 
in the 'Comparison mode'  dialog, can be saved or printed in 'xx/yy' format. 

Example:

Differences between
D:\EGALE\EXAMPLE5.TXT / D:\EGALE\EXAMPLE6.TXT
  7/7
 15/15
e--/16
 25/26
 30/31
e55/--
 79/79
.../

The file 'EXAMPLE5.TXT' has differences in lines 7, 15, 25, 30 and 79 
compared to the second file. The corresponding line number in 'EXAMPLE6.TXT' 
is also indicated (after the '/').

Inserted lines are indicated by a broken line ('--') and an 'i' is placed 
at the start of the line; deleted lines are not mentioned!

The '...' dots at the end indicates the two files (including any insertions 
and deletions already made) have a different length.
If the dots are to the left of the '/' there are more lines in the left 
hand file and vice versa.

'With relevant lines: ' [Alternate]+[W]
A check box offers a choice between:
'Unchecked:' Default. The contents of the corresponding lines/characters are 
           not saved to the list.
'Checked:'   The contents of the corresponding lines/characters are included 
           below (with text files) or next to (with binary files) the 
           usual list data, described above.

--> Unregistered?
    The 'List of differences' function is not available in the unregistered
    version.

Patch program

It's possible to create an executable program (PRG) which can be used to 
alter a source file to correspond with a (so-called) target file. This is 
commonly referred to as a 'Patch program' and is used to update minor 
differences between files.

The 'Print' button is not available (greyed out) if patch program 
option is selected.


2.6.1 Why use a patch program?

Patch programs evolved mainly for the benefit of on-line users where every 
byte costs money to transmit. They're commonly used to update executables 
but can also be used to update documentation.

Let's suppose you've just released a 200kb masterpiece for beta testing and 
after a number of minor bugs have been reported you want to release a fixed 
version. What are your options?

- Send each beta tester a new file? Expensive and time consuming...
- Send each beta tester a list which they can use to manually patch their 
  copy using a hex-editor? Error prone and awkward...
- Send them a small patch program which automatically updates their copy?

2.6.2 How to create a patch program

1) Load the 'BUGGED.PRG' followed by 'NEW.PRG' into gale.
2) Ensure that 'Chap.numbers' (leading numbers) in the 'Ignore' area of the 
 'Comparison mode'  dialog from the 'Options' menu is cleared otherwise 
   gale will not be able to recognise the relevant lines as different.
3) Equalise the files using either manual or automatic line equalisation.
4) Select 'Create List...' from the 'File' menu to display the patch dialog.
5) Select the 'Patch BUGGED.PRG to NEW.PRG'  option, then 'OK.' 
6) The file selector appears; enter a filename for the patch program, e.g. 
    'PATCH.PRG' followed by 'OK.' 
7) gale compares the two files line by line or byte by byte and creates an 
   executable 'PATCH.PRG' which does the following:

- An inserted line in the source file will be added to the target file.
- A deleted line in source file will be deleted in the target file.
- Any differing lines will be replaced in the target file with the contents 
  of the source file.

Patch programs can also patch more than one file. To generate such a patch 
program, create a patch program for the first file that shall be patched. 
Then, create another, but select (step 6) the patch program you have 
already generated. gale will ask you whether the file should be 
overwritten or attached. Select "Attach". Do the same for every file the 
patch program shall patch.

It's important to check the patch program worked correctly and the easiest 
way to do this is to load the file generated by the patch program and 
compare it with your updated master. If they are 'equal' everything worked! 
The size of the patch program depends on two main factors:
- The number of changes made to the source file. The more changes, the 
  bigger the patch program (from an initial overhead of ~12kb). If there 
  are too many changes the patch program can easily grow larger than the 
  source program, which completely defeats the object!
- The line length. Replacing long line/s (in Text mode) dramatically 
  increases the size of the patch program.

2.6.3 How to use a patch program

1) Run PATCH.PRG and the file selector appears usually displaying the file 
   it's looking for.
2) Load in 'BUGGED.PRG' followed by 'OK.' 
3) The patch program checks whether it's the file it's looking for then 
   re-displays the file selector.
4) Enter the filename for the output program 'NEW.PRG' followed by 'OK.' 
5) The patch program generates 'NEW.PRG'.

--> Unregistered?
    The 'Patch program' function is not available in the unregistered
    version.

2.7 Information...

Select this option to display the 'Information...' dialog. The following 
information about each file in the topped window is displayed:

'File names:            Filename1  Filename2
'No. of lines:              x          y
'Differing lines:           x          y
'Average line length:       x          y
'Size (Bytes):              x          y
'Inserted/deleted:          x          y
'Maximum possible:        1000       1000'  (default)

A further button 'General Info'  [Alternate]+[G] can be used to display a 
further 'General information' dialog. This dialog appears immediately if 
file window is open. The following information is displayed:

'Open/maximum windows:   x/y
'Open/maximum files:     x/y
'Lines per file:         Unlimited
'Available memory:'      The largest contiguous block is displayed in Bytes.

2.8 Quit

Select this option to leave gale; any changes to files and settings are 
'NOT' stored using this option.


____________________________________________________________________________

*****3. 'Find' drop down menu



3.1 Find...

Select this option to display the 'Find' dialog. The following options 
are available:

























'In:' 
If two files have been loaded in the topped window, both filenames are 
displayed along with a check box for each filename. By default both files 
will be searched (i.e. both check boxes are crossed). To restrict the 
search to either file de-select the other file (i.e. clear its check box).

'Input as ASCII value:'  [Alternate]+[V]
A check box offers an option to search for the ASCII value equivalent(s) 
of the actual string displayed in the editable 'Text:' field.

'Text:' 
Enter the desired search string into the editable field. In addition to 
searching for normal text strings gale can search for ASCII values if the 
'Input as ASCII value' option is active (checked). Enter the numbers in the 
following format:

Decimal:     Enter the number                e.g. 144   for ''.
Hexadecimal: Precede the number with a '$'   e.g  $90   for ''.
Octal:       Precede the number with a '&O'  e.g  &O220 for ''. *

* The 'O' is capital O, NOT 0 (zero).

'Options:' 
'Caps/l.c. sensitive:'  [Alternate]+[L]
A check box offers the choice between:
'Unchecked:'  Default. The search is not case sensitive, i.e 'e'='E'.
'Checked:'    The search is case sensitive, i.e 'e' is not equal to 'E'.

'Wildcards:'  [Alternate]+[W]
These are commonly found in other programs and have become standardised 
across different computer platforms as follows:

'*' represents any text string (the string may even be empty).
'?' represents any single character.

A check box offers a choice between:
'Unchecked:'  (Default) Wildcards are treated as normal characters
'Checked:'    Wildcards '?' and '*' are active.

'Character tolerance:' 
Greyed out and not currently implemented.

After a successful search gale always displays the found string in the
visible part of the window, scrolling the line horizontally if necessary. 
The found string is pinpointed by a brief growing and shrinking 
rectangle centred on it and the line cursor covering just the found area.
If a search string is found in the same line in both files in the window 
then that in the left file will be highlighted.

With the 'Find next' menu entry or [Control]+[G] you jump to the next 
occurrence of the search string in the text (if any).


3.1.1 'Find' examples

Search string...    finds...            but not...

m?le                mile, mole          mill, mere
m??l                meal, mill          motel
vine*               vine, vineyard      vein
large *room         large diningroom    large kitchen
                    large bedroom       smallest room

Important!
Matching strings which wrap around more than one line will also be found 
and the cursor positioned on the first line.
Example:

Search string...    finds...        and...

fly*fish            flying fish     fly down to Florida
                                    to catch some fish

3.2 Find next

Select this option to continue to search the files using the current search 
string from the current cursor location.

3.3 Jump...

Select this option to display the 'Jump' dialog. The following options are 
available:

'Absolute:'  [Alternate]+[B]  The line number counted from the first line 
                            of the file is jumped to.
'Relative:'  [Alternate]+[R]  The line separated from the current line by 
                            the entered number is jumped to. Negative 
                            values can also be entered to jump backwards 
                            through files.

You can toggle between these two options. A round filled button shows the 
active mode.

To enter hexadecimal values, precede the number with a '$'
e.g  $20 for decimal 32.

'In:' 
If two files have been loaded both filenames of the topped window are 
displayed along with the default 'To position in window' option.
You can toggle between these three options. A round filled button shows 
the active mode.

'To position in window:'  [Alternate]+[P]
gale takes account of any inserted and deleted line and jumps the 
specified number of lines to the position that would be reached by moving 
the line cursor the corresponding number of times within the file window.

If either filename is selected the jump is to the specified line number and 
any lines inserted or deleted are not taken account of.


3.3.1 Jump into action

Take a look at our imaginary file and notice the dummy line inserted 
between lines 2 and 3 and the two dummy lines inserted between 4 and 5. 
Let's consider the 4 different possibilities of jumping 3 lines forwards:

     1 This is line one      
     2 This is line two      
(b)  --------------------
(a)  3 This is line three  
---> 4 This is line four  <--- Line cursor starting position
     --------------------
     --------------------
(c)  5 This is line five
     6 This is line six
(d)  7 This is line seven

Absolute/Relative  Either filename/Position in window  Final position

Checked............................Checked............ (b)
.........Checked...................Checked............ (c)
.........Checked.. Checked............................ (d)

3.4 Line equalisation...

Equalisation is used to align, as far as possible, two basically similar 
files. This is achieved by inserting dummy lines into either file to match 
up identical areas in the files.

Equalisation can quickly isolate changes in documentation and executables 
but only makes sense if the two files are basically similar. Equalising two 
completely different or identical files is pointless!

Consider the two files shown below which represent two basically similar 
files. Before equalisation gale recognises lines 1 and 2 as identical but 
because line 3 differs, due to 'Insertion A', the rest of the file is 
considered different.

Using equalisation we can instruct gale to insert dummy lines into the 
left hand file and progressively match up (or equalise) the two files.

Example:       EXAMPLE1.TXT     EXAMPLE2.TXT

 Line 2         Text 2           Text 2
 Line 3         Text 3           Insertion A
 Line 4         Text 4           Text 3
 Line 5         Text 5           Text 4
 Line 6         Text 6           Insertion B
 Line 7         Text 7           Insertion C
 Line 8                          Text 5
 Line 9                          Text 6
 Line 10                         Text 7


3.4.1 Equalise: A step by step tutorial

Run gale and load in the demo files 'EXAMPLE1.TXT' and 'EXAMPLE2.TXT' and 
your screen should appear similar to that in 'Line equalisation...' above.

Select:  Number lines entry from the 'Options' menu.
Result:  Lines are numbered.
Help:    So you can follow the steps more easily!

Action:  Use [Down-arrow] to move line cursor to line 3.
Help:    There's no point equalising line 1 and 2 because gale already 
         indicates they are identical. Attempting to equalise an identical 
         line displays an alert box with the following message:
        'Both adjacent lines are identical.' 

Select:  ' Line equalisation...' from the 'Options' menu.
Result:  Dialog asks: 'Search for left or right line on opposite side?' 
Help:    In our example we want to search for the left hand text on Line 3 
         in the file on the right hand side, so...

Select: 'Left' 
Result:  gale searches the right hand file for a matching line and if 
         found the 'Line equalisation' dialog appears, otherwise the the 
         system bell is sounded.
Help:    If a match is found the following information is displayed:
         The number of matching lines and the location of first matching 
         line relative to the current line; for our example this is:
        '2 equal lines found 1 line away' 
         This information gives us a good clue as to whether there might be 
         a better match elsewhere in the file; usually a large number of 
         matching lines indicates a good fit. A single line match, 
         particularly when comparing binary files, is unreliable because 
         any single character is likely to be repeated many times in a 
         single file. Four options are available; select the 'Always' 
         option to complete the tutorial:

Option: 'OK'  [Return] or [Enter] (default).
Result:  gale equalises the line and exits the dialog. The file window is 
         updated with the addition of the dummy line and the first 5 lines 
         in the file window are shown as aligned.

Option: 'Always'  [Alternate]+[W]
Result:  Same as for 'OK' plus:
         The 'Line equalisation' dialog will not appear during subsequent 
         equalisations until either [Control] or [Alternate] are held down 
         whilst selecting 'Line equalisation...' 
Note:    If manual equalisation is called using [Control]+[K] you have to
         keep the [Control] key pressed during the 'Left/Right/Cancel' 
         dialog selection.
Help:    Because the 'Always' option doesn't display the 'Line equalisation' 
         dialog no information about the match is displayed, so you run the 
         risk of matching the wrong lines as mentioned earlier!

Option: 'Continue'  [Alternate]+[T]
Result:  XX

Option: 'Cancel'  [Alternate]+[C]
Result:  The 'Line equalisation' dialog is exited without making changes.

Select: 'Next difference'  [Control]+[N]
         The line cursor moves to line 5.

Select: 'Line equalisation...' from 'Options' menu.
Result:  Dialog asks: 'Search for left or right line on opposite side?' 

Select: 'Left' again.
Result:  Two dummy lines are inserted between lines 4 and 5 and the file 
         window is updated with all lines equalised.

Alternatively individual lines can be equalised by right mouse clicking on 
the left file to search for a match in the right hand file and vice versa. 
This avoids the 'Left/Right/Cancel' dialog. The 'Line equalisation' 
dialog appears as before offering the same options.

3.5 - Automatic...

Select this option to display the 'Automatic line equalisation' dialog.

gale attempts to equalise the two files by inserting dummy lines into both
the left and right parts of the window where neccessary to align the files.
This is similar to a series of manual line equalisations except both 
files are equalised in a single operation.

If you're not sure which parameters to use select the 'Default' button 
to restore the default settings which are suitable for most situations. 
The following options offer a degree of control over how lines are 
equalised:





















'How many lines are needed for recognition after a 'gap'?' ' (Default '1').
Sets the minimum number of matching lines which must be found in the 
opposite file before gale recognises the 'gap' as an insertion. 
Consider the following example:

 EXAMPLE3.TXT   EXAMPLE4.TXT     Comments                    

  Text B         Text B          lines match...              
  Text C         Some text                                   
  Text D         inserted                                    
  Text E         Text C       -> Two consecutive              *
  Text F         Text D       -> matching lines               *
  Text G         Gap text                                    
  Text H         Text E       -> Only one matching line here  #
  Text I         Gap text     

If the 'gap' value is set to 1 both * and # would be equalised.
If the 'gap' value is set to 2 * would be equalised, but not #.
If the 'gap' value is set to 3 (or more) neither * nor # would be equalised.

'How many characters/line (min)?'  (Default '1') --* Text files ONLY *--
The purpose of this option is to ensure that during equalising of blank 
lines blank lines are not inserted (although dummy lines can be inserted 
opposite blank lines).

The only time it's worth changing the default option is when a text file 
contains hardly any blank lines, in which case change this setting to '0.' 

'What is the maximum number of lines for a 'gap'? ' 
To ensure equalisation set this value just larger than the largest 
number of lines inserted into either file. For example if one of the 
files has had several lengthy paragraphs, each less than 50 lines, 
inserted then '50' lines will be sufficient. On the other hand if one 
paragraph of 150 lines has been inserted you'll need to up the value 
to at least this figure to equalise the files.

In the example above:
If the value is set to '1' then * would not be equalised but # would.
If the value is set to '2' (or more) both * and # would be equalised.

Lines can also be inserted manually in the appropriate file by pressing:
[Insert]+[Left Shift]  to add a line to the left hand file.
[Insert]+[Right Shift] to add a line to the right hand file.

'Start at:' 
'Beginning:'        [Alternate]+[B]  Search begins at the start of the files. 
'Cursor position:'  [Alternate]+[P]  Search begins from the current position.

You can toggle between these two options. A round filled button shows 
the active mode.

'Keywords:' 
Use this option to equalise files which contain frequently repeated 
keywords at the start of lines.
A check box offers a choice between:
'Unchecked:' Default: Keywords are ignored
'Checked:'   The file selector appears prior to equalisation from which 
           you can select a previously prepared ASCII file of keywords. 
           If a keyword is encountered during equalisation and no 
           corresponding line exists in the opposite file, the opposite 
           file will be equalised by inserting line/s.
           All other lines are NOT equalised. This option is handy for 
           aligning source code, especially if normal equalisation 
           doesn't yield sensible results.


Example keyword file

For GFA Basic source code in LST format a simple two line file:

PROCEDURE
FUNCTION

should be suitable. Create a file containing the two lines above and 
save them in ASCII format. Something similar should be possible for 
Pascal or Modula-2. Some assemblers even support '>PART' in their 
display, which aids equalisation.

gale uses an intelligent algorithm for automatic equalisation and 
equalises most files efficiently. The algorithm isn't foolproof and if 
the files are very different will take much longer and be more likely 
to suffer errors. A status window displays progress and, via the [Esc] 
key offers an opportunity to abort equalisation if the task is taking 
too long for your liking.

Hints & tips

Before starting equalisation use the 'First difference'  [Control]+[1] 
option from the 'Find' menu to jump to the first line to be equalised.

When equalising text files with numbered chapters/section (e.g. this file) 
set gale to ignore chapter numbers in the 'Comparison mode'  dialog in the 
'Options' menu.

--> Unregistered?
    Automatic line equalisation is only available to registered users.

3.6 First difference OR First identical line

Select this option to jump to either the 'First difference' OR the
 'First identical line' depending on the 'Search for' setting in the  
 'Comparison mode' dialog.

3.7 Next difference OR Next identical line

Select this option to jump to either the 'Next difference' OR the 
 'Next identical line' depending on the 'Search for' setting in the 
 'Comparison mode' dialog.


____________________________________________________________________________

*****4. 'Edit' drop down menu



4.1 Undo

Press the [Undo] key to reverse the last change made in the topped window: 
If a line has been deleted it will be re-inserted at the correct position.
If a blank line has been inserted it will be deleted again.

Note!
If more than one line was inserted or deleted this cannot be reversed using 
the 'Undo' function.

4.2 Insert text line...

Select this option to display the 'Insert text' dialog which features the 
gale line editor. The following options are available:

















'Editor:'  Enter the desired text, or ASCII decimal or hex values, into the 
edit line. The line scrolls in real time to accommodate long lines. The 
character cursor can be positioned with a mouse click or scrolled using 
the [Left-arrow] and [Right-arrow] keys. If you also press one of the 
[Shift] keys the cursor will jump to the start or the end of the line 
respectively.

The editor shows the current cursor position in the file.

'Mode:'  In decimal/hex mode multiple decimal or hex values input on 
one line are automatically grouped into triplets and pairs (each 
corresponding to one character) respectively. In binary mode, each 
character or decimal/hex equivalent will produce a separate line in the 
file.

There are 3 modes according to the size of the values:


- Bytes                 (0-255 = $00-$FF)
- Words (2 Bytes each)  (0-65535 = $0000-$FFFF)
- Longs (4 Bytes each)  (0-4294967295 = $00000000-$FFFFFFFFF)
                        (-> all unsigned)

When editing in 'word' or 'long' values, values are automatically grouped, 
each group representing 2 or 4 bytes.


'Insert:' [Alternate]+[I]    Characters typed into the editor line are 
                           inserted at the cursor position, existing text 
                           moves along with the cursor.
'Overwrite:' [Alternate]+[W] Characters typed into the editor line overwrite 
                           any existing characters at the cursor position.

You can toggle between these two options. A round filled button shows the 
active mode.

'Transfer:'  [Alternate]+[R]

With the 'Transfer' button you can copy the adjacent line from the other 
file to the edit line, then insert it (with or without changes) in the 
file you are editing.
In the binary mode the user must input the number of bytes or characters 
that are to be copied starting from the cursor position.

'Display as:' 
'Text:'    [Alternate]+[T]  Display and edit lines as text
'Decimal:' [Alternate]+[D]  Display and edit ASCII values in decimal format.
'Hex:'     [Alternate]+[H]  Display and edit ASCII values in hex format.

In hex or decimal mode the individual ASCII values of the characters are 
displayed, which makes it possible to enter characters not normally 
accessible from the keyboard. For example, enter '144' in 'Decimal' mode 
or '90' in 'Hex' mode, then switch to 'Text' mode and '' appears in the 
edit line.

You can toggle between these three options and the text in the edit line 
is updated in real time. A round filled button shows the active mode.

Note!
In text files the input of ASCII NULL (decimal 0 or hex $00) characters is 
not possible.

Select 'OK' to insert the text into the file at the current line cursor 
position or 'Cancel' to exit the dialog without making any changes.


The [Shift] key

If two files have been loaded, all the functions in the 'Edit' menu are 
sensitive as to which [Shift] key is being pressed at the time:
The [Left Shift] key applies a function to the left hand file of the
topped window,
the [Right Shift] key applies a function to the right hand file of the
topped window.

gale (in common with many other programs) precedes the filename in
the window header bar with an asterisk '*' for each file which has
been changed since loading (or last saving).

4.3 Edit text line...

The line on which the line cursor is positioned will be displayed in the 
editor, where it can be edited. This option is functionally identical to 
 'Insert text line...'  as described above, except that it modifies existing 
lines rather than creating new ones.

In binary mode, 100 bytes are simultaneously loaded into the editor.


The [Shift] key

If two files have been loaded, all the functions in the 'Edit' menu are 
sensitive as to which [Shift] key is being pressed at the time:
The [Left Shift] key applies a function to the left hand file of the
topped window,
the [Right Shift] key applies a function to the right hand file of the
topped window.

gale shows with an asterisk in front of the filename in the mover bar
of the window that the file has been altered.

4.4 Insert line

It's often the case that a displacement of a single line is enough to make 
the entire remainder of the compared files mismatch. Using this option to 
insert a dummy line/s before the line on which the line cursor is 
positioned makes it possible to manually re-align files. Dummy lines are 
shown as black bars, the line numbering takes inserted lines into account. 
To insert 'real' text lines refer to 4.2 Insert text line... 

By holding down the [Control] key as well as the desired [Shift] key or 
while selecting the menu option, the 'Insert dummy lines' dialog is 
displayed. Any number of lines up to 999 can be entered but there is a 
pre-defined limit to the number of lines which can be inserted/deleted in 
each file which is set using the 'Maximum number of insertions and 
deletions per file' option in the 'Comparison mode' dialog from the 
'Options' menu; refer to 6.1 Comparison mode... for details.


The [Shift] key

If two files have been loaded, all the functions in the 'Edit' menu are 
sensitive as to which [Shift] key is being pressed at the time:
The [Left Shift] key applies a function to the left hand file of the
topped window,
the [Right Shift] key applies a function to the right hand file of the
topped window.

4.5 Delete line

The line on which the cursor is positioned can be deleted using this 
option; the line numbering takes deleted lines into account.


The [Shift] key

If two files have been loaded, all the functions in the 'Edit' menu are 
sensitive as to which [Shift] key is being pressed at the time:
The [Left Shift] key applies a function to the left hand file of the
topped window,
the [Right Shift] key applies a function to the right hand file of the
topped window.

4.6 Load status log...

Use this option to load status log files. These will restore the displayed 
file to the same condition as when the status log was saved, even though 
the main file itself may not have altered in any way.

When loading any file gale looks in the file's directory and the main 
gale path for a file with a matching name and either a '.EGA' or '.EGB' 
extension. If such a file is found then, provided the log file goes with 
the file in question, the status log will be loaded automatically (because 
the name and path of the associated file is saved in the log file).


The [Shift] key

If two files have been loaded, all the functions in the 'Edit' menu are 
sensitive as to which [Shift] key is being pressed at the time:
The [Left Shift] key applies a function to the left hand file of the
topped window,
the [Right Shift] key applies a function to the right hand file of the
topped window.

Hints & tips

With this function you can transfer additions made to a file simply to 
another file; just find the differences and equalise the other file by 
inserting blank lines. Now you can save the status, load in the target file 
and also load the saved status log on that side; the inserted dummy lines 
will be applied to the file and only have to be turned into text lines by 
using the 'Transfer' feature in 'Edit text line...'  as often as required.

4.7 Save status...

A status log file containing any inserted or deleted lines can be saved 
with the extension '.EGA' for a text file, or '.EGB' for a binary file.


The [Shift] key

If two files have been loaded, all the functions in the 'Edit' menu are 
sensitive as to which [Shift] key is being pressed at the time:
The [Left Shift] key applies a function to the left hand file of the
topped window,
the [Right Shift] key applies a function to the right hand file of the
topped window.

Hints & tips

With this function you can transfer additions made to a file simply to 
another file; just find the differences and equalise the other file by 
inserting blank lines. Now you can save the status, load in the target file 
and also load the saved status log on that side; the inserted dummy lines 
will be applied to the file and only have to be turned into text lines by 
using the 'Transfer' feature in 'Edit text line...'  as often as required.

4.8 Clear status...

If at any time you're not satisfied with the lines that you or the 
program has inserted or deleted you can use this option to remove 
them again. Note that this does NOT undo any changes you may have 
made using 'Insert text line...'  or 'Edit text line...' .


The [Shift] key

If two files have been loaded, all the functions in the 'Edit' menu are 
sensitive as to which [Shift] key is being pressed at the time:
The [Left Shift] key applies a function to the left hand file of the
topped window,
the [Right Shift] key applies a function to the right hand file of the
topped window.


____________________________________________________________________________

*****5. 'Window' drop down menu



5.1 Cycle

Select this option to change the topped window in turn, cycling through 
all open windows.

5.2 Help

Select the 'Help' option to display the 'Main window keyboard commands' 
dialog or 'One-line window keyboard commands' depending on which window is 
currently topped. The [Help] key can be used instead.

When a dialog is open the [Help] key calls up a context-sensitive help text. 
This is present as a so-called hypertext and to use it you need to install 
a suitable help system that can display it. 'ST-Guide' by Holger Weets is 
a very compact and easy to use example. It is freeware and is available 
from most well-ordered mailboxes and PD libraries. It is best to copy it 
in its DA form to the root directory of your boot drive and then re-set 
the computer. gale needs the files EGALE.HYP and EGALE.REF and calls 
ST-Guide automatically. If ST-Guide is present you will find a 'HELP' 
button in the dialog boxes that leads to a suitable help page in the 
hypertext when activated.

 (ST-Guide is also available for 10 DM and two
  International Reply Coupons from Holger Weets,
  Tangastr. 45, D-26121 Oldenburg, Germany).

5.3 Files

Beneath the Cycle and Help options the names of the files contained in 
the last 10 (maximum) opened windows are listed. Open windows are denoted 
with a tick before the menu option. Clicking on any listed entry (or 
pressing [Alternate]+indicated number) tops the selected window. If the 
window wasn't currently open it will be re-opened.


____________________________________________________________________________

*****6. 'Options' drop down menu



6.1 Comparison mode...

Select this option to display the 'Comparison mode' dialog. gale is 
designed to find differences or correspondences with the minimum fuss, 
and the global options are set using this dialog.

'Search for:' 
'Correspondences:' [Alternate]+[R]  Finds similarities between files.
'Differences:'     [Alternate]+[D]  Default. Finds differences between files. 
These are emphasised according to the option set in the 'Emphasis...'  dialog.

The following settings in this dialog take effect for all functions, 
i.e. also for line equalisation and functions such as 'Next difference.' 

'Lines:' 
'Treat as strings:'  [Alternate]+[T] 
'... numbers:'       [Alternate]+[N]
If lines are treated as numbers the percentage value set in the 
'Tolerance' field is used to determine whether gale considers the 
numbers as equal. This option is not available in binary mode!

'Ignore:'  Check boxes are provided so gale can ignore:
'Caps=l.c:'      [Alternate]+[L] Case sensitivity is not taken into account.
'Spaces:'        [Alternate]+[S] Leading spaces and tabs are ignored.
'Chap.numbers:'  [Alternate]+[H] Leading numbers (i.e. at the beginning   
                               of a line) are ignored. This option is   
                               handy when comparing texts with numbered  
                               paragraphs, sections, chapters etc.
                               It's also useful when sections of text  
                               have been inserted/deleted which affect 
                               numbering.
'Editor:'  [Alternate]+[E]
Sets the path to an optional external text editor. Click inside the box 
to call the file selector, then select your desired text editor. The 
editor can be called and pre-loaded (the filename(s) are passed as 
parameters) with one or two files displayed in the topped window using 
the [Control]+[E] keyboard shortcut.

'Maximum insertions and deletions per file:' 
When gale loads a file it reserves memory to insert/delete lines. 
4 bytes are needed for each dummy line insertion and each deletion 
so this setting determines the amount of memory used. gale considers 
the size of the loaded file to set a default value, but you can edit 
this value as necessary. The following alert may appear:
'Further insertion not possible, due to lack of buffer space' if you try to 
allocate too much memory.

Important
This setting only comes into effect next time gale loads a file.

--> Unregistered?
    Changes made to this dialog cannot be activated. You can only search 
    for differences, and lines are always compared as strings.

6.2 Number lines

gale can also number individual lines consecutively. For this press 
[Alternate]+[N] or click on the 'Number lines' option in the 'Options' 
drop down menu.

6.3 Emphasis...

Select this option to display the 'Mark target area' dialog which offers 
the following options:

'Off:'            [Alternate]+[F]  Switches emphasis off.
'Coloured:'       [Alternate]+[L]  Uses the colours selected in the 'Colours' 
                                 dialog.
'Rest grey:'      [Alternate]+[R]  Default. Excluded lines are greyed out.
'Bold:'           [Alternate]+[B]  Included lines displayed in bold 
                                 characters.
'Hide the rest:'  [Alternate]+[H]  Excluded lines not displayed.
'Divider only'    [Alternate]+[D]  The dividing-bar between excluded lines  
' there:'                          is deleted. This makes it easy to see 
                                 differences/correspondences quickly.
'Mark single'     [Alternate]+[M]  Characters are checked individually and 
 'characters:'                     target characters (those being searched 
                                 for) are highlighted with a grey pattern 
                                 so you can see precisely what's changed.
      Below this button is a pop-up menu which allows further options 
      to be chosen that are only active when 'Mark single characters:'  
      has been selected:

'First target'   Highlights the first character in a line that is different 
               (or equal); only one character is selected in each case.

'All'            gale compares each character in the two lines individually 
               and highlights all differences/correspondences. This option 
               is slow, especially on long lines, so only use it where 
               you're likely to get sensible results!

'Insertions'     Is the most intelligent but also the slowest setting.
               gale establishes where portions of text have been added  
               and highlights them. If correspondences are being searched  
               for (in 'Comparison mode'  dialog, see 2.2.1) the whole 
               line except for the insertion will be highlighted.
               Again only use this option where you are likely to get 
               sensible results.
               The algorithm used for this option is complex which takes 
               time and requires a certain amount of intelligence from 
               the computer. Since computers are pretty dumb gale 
               occasionally isn't able to display perfect results!


Hints & tips

The most sensible emphasis setting is probably 'Rest grey,' because you can 
easily see the differing or corresponding lines. However, empty lines are 
NOT emphasised in this mode. Turn on line numbering to easily locate empty 
lines.

--> Unregistered?
    This dialog is not available. You can toggle 'Emphasis...' on (which 
    selects the 'Rest grey' option) and off.

6.4 Display...

Select this option to bring up the 'Display' dialog. The following options 
are available:

'Display line cursor as:'   Four alternative displays are provided:
'Inverted bar'    [Alternate]+[I] (default)
'Outlined bar'    [Alternate]+[U]
'Small bar'       [Alternate]+[M]
'Arrows'          [Alternate]+[R]

'TABs:'           [Alternate]+[T], then select with [Up/Down-arrow]
You can choose here whether and how tab stops in text files (and spaces
between the columns in binary files) are to be displayed. '(In the text
below, the asterisk '*' is used in place of the ASCII 9 'clock' character 
of the actual dialog, since the latter does not show up in text.)' 

'Off, As *'       Shows each set tab stop as the ASCII 9 Tab character,
                with no filling.
'Fill with *'     Fills the tabbed portions of lines with ASCII 9 characters. 
'Fill with ' ''   Fills the tabbed portions with spaces.

See Examples for the effect of these options.

'Width:' 
Enter a value into the editable field. This number is used every time an 
ASCII Tab character is encountered to increment the next column position
to a multiple of the value. 

'Sub-division:' 
Text or binary files can be sub-divided into groups of lines using a faint 
horizontal line. Enter the desired value into the editable field. Note that 
2 and 4 line divisions can also be achieved with the corresponding keys 
on the numerical keypad at any time without calling this dialog.

With the [1], [2], [4] and [0] keys of the numerical keypad you can 
switch between these options without first having to call up the above 
dialog.

A button offers the choice of decimal or hex line numbering.
The order in which the various columns are displayed in binary mode can be 
altered with popups in this dialog.


Hints & tips

This option is particularly suitable when viewing binary files as the line 
can be used to display the boundaries between words and longs.
Set to '2' to display word boundaries.
Set to '4' to display long boundaries.

'Info line:'  [Alternate]+[I]
Select the check box to display an Info line just under the GEM Window 
header bar. Default is off '(unchecked).' 
In text mode the length the line highlighted by the line cursor is shown 
for both files.
In binary mode the character at the cursor and the following values will 
be evaluated and displayed:
A word value 'W:' from the 2 characters or bytes starting at the cursor 
position), a long value 'L:' (4 characters) and a long value in
hexadecimal form.

This is useful for analysing file formats or during comparison to recover 
data values (for example, version numbers in INF files etc).

--> Unregistered?
    This dialog is not available. The defaults apply so no Info line!

6.5 Fonts...

Select this entry from the 'Options' menu to display the 'Select font' 
dialog. Using this dialog you can select the font and point size to be 
displayed in the main window from any of the available options.
If GDOS (or equivalent) and a valid 'ASSIGN.SYS' is installed GDOS screen 
fonts can be selected. gale does not support the use of proportional 
fonts. The following options are available:

'Used for:'  [Alternate]+[F]
           A pop-up menu sets the font and point size for each of the 
           following options (different fonts/sizes can be applied to each):
          'File window(s)' 
          'One-line window(s)' 
          'Topmost window' 
           A preview window displays a sample of the selected font and 
           point size.
'Font:'      [Alternate]+[T]
           A pop-up menu displays all installed fonts; select the desired 
           font.
'Size:'      [Alternate]+[S]
           A pop-up menu displays a choice of point sizes. The choice 
           depends on active font selected.

6.6 Colours...

Select this option to display the 'Colours' dialog. Each of the 
following options display a pop-up menu from which the desired colour 
can be selected:

'Standard:'       [Alternate]+[S]   Default 'Black.' Used for all lines 
                                  other than those emphasised.
'Inserted line:'  [Alternate]+[I]   Default 'Yellow.' Used for inserted lines.

In the 'Special' box: 
'Emphasis:'       [Alternate]+[E]   Default 'Red.' Used for emphasised lines.
'Single'          [Alternate]+[H]   Default 'Pattern.' Used to highlight 
 'character:'                      individual characters. The pattern 
                                  option is provided specifically for 
                                  monochrome displays.

The colours available depend on your system. At 640x200 (ST medium) 
you'll have 4 colours to chose from whereas on the TT or Falcon and 
with some graphics cards up to 16 colours will be available. Although 
the defaults are colours, monochrome users will not find these 
available for selection in the pop-ups!

Important!
The 'Special' options are only active if 'Coloured' is selected in the 
'Mark target area' of the 'Options/Emphasis...' dialog.

--> Unregistered?
    Because the 'Emphasis...' dialog is unavailable in the unregistered 
    version you cannot select the 'Coloured' option so the 'Special' 
    options are not available.

6.7 Save settings...

Select this option to display the file selector which can be used to save 
the following settings to an .INF file:
- Settings selected for each file, including search text etc.
- Window and dividing-bar positions.
- Names of loaded files.
On starting gale the file 'EGALE.INF' if found is loaded automatically.

6.8 Load saved settings...

Select this option to display the file selector which can be used to load 
an .INF file. After selecting the desired .INF file a dialog appears asking 
whether the existing open windows should be closed before new or additional 
files are loaded. The following options are available:

'No:'          [Alternate]+[N] or [Return]
             The selected INF file is not loaded.
'Yes:'         [Alternate]+[Y]
             The existing window/s are closed and the INF file and 
             associated files and settings are loaded.
'Additional:'  [Alternate]+[A]
             The existing window/s remain on screen and the INF file and 
             associated files and settings are superimposed.

6.9 Quick save and exit

In addition to the normal saving of the default settings you can use this 
option to exit gale and save your work and settings.

This option doesn't overwrite 'EGALE.INF' but creates a second, temporary, 
parallel file called 'EGALE.TMP' in the same directory as 'EGALE.PRG'.  
Next time gale is started 'EGALE.TMP' is read in preference to 'EGALE.INF', 
gale is restored to its previous environment and 'EGALE.TMP' is deleted.


____________________________________________________________________________

*****7. Other functions



7.1 Display functions

In most cases when two text files have been loaded the lines will exceed 
the width of the window, so you won't be able to see the entire line. 
By moving the dividing bar the hidden portion can be revealed.

The dividing bar can be moved to any position within the window by 
dragging it with the mouse. Alternatively the following keyboard 
shortcuts also move the dividing bar:

'(Use the bracket keys on the number pad)' 
[(]            5 characters to left.
[)]            5 characters to right.
[Shift]+[(]    1 character left.
[Shift]+[)]    1 character right.
[Control]+[(]  To left margin, displays right hand file.
[Control]+[)]  To right margin, displays left hand file.
[Esc]          Toggles between left and right hand file display.
[Space]        Returns divider bar to its default screen centre position.

Instead of moving the dividing bar it's also possible to scroll the text 
sideways within the text windows. The following options are available:

[Left-arrow]             5 characters to left.
[Right-arrow]            5 characters to right.
[Shift]+[Left-arrow]     1 character to left.
[Shift]+[Right-arrow]    1 character to right.
[Control]+[Left-arrow]   1 screen width to left. *
[Control]+[Right-arrow]  1 screen width to right. *


The line cursor can be moved within the text window using the following 
options (the [Control] key can be used in place of the [Shift] key if 
prefered):

[Up-arrow]               1 line up.
[Down-arrow]             1 line down.
[Shift]+[Up-arrow]       1 page up.
[Shift]+[Down-arrow]     1 page down.
[ClrHome]                To start of text.
[Shift]+[ClrHome]        To end of (the longer) text.

7.2 Single line comparison using one-line windows

A double mouse click on any line or pressing Return opens the one-line
GEM window which displays the same line number from both files above
one another. This means the lines are displayed the full width of the
screen and is particularly useful to check exactly how the two lines
differ/agree. The characters in a one-line window are always compared
individually and the differences or correspondences highlighted (the
options are described in more detail in the 'Emphasis...' dialog,
refer to the 'Mark each character' and 'All'  options in 2.2.2).

In the one-line window each of the two text lines shows a double marker 
line starting where the line finishes and running to the right edge of 
the window. Thanks to this marker line you can easily establish the real 
length of each line, since it is easy to miss one or more spaces hanging 
at the end of the line and then wonder why gale marks two apparently 
identical lines as 'different'.

The cursor [Up-arrow] and [Down-arrow] or window up and down scroll arrows 
automatically perform a 'Next difference' / 'Next identical line' command.
Holding down either the [Shift] or [Control] keys while pressing the cursor 
keys enables normal line by line scrolling.

A double click in the one-line window sets the line cursor in the main 
window to the line clicked on in the one-line window.

7.3 Moving files

Files can be dragged between gale windows and the desktop (i.e the
background) which makes it easy to compare and view any desired
file(s). For example, let's consider two windows which each contain
two files:

Window 1 contains: A.TXT  B.TXT
Window 2 contains: C.TXT  D.TXT

Currently A.TXT is being compared with B.TXT and C.TXT is being
compared with D.TXT. Let's suppose we'd like to compare A.TXT with
D.TXT. To do this a 'click and drag' mouse action is used:

Hold down either [Shift] key then click and hold down the left mouse
button anywhere inside window 1 over B.TXT which displays an icon.
Drag and release the icon over D.TXT in window 2 and gale
automatically exchanges B.TXT and D.TXT so the windows look like this:

Window 1 contains: A.TXT  D.TXT
Window 2 contains: C.TXT  B.TXT

To move the files back to their original windows simply reverse the
process. It's also possible to split a window comparing two files into
two windows each displaying a single file. To do this drag either file
onto the desktop (whilst holding down the [Shift] key).

In summary:
Drag a file into a two file window to exchange files.
Drag a file into a single file window to move a file.
Drag a file onto the desktop to create a new file window.
7.4 Quick save and exit     [Shift]+[Control]+[Q]

7.5 Iconifying

Iconifying can be useful while using a multitasking operating system. 
An iconified window is reduced to a minimum size and displayed as an
icon instead of the actual window contents.
To iconify a window: Use the mouse together with one of the following
keys:
- [Alternate]: Iconifies the window
- [Control] or [Shift]+[Alternate]: Iconifies all gale windows into a
  single icon window.
- [Shift]: Iconify all gale windows, each with indivual icons
Instead of clicking on the Closer button, you can press the [Space bar].
To restore an iconified window, simply click on it!
ICFS, the Window iconify utility, is supported.


____________________________________________________________________________

*****8. Advanced gale features


This chapter is designed to explain some of the advanced system features 
gale can take advantage of. It's NOT designed for beginners, who should 
refer to the earlier chapters.


8.1 Passing parameters

gale can be called from a DOS type shell so long as the command line 
passes parameters via the desktop for gale to evaluate. Under multitasking 
systems, so long as your shell supports them, you can drag two files to 
gale's icon without gale being loaded unnecessarily a second time.

Input the name of the file(s) you want to load. This may contain a path: 

  EGALE file_s.txt
(if this file is to be loaded)
  EGALE file_a.txt file_b.txt
(if these two files are to be loaded and compared).

This eliminates the automatic appearance of the file selector when the 
program starts.

Passing '-b' as an additional parameter causes gale to load the files
in binary mode:

  EGALE -b bugged.prg new.prg

Power users may like to use wildcards, both '*' and '?' are supported. 
gale will search for files that fit the entered file 'mask'.

If both names have the same search pattern then the second name can be 
omitted. Example:

EGALE erg?.dat    compares the files  ERGA.DAT   and  ERGB.DAT
EGALE TEXT*.DOC   compares the files  TEXT_1.DOC and  TEXT_21X.DOC

Note: Filename/s may not start with the '*' character.

The file data can also contain a path. If two files with the same name but 
in different folders are to be compared then you only need to input the 
folder for the second name. For example if:

EGALE \tex\letter.tex \tex\doc\

is passed gale compares the two files:

\TEX\LETTER.TEX  and  \TEX\DOC\LETTER.TEX

Note:
For a given search pattern gale will only find the first matching files in 
the relevant folder. If further files that match the pattern are present 
and gale does not select the desired ones then the pattern will have to be 
specified more precisely.

It's also possible to input a single filename fully, in which case the path 
is adopted from the other file, e.g.:

EGALE \tex\file_a.txt file_b.txt

If you only pass one file name to gale then only this file is loaded.

8.2 Passing parameters using EGALEPAR.PRG

Unfortunately the GEM desktop can't pass two arguments to a program. 
Start EGALEPAR.PRG instead of EGALE.PRG. EGALEPAR starts then EGALE.PRG. To 
pass two arguments, first drag the first file on the EGALEPAR icon then 
drag the second file to the EGALEPAR icon. Then EGALEPAR starts EGALE.PRG, 
passing both arguments.

You can start EGALEPAR without parameters or passing two arguments as well. 
In this case EGALE.PRG is started with these parameters.

Pressing the 'Control' key whilst starting EGALEPAR causes the program to 
clean its file buffer.

EGALEPAR.PRG must be in the EGALE folder!

EGALEPAR is written by Werner Buthe, Frankfurt.


____________________________________________________________________________

*****9. Technical notes



9.1 Protocols supported

- gale understands VA_START. That means that under multitasking systems 
  and/or gale installed with Gemini, files can easily be passed to gale.
- gale understands WM_UNTOPPED (WiNX). Provided you have WiNX installed 
  you can perform the Cycle windows function by a short click on the 
  title bar of the topped window.
- gale supports UFSL (Universal File SeLector) if present.
- gale supports ICFS (Iconify-Server) if present.
- For passing parameters gale understands the xARG-(ARGV)-standard. 
  The process is also used for starting the editor.
- gale can send AV_DRAG_ON_WINDOW-messages

9.2 Known bugs

With horizontal scrolling and 'Mark single characters: All ' selected in the 
'Emphasis...'  menu you can get disturbances with fonts whose width is not a 
multiple of 8 pixels due to interference from the emphasis pattern when 
'Pattern' has been selected in the 'Options/Colours...'  menu. This can also 
happen with inserted lines and is a limitation of the VDI 'NOT' gale!

9.3 Hints & tips

The menu shortcuts follow Ofir Gal's GEM-list proposals as far as practical 
but remain fully editable using an RSC file or file editor, such as gale.


____________________________________________________________________________

*****10. Miscellaneous



10.1 Credits

I would like to thank:

- Werner Buthe, Frankfurt Germany, for his friendly support when 
  programming some fast assembler routines and for teaching me 'correct' 
  assembler programming by telephone.
- Joe Connor, Colchester England, for editing the English documentation 
  and undertaking distribution of the program in England.
- Christof Schardt, Darmstadt Germany, for his good ideas and the 
  original program, COMPARE.
- Peter West, London England, for his hard work translating the program 
  and documentation into English.


Also thanks to the Beta testers:
  Rainer Albrecht, Aleks Almonacid-Lessmann, J.Jrgen von Bargen,
  Heinz Bokel, Robert Federle, Carsten Guthardt-Schulz, Werner Herrmann,
  John Mcloud, Reiner Show me Rosin, Robert Schaffner, 
  Manfred Ssykor, Gert Stamminger, Arndt Weinmann, Ralf Zimmermann.

Our thanks also to the users who, by registering, have encouraged 
the author to undertake further developments.

- gale is programmed in GFA Basic. Program development was aided by 
  Ergo!pro from Columbus Soft.

10.2 Warranty and liability

Whilst I will try to resolve any problems you may experience using gale, 
my liability, and that of any agents I appoint, for any loss or 
consequential loss you may suffer due to the use of gale is strictly 
limited to refunding your shareware fee.

- All trademarks used are recognised and acknowledged.
- All trademarks mentioned in the documentation are acknowledged and 
  recognised.

We all wish you every success using gale.
