home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional / OS2PRO194.ISO / os2 / prgramer / vcomp / manual.doc < prev    next >
Text File  |  1992-03-05  |  26KB  |  700 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.                                    Visual Compare
  16.  
  17.                                     Version 1.32
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.                      A file comparison utility for programmers.
  49.  
  50.  
  51.         Copyright Notice
  52.  
  53.         Copyright (C) John R. Whitney 1991
  54.         All rights reserved.
  55.  
  56.  
  57.         Trademarks
  58.  
  59.         IBM and OS/2 are registered trademarks of International Business
  60.         Machines Corporation.
  61.  
  62.         Lotus is a registered trademark of Lotus Development Corporation.
  63.  
  64.         Intel is a registered trademark of Intel Corporation.
  65.  
  66.         Microsoft is a registered trademark of Microsoft Corporation.
  67.  
  68.  
  69.         Disclaimer and Agreement
  70.  
  71.         Visual Compare is supplied as is, without any warranty.  To the
  72.         extent permitted under applicable law, Whitney Software, Inc.
  73.         disclaims all warranties, either express or implied, including but
  74.         not limited to implied warranties of merchantability and fitness for
  75.         a particular purpose.
  76.  
  77.         In no event shall Whitney Software, Inc. be liable for any damages
  78.         whatsoever (including, without limitation, damages for loss of
  79.         business profits, business interruption, loss of business
  80.         information, or other pecuniary loss) arising out of the use of or
  81.         inability to use this Whitney Software, Inc. product, even if Whitney
  82.         Software, Inc. has been advised of the possibility of such damages.
  83.         Some states do not allow the exclusion of liability for consequential
  84.         or incidental damages, so the above limitation may not apply to you.
  85.  
  86.         Visual Compare is a "shareware program" and is provided at no charge
  87.         to the user for evaluation.  Feel free to share it with your friends,
  88.         but you may not give it away altered or as part of another system.
  89.         The essence of "user-supported" software is to provide personal
  90.         computer users with quality software without high prices, and yet to
  91.         provide incentive for programmers to continue to develop new
  92.         products.  If you find this program useful and find that you are
  93.         using Visual Compare and continue to use Visual Compare after a
  94.         reasonable trial period, you must make a registration payment of $49
  95.         to Whitney Software, Inc.  The $49 registration fee will license one
  96.         copy for use on any one computer at any one time.  You must treat
  97.         this software just like a book.  An example is that this software may
  98.         be used by any number of people and may be freely moved from one
  99.         computer location to another, so long as there is no possibility of
  100.         it being used at one location while it's being used at another.  Just
  101.         as a book cannot be read by two different people at the same time.
  102.  
  103.  
  104.         Commercial users of Visual Compare must register and pay for their
  105.         copies of Visual Compare within 30 days of first use or their license
  106.         is withdrawn.  See the file LICENSE.DOC for a site-license agreement.
  107.  
  108.         Anyone distributing Visual Compare for any kind of remuneration must
  109.         first contact Whitney Software, Inc. for authorization.
  110.  
  111.         You are encouraged to pass a copy of Visual Compare along to your
  112.         friends for evaluation.  Please encourage them to register their copy
  113.         if they find that they can use it.  All registered users will receive
  114.         a copy of the latest version of Visual Compare.
  115.  
  116.  
  117.         Technical Support
  118.  
  119.         If you have any questions or comments regarding Visual Compare,
  120.         please send them to CompuServe ID 70661,3463 or:
  121.  
  122.         Whitney Software, Inc.
  123.         P.O. Box 4999
  124.         Walnut Creek, CA 94596 USA
  125.  
  126.  
  127.         Table of Contents
  128.         _____________________________________________________________________
  129.  
  130.  
  131.         Introduction ...................................................... 1
  132.  
  133.         Starting Visual Compare ........................................... 2
  134.  
  135.         Visual Mode ...................................................... 12
  136.  
  137.         Miscellaneous Notes .............................................. 13
  138.  
  139.  
  140.         Introduction                                                        1
  141.         _____________________________________________________________________
  142.  
  143.  
  144.         This manual describes how to use the Visual Compare program to
  145.         compare two program source files.  This manual and the Visual Compare
  146.         program were written for programmers.
  147.  
  148.         Using Visual Compare's visual mode you can easily see the differences
  149.         between two program source files and you can also selectively discard
  150.         differences in order to quickly undo some of the changes that were
  151.         made.
  152.  
  153.         Visual Compare requires an IBM Personal Computer or 100% compatible
  154.         running DOS version 2.1 or later or OS/2 version 1.1 or later.
  155.  
  156.         Visual Compare uses a compare algorithm that has been mathematically
  157.         proven to always produce a shortest possible sequence of insertions
  158.         and deletions that will convert file one to file two.
  159.  
  160.  
  161.         Starting Visual Compare                                             2
  162.         _____________________________________________________________________
  163.  
  164.  
  165.         There are two ways to control the start of Visual Compare:
  166.  
  167.         1. Through arguments specified on the Visual Compare command line.
  168.  
  169.         2. Through commands specified in the Visual Compare initialization
  170.            file.
  171.  
  172.  
  173.         Visual Compare Command Line
  174.  
  175.         Run Visual Compare with no arguments to see a list of the available
  176.         command line arguments.
  177.  
  178.         The form of the Visual Compare command line is as follows:
  179.  
  180.              VCOMP fileone filetwo [options]
  181.  
  182.  
  183.         VCOMP
  184.  
  185.         The name of the program module for the DOS version.  VCOMPP is the
  186.         name of the program module for the OS/2 version.
  187.  
  188.  
  189.         fileone
  190.  
  191.         The first of two files you wish to compare.
  192.  
  193.  
  194.         filetwo
  195.  
  196.         The second of two files you wish to compare.
  197.  
  198.  
  199.         If fileone or filetwo ends with a backslash (\) symbol, the filename
  200.         (file name and optional extension) from the other fileone or filetwo
  201.         command line argument is appended.  This can be convenient if file
  202.         one and file two are in different subdirectories and have the same
  203.         filename.  For example:
  204.  
  205.              VCOMP \OLD\ \NEW\SUPER.C
  206.  
  207.         is equivalent to
  208.  
  209.              VCOMP \OLD\SUPER.C \NEW\SUPER.C
  210.  
  211.  
  212.         Starting Visual Compare                                             3
  213.         _____________________________________________________________________
  214.  
  215.  
  216.         options
  217.  
  218.         The following options may be specified with a leading / or -,
  219.         whichever you prefer:
  220.  
  221.         /B
  222.  
  223.         Same as the BLACKANDWHITE initialization file command.
  224.  
  225.         Use /B to tell Visual Compare that you have a monochrome display
  226.         attached to your computer.
  227.  
  228.         Visual Compare can usually determine whether you have a color or
  229.         monochrome display.  If you have a color display, Visual Compare
  230.         takes advantage of this and uses colors on the screen.
  231.  
  232.         However, if you have a CGA (Color Graphics Adapter), Visual Compare
  233.         can't tell whether you have a monochrome or color display.  Since
  234.         Visual Compare will assume you have a color display, you may wish to
  235.         use /B to tell Visual Compare otherwise.
  236.  
  237.  
  238.         /Tn
  239.  
  240.         2-64
  241.         Default value: 8
  242.  
  243.         Same as the TABWIDTH initialization file command.
  244.  
  245.         Specifies the tab width to be used when expanding tabs or compressing
  246.         spaces.
  247.  
  248.  
  249.         /25
  250.  
  251.         Displays 25 lines in visual mode.
  252.  
  253.  
  254.         /43
  255.  
  256.         Displays 43 lines in visual mode if you have an EGA (Enhanced
  257.         Graphics Adapter).
  258.  
  259.  
  260.         /50
  261.  
  262.         Displays 50 lines in visual mode if you have a VGA (Video Graphics
  263.         Array).
  264.  
  265.  
  266.         Starting Visual Compare                                             4
  267.         _____________________________________________________________________
  268.  
  269.  
  270.         /S[-]
  271.  
  272.         Writes an edit script to standard output that will consist of a
  273.         shortest possible sequence of insertions and deletions that will
  274.         convert file one to file two.
  275.  
  276.         Specify /S- to write the edit script in reverse order (from the end
  277.         of file to the beginning of file).  This can be useful if you are
  278.         using an editor to convert file one to file two using the edit
  279.         script, since modifying the end of file one will not effect the line
  280.         numbers in the edit script that refer to earlier lines in file one.
  281.  
  282.  
  283.         /C
  284.  
  285.         Writes a composite file to standard output that is the same as the
  286.         composite file displayed in visual mode except that strings are used
  287.         to delimit text unique to file one or file two instead of colors.
  288.  
  289.         Use the ONESTART, ONEEND, TWOSTART, and TWOEND initialization file
  290.         commands to specify the strings used to delimit text unique to file
  291.         one or file two.  By default, ONESTART equals "$$$$$  fileone START
  292.         $$$$$", ONEEND equals "$$$$$  fileone END  $$$$$", TWOSTART equals
  293.         "$$$$$  filetwo START  $$$$$", and TWOEND equals "$$$$$  filetwo END
  294.         $$$$$."  Where "fileone" and "filetwo" represent the fileone and
  295.         filetwo command line arguments.
  296.  
  297.         One reason you might use this option is to run Visual Compare from
  298.         within your editor in order to display output similar to that
  299.         displayed in visual mode, in an editor window while you edit file two
  300.         or file one in another editor window.
  301.  
  302.  
  303.         /D
  304.  
  305.         Writes a file to standard output that consists of information about
  306.         each difference.  The information consists of the corresponding file
  307.         positions for file one and file two, whether the difference is an
  308.         insertion or deletion, and the number of lines inserted or deleted.
  309.  
  310.         You might use this option to interface a program of your own design
  311.         to Visual Compare.
  312.  
  313.  
  314.         Starting Visual Compare                                             5
  315.         _____________________________________________________________________
  316.  
  317.  
  318.         /En
  319.  
  320.         0-32736
  321.         Default value: 32736
  322.  
  323.         The edit distance is defined as the length of a shortest possible
  324.         sequence of insertions and deletions that will convert file one to
  325.         file two.
  326.  
  327.         Use /En to set the maximum edit distance.  If you specify a value
  328.         greater than 32736, Visual Compare will use 32736.  If while
  329.         comparing files the maximum edit distance is exceeded, Visual Compare
  330.         will display an appropriate message and abort.
  331.  
  332.         Use this option if you are comparing files that may be too different
  333.         for the comparison to be useful and you don't want to wait for Visual
  334.         Compare to complete the comparison if the comparison won't be useful.
  335.  
  336.  
  337.         /I
  338.  
  339.         Same as the IGNORE initialization file command.
  340.  
  341.         Ignores leading space and tab characters when comparing lines.  Use
  342.         /I if you are not interested in changes in the indentation of lines.
  343.  
  344.  
  345.         Visual Compare Initialization File
  346.  
  347.         Visual Compare automatically processes an initialization file called
  348.         VCOMP.INI at the start of execution.
  349.  
  350.         Visual Compare first looks for VCOMP.INI in the current working
  351.         directory.  If it doesn't find VCOMP.INI, it next looks in the
  352.         directories specified by the PATH environment variable.
  353.  
  354.         The initialization file commands can be abbreviated.  For example,
  355.         the TABSOUT command can be entered as TABS, TABSO, TABSOU, or
  356.         TABSOUT.  The shortest legal abbreviation for a command is indicated
  357.         by showing that portion of the command in uppercase and the rest of
  358.         the command in lowercase.
  359.  
  360.         Some of the initialization file commands have command line option
  361.         counterparts.  If both the initialization file command and the
  362.         corresponding command line option are specified, the command line
  363.         option will override.
  364.  
  365.  
  366.         Starting Visual Compare                                             6
  367.         _____________________________________________________________________
  368.  
  369.  
  370.         The available initialization file commands are as follows:
  371.  
  372.         Attributes
  373.  
  374.         Use ATTRIBUTES to control the colors Visual Compare uses on the
  375.         screen.
  376.  
  377.         An attribute value is associated with each type of field that Visual
  378.         Compare displays.  The following table lists the seven different
  379.         field types displayed by Visual Compare.  Use ATTRIBUTES to specify
  380.         an attribute value for each field type, in the order of the table
  381.         below.
  382.  
  383.         Field                Description
  384.         ----------------------------------------------------------
  385.         Common               lines common to file one and file two
  386.         Delete               lines deleted from file one
  387.         Insert               lines inserted from file two
  388.         Function             function key and file name lines
  389.         Window               help and prompt windows
  390.         Error                error message windows
  391.         Key                  keys in help and prompt windows
  392.  
  393.         Attribute values are numbers ranging from 0 to 255.  Different
  394.         attribute values cause text to appear in different colors,
  395.         highlighted, blinking, etc.  On most display adapters that handle
  396.         color, you can use the following table to determine the attribute
  397.         value corresponding to a given color.  Add the number corresponding
  398.         to the desired foreground color to the number corresponding to the
  399.         desired background color.  To also get blinking, add 128.
  400.  
  401.         Foreground           Background
  402.         -------------------------------
  403.         0 black              0 black
  404.         1 blue               16 blue
  405.         2 green              32 green
  406.         3 cyan               48 cyan
  407.         4 red                64 red
  408.         5 magenta            80 magenta
  409.         6 brown              96 brown
  410.         7 white              112 white
  411.         8 gray
  412.         9 light blue
  413.         10 light green
  414.         11 light cyan
  415.         12 light red
  416.         13 light magenta
  417.         14 yellow
  418.         15 bright white
  419.  
  420.  
  421.         Starting Visual Compare                                             7
  422.         _____________________________________________________________________
  423.  
  424.  
  425.         On a MDA (Monochrome Display Adapter), the available attribute values
  426.         are 7 for normal text, 15 for highlighted text, 65 for underlined
  427.         text, and 112 for reverse video text.  To also get blinking, add 128
  428.         to any of these values.
  429.  
  430.         Examples:
  431.  
  432.              ATTRIBUTES 27 28 26 30 63 79 15
  433.  
  434.         The default attribute values used by Visual Compare on a CGA (Color
  435.         Graphics Adapter), an EGA (Enhanced Graphics Adapter), or a VGA
  436.         (Video Graphics Array).
  437.  
  438.              ATTRIBUTES 7 112 15 7 112 112 15
  439.  
  440.         The default attribute values used by Visual Compare on a MDA
  441.         (Monochrome Display Adapter).
  442.  
  443.  
  444.         Blackandwhite
  445.  
  446.         Same as the /B command line option.
  447.  
  448.         Use BLACKANDWHITE to tell Visual Compare that you have a monochrome
  449.         display attached to your computer.
  450.  
  451.         Visual Compare can usually determine whether you have a color or
  452.         monochrome display.  If you have a color display, Visual Compare
  453.         takes advantage of this and uses colors on the screen.
  454.  
  455.         However, if you have a CGA (Color Graphics Adapter), Visual Compare
  456.         can't tell whether you have a monochrome or color display.  Since
  457.         Visual Compare will assume you have a color display, you may wish to
  458.         use BLACKANDWHITE to tell Visual Compare otherwise.
  459.  
  460.  
  461.         Starting Visual Compare                                             8
  462.         _____________________________________________________________________
  463.  
  464.  
  465.         Expanded
  466.  
  467.         YES or NO
  468.  
  469.         Visual Compare keeps the contents of the files you are comparing in
  470.         memory.  The DOS version of Visual Compare can use up to four
  471.         megabytes of DOS and EMS memory (Lotus-Intel-Microsoft Expanded
  472.         Memory Specification, version 3.0 or later) to store your files.  If
  473.         Visual Compare detects that EMS memory is present in your system, it
  474.         will automatically use it.
  475.  
  476.         The EXPANDED command is ignored by the OS/2 version of Visual
  477.         Compare.
  478.  
  479.         Use EXPANDED NO to tell Visual Compare to ignore any EMS memory in
  480.         your system, and to use only DOS memory.  You may need to use
  481.         EXPANDED NO if your EMS driver is not compatible with Visual Compare.
  482.         You may also want to use EXPANDED NO for performance reasons.
  483.  
  484.  
  485.         Height
  486.  
  487.         25, 43, or 50
  488.  
  489.         Use HEIGHT to tell Visual Compare how many lines to display in visual
  490.         mode.  You must have either an EGA (Enhanced Graphics Adapter) or a
  491.         VGA (Video Graphics Array) for this command to have any effect.
  492.  
  493.  
  494.         Ignore
  495.  
  496.         Same as the /I command line option.
  497.  
  498.         If you are not interested in changes in the indentation of lines, use
  499.         IGNORE to tell Visual Compare to ignore leading space and tab
  500.         characters when comparing lines.
  501.  
  502.  
  503.         SHadow
  504.  
  505.         YES or NO
  506.  
  507.         Use SHADOW to tell Visual Compare whether or not windows should have
  508.         shadows.
  509.  
  510.  
  511.         Starting Visual Compare                                             9
  512.         _____________________________________________________________________
  513.  
  514.  
  515.         SNowcontrol
  516.  
  517.         YES or NO
  518.  
  519.         The IBM Color Graphics Adapter (CGA) requires special programming to
  520.         prevent "snow" from appearing on the screen when a program changes
  521.         the contents of the screen.  The special programming slows down
  522.         screen updating and is not necessary for most other display adapters.
  523.         If Visual Compare detects a MDA (Monochrome Display Adapter), an EGA
  524.         (Enhanced Graphics Adapter), or a VGA (Video Graphics Array), it does
  525.         not "desnow."  If Visual Compare detects a CGA, it will try to
  526.         determine whether "desnowing" is necessary.
  527.  
  528.         The SNOWCONTROL command is ignored by the OS/2 version of Visual
  529.         Compare because OS/2 automatically performs "desnowing" if necessary.
  530.  
  531.         If you suspect that Visual Compare is "desnowing" when it is not
  532.         necessary, you may want to use SNOWCONTROL NO which will allow Visual
  533.         Compare to run faster.
  534.  
  535.         If your computer "locks up" when you run Visual Compare, use
  536.         SNOWCONTROL NO.
  537.  
  538.         If Visual Compare incorrectly determines that your CGA does not
  539.         require "desnowing", you can force Visual Compare to "desnow" by
  540.         using SNOWCONTROL YES.
  541.  
  542.  
  543.         TABSout
  544.  
  545.         Use TABSOUT to tell Visual Compare to compress spaces in the
  546.         composite file to tab characters (using the default tab width of 8 or
  547.         the tab width specified by the TABWIDTH initialization file command
  548.         or the /Tn command line option) before writing the composite file to
  549.         disk.  Spaces appearing after the first single or double quote on a
  550.         line are not compressed and single spaces are not changed to tab
  551.         characters.
  552.  
  553.         TABSOUT effects the composite file written to disk by the visual mode
  554.         F2 write function and has no effect on the composite file written to
  555.         standard output by the /C command line option.
  556.  
  557.  
  558.         Starting Visual Compare                                            10
  559.         _____________________________________________________________________
  560.  
  561.  
  562.         TABWidth
  563.  
  564.         2-64
  565.         Default value: 8
  566.  
  567.         Same as the /Tn command line option.
  568.  
  569.         Specifies the tab width to be used when expanding tabs or compressing
  570.         spaces.
  571.  
  572.  
  573.         ONEStart
  574.  
  575.         "string" or 'string'
  576.         Default value: "$$$$$  fileone START  $$$$$"
  577.  
  578.         If the /C command line option is specified, ONESTART specifies the
  579.         string to be written to standard output at the start of text that is
  580.         unique to file one.  The "fileone" in the default value represents
  581.         the fileone command line argument.
  582.  
  583.  
  584.         ONEEnd
  585.  
  586.         "string" or 'string'
  587.         Default value: "$$$$$  fileone END  $$$$$"
  588.  
  589.         If the /C command line option is specified, ONEEND specifies the
  590.         string to be written to standard output at the end of text that is
  591.         unique to file one.  The "fileone" in the default value represents
  592.         the fileone command line argument.
  593.  
  594.  
  595.         TWOStart
  596.  
  597.         "string" or 'string'
  598.         Default value: "$$$$$  filetwo START  $$$$$"
  599.  
  600.         If the /C command line option is specified, TWOSTART specifies the
  601.         string to be written to standard output at the start of text that is
  602.         unique to file two.  The "filetwo" in the default value represents
  603.         the filetwo command line argument.
  604.  
  605.  
  606.         Starting Visual Compare                                            11
  607.         _____________________________________________________________________
  608.  
  609.  
  610.         TWOEnd
  611.  
  612.         "string" or 'string'
  613.         Default value: "$$$$$  filetwo END  $$$$$"
  614.  
  615.         If the /C command line option is specified, TWOEND specifies the
  616.         string to be written to standard output at the end of text that is
  617.         unique to file two.  The "filetwo" in the default value represents
  618.         the filetwo command line argument.
  619.  
  620.  
  621.         Working
  622.  
  623.         YES or NO
  624.  
  625.         Use WORKING to tell Visual Compare whether or not to display the
  626.         "Working" message.
  627.  
  628.  
  629.         Here is an example initialization file:
  630.  
  631.              SN NO
  632.              TABW 4
  633.              ONES "!!!!!  ONE START  !!!!!"
  634.              ONEE "!!!!!  ONE END  !!!!!"
  635.              TWOS '!!!!!  TWO START  !!!!!'
  636.              TWOE '!!!!!  TWO END  !!!!!'
  637.  
  638.         Don't "desnow", use a tab width of 4, and if the /C command line
  639.         option is specified, use the given strings to delimit text unique to
  640.         file one or file two.
  641.  
  642.  
  643.         Visual Mode                                                        12
  644.         _____________________________________________________________________
  645.  
  646.  
  647.         Visual Compare can be run in batch mode by using the /C or /S command
  648.         line option.  However, most of the time you will probably run Visual
  649.         Compare in visual mode.  In visual mode you can easily see the
  650.         differences between two program source files and you can also
  651.         selectively discard differences in order to quickly undo some of the
  652.         changes that were made.
  653.  
  654.         If the /C or /S command line option is not given, Visual Compare will
  655.         enter visual mode.  In visual mode you will be presented with a
  656.         scrollable display of a composite of file one and file two.  The
  657.         composite file consists of lines that are common to file one and file
  658.         two, lines unique to file one (deleted from file one), and lines
  659.         unique to file two (inserted from file two).  Invoke the F1 help
  660.         function to see a list of the available functions and their keys.
  661.  
  662.         To selectively discard differences, use the F7 remove one function,
  663.         the F8 remove two function, the Del key, and the Shift-Del key to
  664.         remove insertions and deletions from the composite file.  Then invoke
  665.         the F2 write function to write the modified composite file to disk.
  666.         All lines in the composite file except those that have been removed
  667.         will be written to disk.  When you invoke the F2 write function, you
  668.         will be prompted for a composite file name.
  669.  
  670.         Use the F5 show/hide function to display insertions and deletions
  671.         that have been removed.  Use the F4 number function to mark the
  672.         removed insertions and deletions.  Use the Ins and Shift-Ins keys to
  673.         unremove insertions and deletions.  To use the Ins or Shift-Ins key
  674.         to unremove an insertion or deletion, you must first position the
  675.         cursor on the removed insertion or deletion (the removed insertion or
  676.         deletion must be displayed with the F5 show/hide function).
  677.  
  678.         If there are lines that are too long to be completely displayed, use
  679.         the right and left arrow keys, the End key, and the Home key to
  680.         horizontally scroll the display.  The End key will scroll the display
  681.         so that the last character of the longest displayed line is visible.
  682.  
  683.  
  684.         Miscellaneous Notes                                                13
  685.         _____________________________________________________________________
  686.  
  687.  
  688.         Lines in file one and file two can be delimited with Cr, Lf, or
  689.         Cr-Lf.  The maximum allowed line length in file one and file two is
  690.         255 characters.  The maximum number of lines that file one and file
  691.         two each can contain is 16368.  The maximum number of lines that the
  692.         composite file can contain is 16368.
  693.  
  694.         Visual Compare will normally terminate with a return code of 0.
  695.         However, if Visual Compare determines that file one and file two are
  696.         identical, it will display an appropriate message and terminate with
  697.         a return code of 1.  Also, if Visual Compare encounters an error
  698.         condition while not in visual mode, it will display an appropriate
  699.         message and terminate with a return code of 2.
  700.