CMPFILE Textfile Comparison Program.
Written by Gordon McNeil.
Version 1.0:  29th February 1992.


COPYRIGHT NOTICE

CMPFILE v1.0 is  not  in  the  public  domain.   It  may  not be
distributed in any form  or  by  any  means  without the express
written consent of the author.


PROGRAM DESCRIPTION

CMPFILE is  a  powerful  textfile  comparison  program.   It was
designed primarily as an  aid  in managing programming projects,
but it could equally  be  used  for  any  purpose which requires
standard ASCII textfiles to be compared.   An example of its use
would be the comparison of two versions of a source code file to
determine whether  any  errors  have  been  introduced  into the
latest version of the code.

The  program   will   run   on   any   Atari ST   in   medium or
high resolution.  It features  an  easy  to  use  GEM interface,
intelligent comparison routines and many user-definable options.
It is capable of comparing files of any length.

In  addition  to  this  textfile,  you  should  have  the  files
CMPFILE.PRG and CMPFILE.RSC.

To use CMPFILE,  simply  enter  the  names  of  the  files to be
compared in  the  fields  at  the  top  of  the  form  and press
<Return>.  The default settings will produce a list of any lines
which differ on the screen.  Press  any key to pause the listing
or <Esc> to  abandon  it.   A  full  description  of the options
available is given below.


USING CMPFILE

1. Entering the names of the files to compare.

The names of the files to  be  compared should be entered in the
fields marked 'File 1' and 'File  2'  on  the form.  They can be
entered directly from the keyboard.  Alternatively, click on one
of the 'Select' buttons to enter the name using the standard GEM
file selector.  If either  of  the  files  are  not  in the same
directory as the program, the  full path specification should be
entered.

2. Listing output.

By default, the list  of  differences  is  output to the screen.
This can be changed to  direct  the  listing to either a printer
(connected to the parallel port) or to a diskfile by clicking on
the appropriate option on the form.   If 'Disk' is selected, the
file created will be  named  after  the  first  file entered for
comparison ('File 1' on the form) but with the extension altered
to that specified in  the  'File  ext'  field  of the form.  The
default extension for the differences file is '.MTC'.

3. The list of differences.

Two types of differences can be listed:

   a) If the same line is present in both files but has been
      altered in one, both lines  are listed giving the line
      number of each within their respective files.

   b) If a number of  lines  have  been  added to one of the
      files, the inserted lines are  listed with their line-
      number and are marked off  in  the listing as a 'Block
      Of Inserted Lines'.

During comparison, empty lines are  ignored, as are leading tabs
and spaces within each line.

The listing can be abandoned at  any  time by pressing the <Esc>
key.  If it is directed to the  screen, it can also be paused by
pressing any other key.


4. Program options.

By default, file comparison  is  case-dependent: any lines where
even the case of a  character  differs  will  be listed as being
different.  To make the  comparison case-independent, select the
'Case ind' option.

If the  output  listing  is  directed  to  either  a  printer or
diskfile it will not normally be  output to the screen.  To echo
the listing to  the  screen,  select  the  'Echo'  option.  This
option has no meaning if output to screen is already selected.


5. Resynchronization.

If file  comparison  were  performed  purely  on  a line-by-line
basis, a single inserted line in either of the files would cause
all lines following the inserted  line  to  be reported as being
different.  The files get out  of synchronization.  CMPFILE gets
round this problem by  searching  forward  in  the  files to re-
establish synchronization.  This allows  it  to correctly report
inserted blocks of text within  the  files  in most cases.  This
option should normally be  left  selected.   However,  it can be
switched off by clicking on  the  'Resynch' option.  This speeds
up file-comparison substantially  in  cases  where  neither file
contains inserted lines.

A problem created by searching  forward  in  this manner is that
the program can be fooled  by  recurring lines within the files.
Normally, it will be able to recover but will incorrectly report
some lines as differing.   Typically,  this  appears as a report
showing a block of  inserted  lines  in  one  file followed by a
report showing the same block  as  being  inserted in the second
file.  The  likelihood  of  this  occurring  can  be  reduced by
limiting the depth  (i.e.  the  number  of  lines)  by which the
program  searches  forward  in   it's  attempt  to  re-establish
synchronization.  The 'Synch  depth'  parameter  is provided for
this purpose.  The default setting is  24,  but it can be set to
any value between  1  and  99.   If  the  maximum  value (99) is
entered, the search will continue until  the  end of the file is
reached if necessary.  Ideally, it  should  be set to the lowest
value which can cope with the changes made to the file.  Setting
the value as low as  possible  has  two advantages: it speeds up
the comparison and it  reduces  the  probability  of the program
being fooled by recurring lines.


6. Online help.

During  use  of  CMPFILE,  various   prompts  and  messages  are
displayed in a box at the bottom  of  the form.  If you click on
the 'Help' button, the mouse  cursor  will  change to a pointing
hand.  Clicking on any active  component  of  the form will then
produce a message outlining its function.

Finally, click  on  the  button  marked  'CmpFile'  for  further
details of the program.
