DIFF.DOC



Command line:
-------------

DIFF infile outfile [changebar_file] [options]

For VMS, you'll need to install DIFF as a foreign command as:

     DIFF :== $diskname:[pathname]DIFF.EXE



Command line options:
---------------------

/BAR_COL=n
Selects  the column in which the change bar will be placed.   The 
default  is column 78.  If column 0 is selected, the  change  bar 
will  be placed at the left edge of the document or source  code, 
moving  text to the right if necessary.  If a space or a  tab  is 
the first character on the line, the alignment of the text should 
not be affected.  If a nonzero column is selected, the change bar 
will  be  placed in the specified column if  possible.   If  text 
extends  over the specified column, the change bar will be  moved 
as far to the right as is necessary not to overwrite text.

A "feature" of the change-bar algorithm is that it can  recognize 
and  account  for underlined text, at least the  way  Runoff  and 
WordStar underline for "generic" printer, but not tabs.  Tabs are 
counted  as one column each.  This produces amusing results on  C 
source code.

For best results, on document files choose a column to the  right 
of your text.  On program source code with embedded tabs,  choose 
column 0.  This is admittedly an area on which the program  could 
be  improved.  I needed the underline capability, and if the  tab 
expansion is added, the code in change_bar() gets uglier than  it 
already is, e.g.  /BAR_COL=0

/TOP_SKIP=n
Used for processing formatted documents.  Its primary reason  for 
being  is  to  allow you to skip over the  header  line(s)  in  a 
document.   Header lines confuse DIFF if they are left  in  place 
because DIFF doesn't know from chopped liver about headers unless 
you  tell it, and if the pagination changes between the  old  and 
the  new files, DIFF will cheerfully changebar every header.   Be 
sure  to  account  for blank lines at the top of  the  page  that 
precede the header line(s).  The default value of /TOP_SKIP is 0, 
e.g.  /TOP_SKIP=3.

/BOT_SKIP=n
Similar in use and purpose to the /TOP_SKIP option.  It specifies 
how  many  lines  at the bottom of the page  should  be  skipped.  
Count  lines  up  from the bottom, not down from  the  top.   The 
default value of /BOT_SKIP is 0, e.g.  /BOT_SKIP=8.

/PAGE_LEN=n
Sets  the  length of a page in lines.  The default  value  is  66 
lines.   A form-feed character will override the /PAGE_LEN  value 
and cause a new page to be started.  DIFF needs to know the  page 
length  in  order to skip headers and footers  if  /TOP_SKIP  and 
/BOT_SKIP are specified.  Also, the change summary lists  changes 
by page and line number.  For nonpaginated text, such as  program 
source code, you should specify a value of /PAGE_LEN greater than 
the  number of lines in newfile so that the change  summary  line 
numbers   will   correspond   to   file   line   numbers,    e.g.  
/PAGE_LEN=2000.

/UP_CASE, /NOUP_CASE
Controls  whether  or not the case of  alphabetic  characters  is 
significant when deciding if a line has changed.  The default  is 
/NOUP_CASE, which means that the case of a letter is significant.  
This is slightly faster than /UP_CASE, e.g.  /UP_CASE.

/RE_SYNC=n
Controls how many lines must match between the two files after  a 
difference has been found before the two files are considered  to 
be  back  in sync.  The default is five lines.   Using  a  larger 
number will make DIFF smarted when considering files that have  a 
lot  of  identical  lines (such as BEGIN  or  END  statements  in 
Pascal).   Using  a smaller number will make  DIFF  smarter  when 
considering a file that has a lot of small changes spaced closely 
together.  For text, a value of 2 or 3 is good.  For source code, 
a value of 5 is pretty good.

/OUTPUT=filename
Allows  you  to  specify an output file for  the  change  summary 
listing.   In MS-DOS, this is exactly equivalent  to  redirecting 
standard  output with the greater-than command-line  option,  and 
you  can use either way in MS-DOS.  In VMS, this matches the  VMS 
standard   redirection  syntax.   The  default  for  /OUTPUT   is 
SYS$OUTPUT  on  VMS and the console on MS-DOS, but  this  can  be 
redirected as a command option, e.g.  /OUTPUT=FILE1.SUM.

/BLANKS, /NOBLANKS
Lets  you  make  blanks  lines (for my  purposes,  a  blank  line 
contains   only   spaces   or   tabs)   either   significant   or 
insignificant.    This  is  most  useful  as  it   accounts   for 
conditionally paging and trivial source code prettying.

/LOOKAHEAD=n
Controls  how far DIFF will look forward in both files to find  a 
rematch  after it finds a difference.  The default is 200  lines.  
A larger value lets you process files in which several pages  are 
added  or deleted between revisions.  A smaller value  runs  much 
faster  and uses less memory.  Resynchronization (in the  general 
case)  is proportional to the square of /LOOKAHEAD.   This  value 
also affects the amount of memory the program uses.

/SKIP1
Allows you to specify a number of pages to skip in the two  files 
before  starting the compare.  This is most useful when  skipping 
tables  of  contents, in which the page numbers  may  change  but 
nobody  cares.   The default for /SKIP1 is 0 pages.   The  /SKIP1 
option sets the page-skip values for both newfile and oldfile.

/SKIP2
Same  as /SKIP1, except that it only affects the page-skip  value 
for  oldfile.   Because  /SKIP1 affects both  files,  the  /SKIP2 
option must appear to the right of /SKIP1 on the command line  to 
have any effect.  The two option are provided because the  tables 
of  contents  may be of different lengths.   There  are  probably 
other reasons why /SKIP2 needs to be there, but I can't think  of 
any right now.

/TRACE
Conditionally compiled and turns on function tracing.


Error Messages
--------------

Error:  Must specify two files
This  occurs  if the command line does not contain at  least  two 
file names.

Out of Memory
This  error occurs if a large look-ahead is specified  and/or  if 
huge sections of text differ between the two files.

ERROR - lost sync in file <name> at page <n> line <n>
After  a  difference was located, DIFF could not find  where  the 
files  became synchronized.  To correct, increase the  value  for 
/LOOKAHEAD.  The page/line reported is the start of the point  in 
newfile at which the difference was first detected.

Error:  Can't open <filename>
DIFF was unable to open (for reading) one of the input files.  Be 
sure  that the file and path name are correct and that  you  have 
read  privilege for that file.  It may be caused by  a  forgotten 
slash (/) on an option that made DIFF interpret it a file name.

Error:  Can't create <filename>
DIFF  was unable to create the optional output  change-bar  file.  
Be  sure  that the name is a legal one and that  you  have  write 
privilege  for the directory in which the name is to  be  placed.  
Could be a forgotten slash, too.

ERROR in option <option>
This  error  occurs  when an /OUTPUT option has  a  malformed  or 
missing file name.

ERROR creating <name>
This  error occurs when DIFF is unable to create an  output  file 
for  the change summary.  Be sure that the name a legal  one  and 
that you have write privilege for the directory in which the name 
is to be placed.

Unrecognized Option: <option>
An option name is misspelled or illegal.

Error:  Too many files at <name>
More than three file names appear on the command line.












































