home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 11 Util / 11-Util.zip / MERGE10P.ZIP / MERGE.DOC next >
Text File  |  1991-05-01  |  14KB  |  355 lines
  1.                                    MERGE 1.00
  2.  
  3.         Purpose
  4.         -------
  5.         MERGE compares two versions of a program source file and
  6.         generates a third file that is a "merger" of the two.  The merge
  7.         file contains all source from both versions; differences between
  8.         the two versions are bracketed by conditional compilation
  9.         directives.  Thus, either version can be compiled/assembled by
  10.         setting appropriate compiler switches or declaring constants in
  11.         the source.
  12.  
  13.         MERGE directly supports C, Pascal, and assembler.  It can be
  14.         used with languages that support conditional compilation, but
  15.         you may have to change the conditional compilation directives in
  16.         the merge file.
  17.  
  18.         MERGE is available in both DOS and OS/2 versions (distributed in
  19.         separate libraries).  Usage is identical for both versions.  The
  20.         OS/2 version is not a PM application, but it can be run in a
  21.         window.
  22.  
  23.  
  24.         Running MERGE
  25.         -------------
  26.         The general syntax for MERGE is:
  27.  
  28.             hdiff [/options] old-file new-file [merge-file]
  29.  
  30.         The simplest use of MERGE is exemplified by:
  31.  
  32.             merge oldver.c newver.c
  33.  
  34.         This compares OLDVER.C and NEWVER.C and generates a merged
  35.         version of the two, which is displayed.  You can record the
  36.         merged version in a disk file either by redirecting the output
  37.         or by specifying a third filename:
  38.  
  39.             merge oldver.c newver.c > merger.c
  40.             merge oldver.c newver.c merger.c
  41.  
  42.         In either case, MERGER.C will contain the merged version.
  43.  
  44.  
  45.         Option switches
  46.         -----------------
  47.         Option switches must precede the filenames.  They may be
  48.         introduced by either '/' or '-' and are not case sensitive.  The
  49.         options are:
  50.  
  51.         /C      Case insensitive comparison: MERGE ignores differences
  52.                 in alphabetic case in the source.  Thus, the two lines:
  53.  
  54.                         This is text
  55.                         THIS IS TEXT
  56.  
  57.                 are not reported as changed.
  58.  
  59.         /Dname  Declares the name of the conditional compilation
  60.                 constant.  For example, "/D_OS2" declares the constant
  61.                 to be "_OS2", and MERGE will use conditional compilation
  62.                 directives in the form "#ifdef _OS2" (for C).  If no
  63.                 constant name is specified, MERGE creates a name based
  64.                 on the current date and time; this allows you to use a
  65.                 merged file as one of the bases for a later merge
  66.                 without duplicating the constant name.  In general,
  67.                 however, we recommend that you specify a name.
  68.  
  69.         /I#     Specifies an indentation value.  All lines between
  70.                 conditional compilation directives will be indented the
  71.                 number of spaces specified.  For example, if you use /I2
  72.                 and the original lines were flush-left (not indented),
  73.                 the merge file might look like this:
  74.  
  75.                     #ifdef foo
  76.                       statement2
  77.                     #else
  78.                       statement1
  79.                     #endif
  80.  
  81.                 Without the /I, it would look like this:
  82.  
  83.                     #ifdef foo
  84.                     statement
  85.                     #else
  86.                     statement
  87.                     #endif
  88.  
  89.                 /I simply makes the merge file easier to read.  Valid
  90.                 value for /I are from 1 to 20.
  91.  
  92.         /Lx     Specifies the language.  The option can be any of:
  93.  
  94.                     /La     Assembler
  95.                     /Lc     C
  96.                     /Lp     Pascal
  97.  
  98.                 In assembler mode, MERGE uses the following directives:
  99.  
  100.                     IFDEF name
  101.                     IFNDEF name
  102.                     ELSE
  103.                     ENDIF
  104.  
  105.                 In C mode, MERGE uses:
  106.  
  107.                     #ifdef name
  108.                     #ifndef name
  109.                     #else
  110.                     #endif
  111.  
  112.                 In Pascal mode, MERGE uses (these are the directives
  113.                 used by Turbo Pascal; others may vary):
  114.  
  115.                     {$IFDEF name}
  116.                     {$IFNDEF name}
  117.                     {$ELSE}
  118.                     {$ENDIF}
  119.  
  120.                 The default language is based on the extension of the
  121.                 first file specified:
  122.  
  123.                     .ASM        Assembler
  124.                     .PAS        Pascal
  125.                     other       C
  126.  
  127.                 Thus, you will need the /L option only if MERGE won't
  128.                 default to the correct language for your current source.
  129.  
  130.         /S      Space insensitive: MERGE ignores differences in spacing.
  131.                 Thus, the two lines:
  132.  
  133.                         This is text
  134.                         This  is    text
  135.  
  136.                 are not considered to have been changed.
  137.  
  138.  
  139.         Examples
  140.         --------
  141.         Examples of MERGE use:
  142.  
  143.             merge one.c two.c
  144.                 Compares ONE.C with TWO.C and displays a merged version.
  145.  
  146.             merge one.c two.c three.c
  147.                 Compares ONE.C with TWO.C and creates a merged version
  148.                 in the new file THREE.C
  149.  
  150.             merge one.c two.c > three.c
  151.                 Identical to previous example.
  152.  
  153.             merge /DP386 one.c two.c three.c
  154.                 As above, but the conditional compilation directives
  155.                 will reference the constant 'P386'.
  156.  
  157.             merge /C /DDOS /I4 one.pas two.pas three.pas
  158.                 Merges Pascal files ONE.PAS and TWO.PAS into THREE.PAS.
  159.                 The file comparison is case-insensitive, and the
  160.                 constant will be named "DOS".  Conditionally compiled
  161.                 statements will be indented four spaces.
  162.  
  163.  
  164.         The merge file
  165.         --------------
  166.         As an example of what a merge file looks like, suppose we have
  167.         a DOS version and an OS/2 version of this do-nothing assembler
  168.         program:
  169.  
  170.             DOS VERSION                 OS/2 VERSION
  171.             ------------                ------------
  172.             .MODEL SMALL                .MODEL SMALL
  173.             DOSSEG                      DOSSEG
  174.  
  175.             .STACK 256                  .STACK 4096
  176.                                         EXTRN DosExit:far
  177.             .CODE
  178.             start:                      .CODE
  179.                 mov ax,@data            start:
  180.                 mov ds,ax                    mov ax,@data
  181.                 mov ax,4C00h                 mov ds,ax
  182.                 int 21h                      push 0
  183.             END start                        push 0
  184.                                              call DosExit
  185.                                         END start
  186.  
  187.         If we then run the command
  188.  
  189.             merge /D_OS2 /I2 dosprg.asm os2prg.asm prg.asm
  190.  
  191.         the new file PRG.ASM will contain the following:
  192.  
  193.             .MODEL SMALL
  194.             DOSSEG
  195.  
  196.             IFDEF _OS2
  197.               .STACK 4096
  198.               EXTRN DosExit:far
  199.             ELSE
  200.               .STACK 256
  201.             ENDIF
  202.  
  203.             .CODE
  204.             start:
  205.                 mov ax,@data
  206.                 mov ds,ax
  207.                 IFDEF _OS2
  208.                   push 0
  209.                   push 0
  210.                   call DosExit
  211.                 ELSE
  212.                   mov ax,4C00h
  213.                   int 21h
  214.                 ENDIF
  215.             END start
  216.  
  217.         Thus, we could create the DOS version via:
  218.  
  219.             masm prg;
  220.  
  221.         or the OS/2 version via
  222.  
  223.             masm /D_OS2 prg;
  224.  
  225.         Alternatively, of course, we could add:
  226.  
  227.             _OS2    equ 1
  228.  
  229.         to the source to force the OS/2 version to be assembled.
  230.  
  231.         Note the sense of the conditional compilation constant as MERGE
  232.         uses it: if the constant is defined, the second version is
  233.         created.  If the constant is not define, the first version is
  234.         created.  Keep this in mind when you're deciding on constant
  235.         names.
  236.  
  237.  
  238.         Restrictions
  239.         ------------
  240.         The following act, in one way or another, as restrictions on
  241.         MERGE:
  242.  
  243.         - File format:  MERGE is intended for use with ASCII text files
  244.         only.  Do not try to use it on binary data files, including word
  245.         processor files.
  246.  
  247.         - Available memory:  MERGE works entirely in memory, and it
  248.         needs quite a lot.  The starting memory requirement is about
  249.         220K; then, for each UNIQUE line in either file, MERGE needs
  250.         about 12 bytes plus the length of the line.  Identical lines are
  251.         stored only once, no matter how many times they occur.  Thus,
  252.         the two files:
  253.  
  254.             File 1:
  255.                 Line 1
  256.                 /* Comment */
  257.                 Line 2
  258.  
  259.             File 2:
  260.                 Line 1
  261.                 /* Comment */
  262.                 /* Comment */
  263.                 Line 2
  264.                 Line 3
  265.  
  266.         have four unique lines ("Line 1", "/* Comment */", "Line 2", and
  267.         "Line 3").  These will use about 79 bytes of storage (in
  268.         addition to the 220K starting memory!):
  269.  
  270.             4 lines @ 12 bytes:  48
  271.             Total text length:   31
  272.  
  273.         - Number of lines: neither file can exceed 5000 lines of text.
  274.  
  275.         - Line size: limited to a maximum of 1000 characters per line.
  276.  
  277.         - File contents: while not a restriction in the traditional
  278.         sense, we note here that the files should be reasonably similar!
  279.         If the two files are quite different, the resulting merge file
  280.         will be difficult to understand.  MERGE is intended for use
  281.         against two files without relatively minor differences.
  282.  
  283.  
  284.         HDIFF
  285.         -----
  286.         MERGE is derived from HDIFF, a file difference finder also
  287.         released by Cove Software.  HDIFF differs from MERGE in what it
  288.         does with the differences between the two files.  MERGE combines
  289.         the two files to create a third (merged) version; HDIFF creates
  290.         a file of differences.  This file is in the form of an editor
  291.         script that can be used to create the second version from the
  292.         first.
  293.  
  294.         HDIFF is thus useful for tasks such as software version control:
  295.         you can retain multiple versions of a source file compactly and
  296.         conveniently by retaining an original (base) version and one or
  297.         more difference files.  These difference files can be applied to
  298.         the base version to create the currect version or any previous
  299.         version.
  300.  
  301.  
  302.         Copyright/License/Warranty
  303.         --------------------------
  304.         This document and the program file MERGE.EXE ("the software")
  305.         are copyrighted by the author.  If you are an individual, the
  306.         copyright owner hereby licenses you to:  use the software; make
  307.         as many copies of the program and documentation as you wish;
  308.         give such copies to anyone; and distribute the software and
  309.         documentation via electronic means.  There is no charge for any
  310.         of the above.
  311.  
  312.         However, you are specifically prohibited from charging, or
  313.         requesting donations, for any such copies, however made; and
  314.         from distributing the software and/or documentation with
  315.         commercial products without prior permission.  An exception is
  316.         granted to not-for-profit user's groups, which are authorized to
  317.         charge a small fee (not to exceed $7) for materials, handling,
  318.         postage, and general overhead.  NO FOR-PROFIT ORGANIZATION IS
  319.         AUTHORIZED TO CHARGE ANY AMOUNT FOR DISTRIBUTION OF COPIES OF
  320.         THE SOFTWARE OR DOCUMENTATION, OR TO INCLUDE COPIES OF THE
  321.         SOFTWARE OR DOCUMENTATION WITH SALES OF THEIR OWN PRODUCTS.
  322.  
  323.         THIS INCLUDES A SPECIFIC PROHIBITION AGAINST FOR-PROFIT
  324.         ORGANIZATIONS DISTRIBUTING THE SOFTWARE, EITHER ALONE OR WITH
  325.         OTHER SOFTWARE, AND CHARGING A "HANDLING" OR "MATERIALS" FEE OR
  326.         ANY OTHER SUCH FEE FOR THE DISTRIBUTION.  NO FOR-PROFIT
  327.         ORGANIZATION IS AUTHORIZED TO INCLUDE THE SOFTWARE ON ANY MEDIA
  328.         FOR WHICH MONEY IS CHARGED.
  329.  
  330.         Businesses, governmental entities, and institutions are
  331.         prohibited from installing or using the software on their
  332.         systems without specific permission.  Licenses are available
  333.         from The Cove Software Group at the address shown below.
  334.  
  335.         No copy of the software may be distributed or given away without
  336.         this document; and this notice must not be removed.
  337.  
  338.         There is no warranty of any kind, and the copyright owner is not
  339.         liable for damages of any kind.  By using this free software,
  340.         you agree to this.
  341.  
  342.         The software and documentation are:
  343.  
  344.                              Copyright (C) 1991 by
  345.                              Christopher J. Dunford
  346.                             The Cove Software Group
  347.                                  P.O. Box 1072
  348.                             Columbia, Maryland 21044
  349.  
  350.                                 (301) 992-9371
  351.                         CompuServe 76703,2002 [IBMNET]
  352.                 Internet/Bitnet, etc.: 76703.2002@compuserve.com
  353.  
  354.                 Software and documentation author: Chris Dunford
  355.