High Voltage Shareware/high1.zip/high1/DIR3/FCMERG10.ZIP/FCMERGE.DOC

Text File | 1993-07-14 | 16KB | 391 lines

                                 FCMERGE Ver. 1.0
                          Copyright (c) 1993 Mike Albert
                                     July 1993



     1   INTRODUCTION

     FCMERGE merges two sets of changes to an ASCII file into a single file.
     FCMERGE is designed to handle program source files, but will also work
     other types of files (e.g. English text).  E.g. if two programmers have
     modified a program independently, FCMERGE will combine their changes
     into a single source file.  If the changes conflict, FCMERGE identifies
     the conflicts so the programmers can resolve them.

     Note that FCMERGE does it's best to identify conflicts accurately, but
     there's no guarantee that all conflicts will be found.  Changes can
     conflict even when they are not close to each other.  Since FCMERGE
     identifies conflicts by the closeness of changes, it's not possible for
     it to find conflicts with complete reliability.  You should always
     examine your output to ensure that it is correct.  I suggest you use FC
     (my file comparison utility) to compare each modified file with the
     merged file.  You may also want to experiment with the -c<n> command
     line option, which controls how close two changes must be to be marked
     as conflicting.



     2   OPERATION

     To merge two sets of changes to a file into a single file:

         fcmerge  options  origfile  file1  file2  outfile
     or:
         fcmerge  options  origfile  file1  file2

     where:

         origfile    original file

         file1       first modified version of origfile

         file2       second modified version of origfile

         outfile     output file containing merged changes (if missing,
                     output is to standard output)

     and options are:

         -c<n>       conflict proximity - if there are less than <n> lines
                     between a change in file1 and file2, FCMERGE indicates
                     that the changes conflict.  To mark fewer changes as
                     conflicting make <n> smaller; to mark more, make <n>
                     larger.  The default value of <n> is 5.

     For example, assume Mike changed file qsort.old to make file qsort.mik
     and Pam made different changes to the same file to make file qsort.pam.
     Then:

         fcmerge  -c8  qsort.old  qsort.mik  qsort.pam  qsort.new



                                       - 1 -

     merges both sets of changes and places the result in file qsort.new.
     Changes that are separated by 8 lines or less are listed as conflicting.



     3   DETAILED OPERATION

     FCMERGE can be used on any IBM-compatible computer with MS-DOS versions
     2.0 and later.  The amount of memory required is dependent on file size.
     100K is enough for small files, while up to 425K is needed for large
     ones.  Files containing up to 16,300 lines can be merged.

     The file names specify a drive and directory in the normal MS-DOS
     manner.  If no drive is specified, FCMERGE looks for files on the
     current drive.  If no directory is specified, FCMERGE looks in the
     current directory.  MS-DOS wild-card characters can be used in all but
     the first file name.

     FCMERGE only processes lines of up to 2,000 characters.  If FCMERGE
     encounters a longer line, it breaks it after the 2,000th character to
     make two separate lines.

     FCMERGE works by first determining the two sets of changes, and then
     applying them together to the original file to make the merged file.
     This works fine if the changes don't apply to the same lines of the
     file.  But if two changes overlap, FCMERGE can't figure out how to
     resolve the conflict.  E.g. if lines 3 to 8 were deleted in the first
     change, and a line was inserted after line 5 in the second change, the
     changes almost certainly conflict with each other.  FCMERGE checks for
     such problems.  When it detects a conflict, it inserts an error message
     in the output file, and then outputs the lines of the original file, the
     lines of the first changed file, and the lines of second changed file.
     FCMERGE also beeps and displays and error message on the screen when it
     completes to warn you of the problem.  When this occurs you must examine
     the file, search for the error message that identifies conflicts, and
     change the file to resolve each conflict.

     A similar problem may occur if a change in one file is close to, but
     doesn't overlap, a change in the second.   E.g. if line 5 has been
     replaced in the first file and line 7 has been replaced in the second,
     there's a reasonable chance that one change will effect the other and
     cause a problem.  When this occurs, FCMERGE behaves as if the changes
     actually overlapped.  Since there is no hard and fast rule for how many
     lines may separate two changes without causing a problem, FCMERGE
     provides the -c<n> option so you can specify this value yourself.  The
     default value is 5.  If you find that FCMERGE is overly cautious in
     identifying conflicts, you can specify a lesser value so FCMERGE will
     mark fewer changes as conflicts.  If you find that FCMERGE is not
     identifying conflicts that it should, you should specify a greater value
     so FCMERGE will mark more changes as conflicts.



     4   FCMERGE MESSAGES

         Error: argument -<x> is invalid
             FCMERGE couldn't recognize the argument you specified on the
             command line (argument <x>).  Check the list of arguments that
             FCMERGE accepts to determine what options you can use.  You can
             list the options FCMERGE recognizes by typing "fcmerge ?".



                                      - 2 -

         Error: couldn't create output file <f>
             FCMERGE couldn't create output file <f> which you specified on
             the command line.  Make sure you specify the correct file name,
             with the directory and drive if needed, on the command line.  If
             you didn't specify a directory or drive, FCMERGE used the
             current directory and drive.  Also make sure that you can write
             to the directory, and that the drive has sufficient free space.

         Error: couldn't create difference file <f>
         Error: couldn't open difference file <f>
             FCMERGE couldn't create or open file <f>.  This file is created
             by FCMERGE to store temporary information, and is deleted before
             FCMERGE completes.  FCMERGE tries to create these files in the
             current directory.  Make sure that the current directory is set
             correctly, that you can write to and read from that directory,
             and that the drive has sufficient free space.  If this message
             occurs and you can't figure out how to correct the problem,
             please contact FCMERGE support.

         Error: couldn't open file <f>
             FCMERGE couldn't open file <f> which you specified on the
             command line.  If you didn't specify a directory or drive,
             FCMERGE looked in the current directory and drive.  Make sure
             you specify the correct file name, with the directory and drive
             if needed, on the command line.

         Error: more than four file names specified
         Error: fewer than three file names specified
             FCMERGE didn't find the right number of file names on the
             command line.  You must specify either three names (the original
             file and the two changed files) or four names (the original
             file, the two changed files, and the output file) on the command
             line.  If you forgot to specify the minus sign ("-") in front of
             an option, FCMERGE interpreted it as an input file name.

         Error: more than 16,300 lines in file <f>
             File <f>, which you specified on the command line, contains more
             than 16,300 lines.  FCMERGE can only process files containing up
             to 16,300 lines.

         Error: not enough memory to process these files
             FCMERGE needs more memory to process these files than is
             available.  The only way to correct this problem is to run on a
             machine with more memory or remove any memory-resident programs.
             This problem only occurs when comparing large files on machines
             with small memory configurations.

         Error: some changes conflict with each other; search for "<<<" in
         the output file
             FCMERGE found one or more conflicts between the the two sets of
             changes.  FCMERGE outputs a line starting with the characters
             "<<<" noting the conflict, followed by the conflicting lines of
             the original file, followed by a line of '-' characters,
             followed by the conflicting lines of the first change file,
             followed by another line of '-' characters, followed by the
             conflicting lines of the second change file, followed by a final
             line of '=' characters.  When you see this message, you must
             search the output file for the "<<<" characters to find each
             conflict, and merge the conflicting changes manually with a text
             editor.



                                      - 3 -

         Error: the -c option value is not a number
             FCMERGE couldn't recognize the value specified with the -c
             option on the command line.  This option accepts one or more
             decimal digits, e.g. -c10 to specify a conflict proximity of 10.

         Error: unexpected end of file reading difference file
         Error: format error in difference file
             FCMERGE encountered an error when reading a difference file.
             The message indicates an internal error which is not caused by
             the user, and should not occur in normal operation.  If it does,
             please contact FCMERGE support.

         Error: output failed, disk probably full
             FCMERGE detected an error when writing a file.  The file may be
             either the output file specified on the command line, or a
             temporary file created in the current directory.  The most
             likely cause of this error is a full disk.  Make sure that the
             output drive and the current drive have sufficient free space,
             and that you can write there.


     5   LICENSING, WARRANTY, and REGISTRATION

     FCMERGE is distributed as shareware.  I encourage you to try FCMERGE and
     share it with friends as long as:

         The FCMERGE program and this documentation file are not modified and
         are distributed together.

         FCMERGE is not provided as a part of any other product.

         No fees, beyond a reasonable fee for media, duplication, or
         downloading costs, are charged.

         FCMERGE is not used for commercial, government, or business purposes
         without registration.  Each registration is for a single person or a
         single computer.

     If you find FCMERGE useful and decide to use it regularly, you are
     required to register.  All registration payments will be donated to
     Oxfam America, an international development and disaster relief agency.
     It's a worthy charity that I've been supporting for many years.  For
     more information on Oxfam see section 6.

     When you register you get the satisfaction of saving lives in Africa,
     Asia, and South America, and encourage me to produce more software at
     reasonable prices.  You also get the following benefits:

         I'll send an updated version of FCMERGE to you at no additional
         cost.  You can request this at any time.  I'll do this once per
         registered user.

         I'll answer questions on FCMERGE and its use.  You can contact me at
         the address shown below or via CompuServe mail.

         If any important bugs are found I will notify you.

         I'll make an attempt (but can't guarantee) to fix any problems you
         find.




                                      - 4 -

     Registration is $25.  Please make your check payable to Oxfam America -
     I'll send your checks to Oxfam and record your registration information.
     I'll also accept original canceled checks or receipts from Oxfam that
     list you as the donor.  Please send payments, registration information,
     and any other correspondence to:

                Mike Albert
                P. O. Box 535
                Bedford, MA   01730

     I can also be reached via CompuServe mail; my userid is [70325,1134].

     Anyone can order the latest version of FCMERGE directly from me for a
     fee of $5.00.  Just send the order (make sure it contains your mailing
     address) with your check to the above address.  You'll receive a 5 1/4
     inch 360Kb floppy disk containing the executable and documentation
     files.  If you need other formats (5 1/4 inch 1.2Mb or 3 1/2 inch 720Kb
     or 1.44Mb) I can provide them.  I'll also include other shareware
     products I produce.  If you live outside North America, please send
     extra money for the increased postage.

     I welcome all comments and suggestions concerning FCMERGE.  I'd like to
     know how you are using FCMERGE, where you obtained it, and what
     problems, bugs, or weaknesses you find.  If you tell me about
     enhancements or changes you're interested in, I'll make an effort to
     provide them.

     This program is provided "as is" without warranty of any kind, either
     express or implied, but not limited to the implied warranties of
     merchantability or fitness for a particular purpose.  The entire risk as
     to the results and performance of the program is assumed by the user.
     Should the program prove defective, the user assumes the entire cost of
     all necessary servicing, repair, or correction.



     6   OXFAM AMERICA

     As stated in Oxfam literature,

         "Oxfam America is an international agency that funds self-help
         development projects and disaster relief in poor countries in
         Africa, Asia, and Latin America, and also prepares and distributes
         educational materials for people in the United States on the issues
         of development and hunger.  The name "Oxfam" comes from the Oxford
         Committee for Famine Relief, founded in England in 1942.  Oxfam
         America, based in Boston, was formed in 1970, and is one of seven
         autonomous Oxfams around the world (Great Britain, Australia,
         Belgium, Canada, Quebec, Hong Kong and the United States).  Oxfam is
         a nonsectarian, nonprofit agency that neither seeks or accepts U.S.
         government funds.  All contributions are tax-deductible to the
         extent permitted by law."

     For more information, you can phone Oxfam at 617-482-1211, or write to
     them at:

                  Oxfam America
                  26 West Street
                  Boston, MA  02111-1206




                                      - 5 -

     7   FCMERGE REVISION HISTORY


         FCMERGE version 1.0 - 7/14/93

             Initial release of FCMERGE program.

























































                                      - 6 -