home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 211.lha / Spiff / README < prev    next >
Text File  |  1996-02-14  |  10KB  |  265 lines
  1. INSTALLATION
  2.     1) Change makefile settings to reflect
  3.         ATT vs. BSD software
  4.         termio vs. termcap
  5.         MGR vs. no MGR        (MGR is a BELLCORE produced
  6.                      window manager that is also available
  7.                      free to the public.)
  8.     2) Then, just say "make".
  9.         If you want to "make install", you should first
  10.         change definition of INSDIR in the makefile
  11.  
  12.     3) to test the software say
  13.  
  14.             spiff Sample.1 Sample.2
  15.  
  16.         spiff should find 4 differences and
  17.         you should see the words "added", "deleted", "changed",
  18.         and "altered" as well as four number in stand-out mode.
  19.  
  20.             spiff Sample.1 Sample.2 | cat
  21.  
  22.         should produce the same output, only the differences
  23.         should be underlined However, on many terminals the
  24.         underlining does not appear. So try the command
  25.  
  26.             spiff Sample.1 Sample.2 | cat -v
  27.  
  28.         or whatever the equivalent to cat -v is on your system.
  29.  
  30.         A more complicated test set is found in Sample.3 and Sample.4
  31.         These files show how to use embedded commands to do things
  32.         like change the commenting convention and tolerances on the
  33.         fly.  Be sure to run the command with the -s option to spiff:
  34.  
  35.             spiff -s 'command spiffword' Sample.3 Sample.4
  36.  
  37.         These files by no means provide an exhaustive test of
  38.         spiff's features. But they should give you some idea if 
  39.         things are working right.
  40.  
  41.     This code (or it's closely related cousins) has been run on
  42.     Vaxen running 4.3BSD, a CCI Power 6, some XENIX machines, and some
  43.     other machines running System V derivatives as well as
  44.     (thanks to eugene@ames.arpa) Cray, Amdahl and Convex machines.
  45.  
  46.     4) Share and enjoy.
  47.  
  48. AUTHOR'S ADDRESS
  49.     Please send complaints, comments, praise, bug reports, etc to
  50.         Dan Nachbar
  51.         Bell Communications Research  (also known as BELLCORE)
  52.         445 South St. Room 2B-389
  53.         Morristown, NJ 07960
  54.  
  55.             nachbar@bellcore.com
  56.         or
  57.             bellcore!nachbar
  58.         or
  59.             (201) 829-4392  (praise only, please)
  60.  
  61. OVERVIEW OF OPERATION
  62.  
  63. Each of two input files is read and stored in core.
  64. Then it is parsed into a series of tokens (literal strings and
  65. floating point numbers, white space is ignored).
  66. The token sequences are stored in core as well.
  67. After both files have been parsed, a differencing algorithm is applied to
  68. the token sequences.  The differencing algorithm
  69. produces an edit script, which is then passed to an output routine.
  70.  
  71. SIZE LIMITS AND OTHER DEFAULTS
  72.         file implementing limit        name        default value
  73. maximum number of lines        lines.h        _L_MAXLINES    10000
  74.     per file
  75. maximum number of tokens    token.h        K_MAXTOKENS    50000
  76.     per file
  77. maximum line length        misc.h        Z_LINELEN     1024
  78. maximum word length        misc.h        Z_WORDLEN       20
  79.  (length of misc buffers for
  80.  things like literal
  81.  delimiters.
  82.  NOT length of tokens which
  83.  can be virtually any length)
  84. default absolute tolerance    tol.h        _T_ADEF           "1e-10"   
  85. default relative tolerance    tol.h        _T_RDEF           "1e-10"  
  86. maximum number of commands    command.h    _C_CMDMAX      100
  87.  in effect at one time
  88. maximum number of commenting    comment.h    W_COMMAX       20
  89.  conventions that can be
  90.  in effect at one time
  91.  (not including commenting
  92.   conventions that are
  93.   restricted to beginning
  94.   of line)
  95. maximum number of commenting    comment.h    W_BOLMAX       20
  96.  conventions that are
  97.  restricted to beginning of
  98.  line that are in effect at
  99.  one time
  100. maximum number of literal    comment.h    W_LITMAX       20
  101.  string conventions that
  102.  can be in effect at one time
  103. maximum number of tolerances    tol.h        _T_TOLMAX       10
  104.  that can be in effect at one
  105.  time
  106.  
  107.  
  108. DIFFERENCES BETWEEN THE CURRENT VERSION AND THE ENCLOSED PAPER
  109.  
  110. The files paper.ms and paper.out contain the nroff -ms input and
  111. output respectively of a paper on spiff that was given the Summer '88
  112. USENIX conference in San Francisco.  Since that time many changes
  113. have been made to the code.  Many flags have changed and some have
  114. had their meanings reversed, see the enclosed man page for the current
  115. usage.  Also, there is no longer control over the
  116. granularity of object used when applying the differencing algorithm.
  117. The current version of spiff always applies the differencing
  118. in terms of individual tokens.  The -t flag controls how the edit script
  119. is printed.  This arrangement more closely reflects the original intent
  120. of having multiple differencing granularities. 
  121.  
  122. PERFORMANCE
  123.  
  124. Spiff is big and slow.  It is big because all the storage is
  125. in core.  It is a straightforward but boring task to move the temporary
  126. storage into a file.  Someone who cares is invited to take on the job.
  127. Spiff is slow because whenever a choice had to be made between
  128. speed of operation and ease of coding, speed of operation almost always lost.
  129. As the program matures it will almost certainly get smaller and faster.
  130. Obvious performance enhancements have been avoided in order to make the
  131. program available as soon as possible.
  132.  
  133. COPYRIGHT
  134.  
  135. Our lawyers advise the following:
  136.  
  137.                    Copyright (c) 1988 Bellcore
  138.                        All Rights Reserved
  139.   Permission is granted to copy or use this program, EXCEPT that it
  140.   may not be sold for profit, the copyright notice must be reproduced
  141.   on copies, and credit should be given to Bellcore where it is due.
  142.   BELLCORE MAKES NO WARRANTY AND ACCEPTS NO LIABILITY FOR THIS PROGRAM.
  143.  
  144. Given that all of the above seems to be very reasonable, there should be no
  145. reason for anyone to not play by the rules.
  146.  
  147.  
  148. NAMING CONVENTIONS USED IN THE CODE
  149.  
  150. All symbols (functions, data declarations, macros) are named as follows:
  151.  
  152.     L_foo    -- for names exported to other modules
  153.             and possibly used inside the module as well.
  154.     _L_foo    -- for names used by more than one routine
  155.             within a module
  156.     foo    -- for names used inside a single routine.
  157.  
  158. Each module uses a different value for "L" -- 
  159.     module files       letter used     implements
  160.     spiff.c            Y    top level routines
  161.     misc.[ch]        Z    various routines used throughout
  162.     strings.[ch]        S    routines for handling strings
  163.     edit.h            E    list of changes found and printed
  164.     tol.[ch]        T    tolerances for real numbers
  165.     token.[ch]        K    storage for objects
  166.     float.[ch]        F    manipulation of floats
  167.     floatrep.[ch]        R    representation of floats
  168.     line.[ch]        L    storage for input lines
  169.     parse.[ch]        P    parse for input files
  170.     command.[ch]        C    storage and recognition of commands
  171.     comment.[ch]        W    comment list maintenance
  172.     compare.[ch]        X    comparisons of a single token
  173.     exact.[ch]        Q    exact match differencing algorithm
  174.     miller.[ch]        G    miller/myers differencing algorithm
  175.     output.[ch]        O    print listing of differences
  176.     flagdefs.h        U    define flag bits that are used in
  177.                     several of the other modules.
  178.                     These #defines could have been
  179.                     included in misc.c, but were separated
  180.                     out because of their explicit
  181.                     communication function.
  182.     visual.[ch]        V    screen oriented display for MGR
  183.                     window manager, also contains
  184.                     dummy routines for people who don't
  185.                     have MGR 
  186.  
  187. I haven't cleaned up visual.c yet.  It probably doesn't even compile
  188. in this version anyway. But since most people don't have mgr, this
  189. isn't urgent.
  190.  
  191. NON-OBVIOUS DATA STRUCTURES
  192.  
  193. The Floating Point Representation
  194.  
  195. Floating point numbers are stored in a struct R_flstr
  196. The fractional part is often called the mantissa.
  197.  
  198. The structure consists of
  199.     a flag for the sign of the factional part
  200.     the exponent in binary 
  201.     a character string containing the fractional part
  202.  
  203. The structure could be converted to a float via
  204.     atof(strcat(".",mantissa)) * (10^exponent)
  205.  
  206. To be properly formed, the mantissa string must:
  207.     start with a digit between 1 and 9 (i.e. no leading zeros)
  208.         except for the zero, in which case the mantissa is exactly "0"
  209.     for the special case of zero, the exponent is always 0, and the
  210.         sign is always positive. (i.e. no negative 0)
  211.  
  212. In other words, (except for the value 0)
  213. the mantissa is a fractional number ranging
  214. between 0.1 (inclusive) and 1.0 (exclusive).
  215. The exponent is interpreted as a power of 10.
  216.  
  217. Lines 
  218. there are three sets of lines:
  219. implemented in line.c and line.h
  220.     real_lines --
  221.       the lines as they come from the file
  222.     content_lines --
  223.       a subset of reallines that excluding embedded commands
  224. implemented in token.c and token.h 
  225.     token_lines --
  226.       a subset of content_lines consisting of those lines that
  227.         have tokens that begin on them (literals can go on for
  228.         more than one line)
  229.         i.e. content_lines excluding comments and blank lines.
  230.  
  231.  
  232. THE STATE OF THE CODE
  233. Things that should be added
  234.     visual mode should handle tabs and wrapped lines
  235.     handling huge files in chunks when in using the ordinal match
  236.     algorithm. right now you have to parse and then diff the
  237.     whole thing before you get any output.  often, you run out of memory.
  238.  
  239. Things that would be nice to add
  240.     output should optionally be expressed in real line numbers
  241.         (i.e. including command lines)
  242.     at present, all storage is in core. there should
  243.         be a compile time decision to allow temporary storage
  244.         in files rather than core. 
  245.         that way the user could decide how to handle the
  246.             speed/space tradeoff
  247.     a front end that looked like diff should be added so that
  248.         one could drop spiff into existing shell scripts
  249.     the parser converts floats into their internal form even when
  250.         it isn't necessary.
  251.     in the miller/myer code, the code should check for matching
  252.         end sequences.  it currently looks matching beginning
  253.         sequences.
  254.  
  255. Minor programming improvements (programming botches)
  256.     some of the #defines should really be enumerated types
  257.     all the routines in strings.c that alter the data at the end of
  258.         a pointer but return void should just return the correct
  259.         data. the current arrangement is a historical artifact
  260.         of the days when these routines returned a status code.
  261.         but then the code was never examined,
  262.         so i made them void . . .
  263.     comments should be added to the miller/myer code
  264.     in visual mode, ask for font by name rather than number
  265.