Visual Compare Version 1.54 A file comparison utility for programmers. Copyright Notice Copyright (C) John R. Whitney 1991, 1992, 1993 All rights reserved. Trademarks CompuServe is a registered trademark of CompuServe, Inc. IBM is a registered trademark of International Business Machines Corporation. Lotus is a registered trademark of Lotus Development Corporation. Intel is a registered trademark of Intel Corporation. Microsoft is a registered trademark of Microsoft Corporation. Agreement Visual Compare is provided at no charge. Visual Compare is copyrighted, but you may make copies for others as long as no fee is charged for the software, Visual Compare is not altered, and Visual Compare is not distributed as part of another system. Non-profit and for-profit organizations may charge a distribution fee for distributing Visual Compare of not more than $10. In no event shall the author of Visual Compare be liable for any damages whatsoever arising out of the use of or inability to use this free software. Table of Contents _____________________________________________________________________ Introduction ...................................................... 1 Starting Visual Compare ........................................... 2 Visual Mode ...................................................... 14 Miscellaneous Notes .............................................. 15 New Features ..................................................... 16 Introduction 1 _____________________________________________________________________ This manual describes how to use the Visual Compare program to compare two program source files. This manual and the Visual Compare program were written for programmers. Using Visual Compare's visual mode you can easily see the differences between two program source files and you can also selectively discard differences in order to quickly undo some of the changes that were made. Visual Compare requires an IBM Personal Computer, or 100 percent compatible, running DOS version 2.1 or later. Visual Compare uses a comparison algorithm that has been mathematically proven to always produce a shortest possible sequence of insertions and deletions that will convert file one to file two. Starting Visual Compare 2 _____________________________________________________________________ There are two ways to control the start of Visual Compare: 1. Through arguments specified on the Visual Compare command line. 2. Through commands specified in the Visual Compare initialization file. Visual Compare Command Line Run Visual Compare with no arguments to see a list of the available command line arguments or to have Visual Compare prompt for arguments. The form of the Visual Compare command line is as follows: VCOMP fileone filetwo [options] VCOMP The name of the program module. fileone The first of two files you wish to compare. filetwo The second of two files you wish to compare. If fileone or filetwo specifies a directory or a drive, the filename (file name and optional extension) from the other fileone or filetwo command line argument is appended. This can be convenient if file one and file two are in different directories and have the same filename. For example: VCOMP \OLD \NEW\SUPER.C is equivalent to VCOMP \OLD\SUPER.C \NEW\SUPER.C Starting Visual Compare 3 _____________________________________________________________________ If fileone or filetwo has a file name consisting of an asterisk (*) symbol, the file name from the other fileone or filetwo command line argument is substituted. For example: VCOMP *.BAK SUPER.C is equivalent to VCOMP SUPER.BAK SUPER.C options The following options may be specified with a leading / or -, whichever you prefer: /B Same as the BLACKANDWHITE initialization file command. Use /B to tell Visual Compare that you have a monochrome display attached to your computer. Visual Compare can usually determine whether you have a color or monochrome display. If you have a color display, Visual Compare takes advantage of this and uses colors on the screen. However, if you have a CGA (Color Graphics Adapter), Visual Compare can't tell whether you have a monochrome or color display. Since Visual Compare will assume you have a color display, you may wish to use /B to tell Visual Compare otherwise. /Tn 2-64 Default value: 8 Same as the TABWIDTH initialization file command. Specifies the tab width to be used when expanding tabs, compressing spaces, or shifting the display right and left with the Tab and Shift-Tab keys. /25 Displays 25 lines in visual mode if you have either an EGA (Enhanced Graphics Adapter) or a VGA (Video Graphics Array). Starting Visual Compare 4 _____________________________________________________________________ /43 Displays 43 lines in visual mode if you have an EGA (Enhanced Graphics Adapter). /50 Displays 50 lines in visual mode if you have a VGA (Video Graphics Array). /S[-] Writes an edit script to standard output that will consist of a shortest possible sequence of insertions and deletions that will convert file one to file two. Specify /S- to write the edit script in reverse order (from the end of file to the beginning of file). This can be useful if you are using an editor to convert file one to file two using the edit script, since modifying the end of file one will not effect the line numbers in the edit script that refer to earlier lines in file one. /C Writes a composite file to standard output that is the same as the composite file displayed in visual mode except that strings are used to delimit text unique to file one or file two instead of colors. Use the ONESTART, ONEEND, TWOSTART, and TWOEND initialization file commands to specify the strings used to delimit text unique to file one or file two. By default, ONESTART equals "$$$$$ fileone START $$$$$", ONEEND equals "$$$$$ fileone END $$$$$", TWOSTART equals "$$$$$ filetwo START $$$$$", and TWOEND equals "$$$$$ filetwo END $$$$$." Where "fileone" and "filetwo" represent the fileone and filetwo command line arguments. One reason you might use this option is to run Visual Compare from within your editor in order to display output similar to that displayed in visual mode, in an editor window while you edit file two or file one in another editor window. Starting Visual Compare 5 _____________________________________________________________________ /D Writes a file to standard output that consists of information about each difference. The information consists of the corresponding file positions for file one and file two, whether the difference is an insertion or deletion, and the number of lines inserted or deleted. You might use this option to interface a program of your own design to Visual Compare. /En 0-32736 Default value: 32736 The edit distance is defined as the length of a shortest possible sequence of insertions and deletions that will convert file one to file two. Use /En to set the maximum edit distance. If you specify a value greater than 32736, Visual Compare will use 32736. If while comparing files the maximum edit distance is exceeded, Visual Compare will display an appropriate message and abort. Use this option if you are comparing files that may be too different for the comparison to be useful and you don't want to wait for Visual Compare to complete the comparison if the comparison won't be useful. /I Same as the IGNORE initialization file command. Ignores leading space and tab characters when comparing lines. Use /I if you are not interested in changes in the indentation of lines. /K Same as the CASE initialization file command. Considers upper-case and lower-case letters equivalent when comparing lines. Starting Visual Compare 6 _____________________________________________________________________ /Z Visual Compare was designed to perform a line-oriented comparison on two program source files. It is possible for Visual Compare to compare two files that are not the same at the byte level and report that they are identical. This can happen for six reasons. First, the lines in the files are not all delimited in the same manner. For example, lines in one file are delimited by Cr and lines in the other file by Cr-Lf. Second, end-of-file characters (Ctrl-Z) can cause this to happen, because end-of-file characters are normally discarded and files are not normally read past the first end-of-file character. Third, tab characters can cause this to happen, because tab characters are normally expanded to spaces before the comparison takes place. Fourth, trailing space and tab characters at the end of lines can cause this to happen, because, by default, trailing space and tab characters at the end of lines are discarded before the comparison takes place. (To change the default, see the TRAILING initialization file command.) Fifth, the /I command line option or the IGNORE initialization file command can cause this to happen, because they tell Visual Compare to ignore leading space and tab characters when comparing lines. Sixth, the /K command line option or the CASE initialization file command can cause this to happen, because they tell Visual Compare to consider upper-case and lower-case letters equivalent when comparing lines. Use /Z to determine if two files are identical at the byte level. This option tells Visual Compare to not discard line delimiters, to not discard end-of-file characters and to read any characters past end-of-file characters, to not expand tab characters, to not discard trailing space and tab characters at the end of lines, to ignore the /I command line option or the IGNORE initialization file command, and to ignore the /K command line option or the CASE initialization file command. Visual Compare will still perform a line-oriented comparison. Visual Compare will also ignore the /C, /S, and /D command line options and will enter visual mode if the files are not identical. Visual Compare Initialization File Visual Compare automatically processes an initialization file called VCOMP.INI at the start of execution. Visual Compare first looks for VCOMP.INI in the current working directory. If it doesn't find VCOMP.INI, it next looks in the directories specified by the PATH environment variable. Starting Visual Compare 7 _____________________________________________________________________ The initialization file commands can be abbreviated. For example, the TABSOUT command can be entered as TABS, TABSO, TABSOU, or TABSOUT. The shortest legal abbreviation for a command is indicated by showing that portion of the command in uppercase and the rest of the command in lowercase. Some of the initialization file commands have command line option counterparts. If both the initialization file command and the corresponding command line option are specified, the command line option will override. The available initialization file commands are as follows: Attributes Use ATTRIBUTES to control the colors Visual Compare uses on the screen. An attribute value is associated with each type of field that Visual Compare displays. The following table lists the seven different field types displayed by Visual Compare. Use ATTRIBUTES to specify an attribute value for each field type, in the order of the table below. Field Description ---------------------------------------------------------- Common lines common to file one and file two Delete lines deleted from file one Insert lines inserted from file two Function function key and file name lines Window help and prompt windows Error error message windows Key keys in help and prompt windows Attribute values are numbers ranging from 0 to 255. Different attribute values cause text to appear in different colors, highlighted, blinking, etc. On most display adapters that handle color, you can use the following table to determine the attribute value corresponding to a given color. Add the number corresponding to the desired foreground color to the number corresponding to the desired background color. To also get blinking, add 128. Starting Visual Compare 8 _____________________________________________________________________ Foreground Background ------------------------------- 0 black 0 black 1 blue 16 blue 2 green 32 green 3 cyan 48 cyan 4 red 64 red 5 magenta 80 magenta 6 brown 96 brown 7 white 112 white 8 gray 9 light blue 10 light green 11 light cyan 12 light red 13 light magenta 14 yellow 15 bright white On a MDA (Monochrome Display Adapter), the available attribute values are 7 for normal text, 15 for highlighted text, 65 for underlined text, and 112 for reverse video text. To also get blinking, add 128 to any of these values. Examples: ATTRIBUTES 27 28 26 30 63 79 15 The default attribute values used by Visual Compare on a CGA (Color Graphics Adapter), an EGA (Enhanced Graphics Adapter), or a VGA (Video Graphics Array). ATTRIBUTES 7 112 15 7 112 112 15 The default attribute values used by Visual Compare on a MDA (Monochrome Display Adapter). Starting Visual Compare 9 _____________________________________________________________________ Blackandwhite Same as the /B command line option. Use BLACKANDWHITE to tell Visual Compare that you have a monochrome display attached to your computer. Visual Compare can usually determine whether you have a color or monochrome display. If you have a color display, Visual Compare takes advantage of this and uses colors on the screen. However, if you have a CGA (Color Graphics Adapter), Visual Compare can't tell whether you have a monochrome or color display. Since Visual Compare will assume you have a color display, you may wish to use BLACKANDWHITE to tell Visual Compare otherwise. Case Same as the /K command line option. Use CASE to tell Visual Compare to consider upper-case and lower-case letters equivalent when comparing lines. ENdofline CRLF, CR, or LF Default value: CRLF Use ENDOFLINE to tell Visual Compare the line delimiter to use when the composite file is written to disk by the F2 write function. If Visual Compare is started with the /Z command line option, it will not discard the line delimiters in file one and file two and will write them to the composite file, instead of using the line delimiter specified by ENDOFLINE. Starting Visual Compare 10 _____________________________________________________________________ EXPanded YES or NO Visual Compare keeps the contents of the files you are comparing in memory. Visual Compare can use up to four megabytes of DOS and EMS (Lotus-Intel-Microsoft Expanded Memory Specification, version 3.0 or later) memory or DOS and XMS (eXtended Memory Specification) memory to store your files. If Visual Compare detects that EMS memory is present in your system, it will automatically use it. If EMS memory is not detected and XMS memory is detected, Visual Compare will automatically use XMS memory. Use EXPANDED NO to tell Visual Compare to ignore any EMS memory in your system, and to use only DOS and possibly XMS memory. You may need to use EXPANDED NO if your EMS driver is not compatible with Visual Compare. You may also want to use EXPANDED NO for performance reasons. EXTended YES or NO Visual Compare keeps the contents of the files you are comparing in memory. Visual Compare can use up to four megabytes of DOS and EMS (Lotus-Intel-Microsoft Expanded Memory Specification, version 3.0 or later) memory or DOS and XMS (eXtended Memory Specification) memory to store your files. If Visual Compare detects that EMS memory is present in your system, it will automatically use it. If EMS memory is not detected and XMS memory is detected, Visual Compare will automatically use XMS memory. Use EXTENDED NO to tell Visual Compare to ignore any XMS memory in your system, and to use only DOS and possibly EMS memory. You may need to use EXTENDED NO if your XMS driver is not compatible with Visual Compare. You may also want to use EXTENDED NO for performance reasons. Height 25, 43, or 50 Use HEIGHT to tell Visual Compare how many lines to display in visual mode. You must have either an EGA (Enhanced Graphics Adapter) or a VGA (Video Graphics Array) for this command to have any effect. Starting Visual Compare 11 _____________________________________________________________________ Ignore Same as the /I command line option. If you are not interested in changes in the indentation of lines, use IGNORE to tell Visual Compare to ignore leading space and tab characters when comparing lines. SHadow YES or NO Use SHADOW to tell Visual Compare whether or not windows should have shadows. SNowcontrol YES or NO The IBM Color Graphics Adapter (CGA) requires special programming to prevent "snow" from appearing on the screen when a program changes the contents of the screen. The special programming slows down screen updating and is not necessary for most other display adapters. If Visual Compare detects a MDA (Monochrome Display Adapter), an EGA (Enhanced Graphics Adapter), or a VGA (Video Graphics Array), it does not "desnow." If Visual Compare detects a CGA, it will try to determine whether "desnowing" is necessary. If you suspect that Visual Compare is "desnowing" when it is not necessary, you may want to use SNOWCONTROL NO which will allow Visual Compare to run faster. If your computer "locks up" when you run Visual Compare, use SNOWCONTROL NO. If Visual Compare incorrectly determines that your CGA does not require "desnowing", you can force Visual Compare to "desnow" by using SNOWCONTROL YES. Starting Visual Compare 12 _____________________________________________________________________ TABSout Use TABSOUT to tell Visual Compare to compress spaces in the composite file to tab characters (using the default tab width of 8 or the tab width specified by the TABWIDTH initialization file command or the /Tn command line option) before writing the composite file to disk. Spaces appearing after the first single or double quote on a line are not compressed and single spaces are not changed to tab characters. TABSOUT effects the composite file written to disk by the visual mode F2 write function and has no effect on the composite file written to standard output by the /C command line option. TABWidth 2-64 Default value: 8 Same as the /Tn command line option. Specifies the tab width to be used when expanding tabs, compressing spaces, or shifting the display right and left with the Tab and Shift-Tab keys. TRailing YES or NO Default value: YES Use TRAILING to tell Visual Compare whether or not trailing space and tab characters at the end of lines should be discarded. ONEStart "string" or 'string' Default value: "$$$$$ fileone START $$$$$" If the /C command line option is specified, ONESTART specifies the string to be written to standard output at the start of text that is unique to file one. The "fileone" in the default value represents the fileone command line argument. Starting Visual Compare 13 _____________________________________________________________________ ONEEnd "string" or 'string' Default value: "$$$$$ fileone END $$$$$" If the /C command line option is specified, ONEEND specifies the string to be written to standard output at the end of text that is unique to file one. The "fileone" in the default value represents the fileone command line argument. TWOStart "string" or 'string' Default value: "$$$$$ filetwo START $$$$$" If the /C command line option is specified, TWOSTART specifies the string to be written to standard output at the start of text that is unique to file two. The "filetwo" in the default value represents the filetwo command line argument. TWOEnd "string" or 'string' Default value: "$$$$$ filetwo END $$$$$" If the /C command line option is specified, TWOEND specifies the string to be written to standard output at the end of text that is unique to file two. The "filetwo" in the default value represents the filetwo command line argument. Working YES or NO Use WORKING to tell Visual Compare whether or not to display the "Working" message. Here is an example initialization file: CASE EXP NO TABW 4 Consider upper-case and lower-case letters equivalent when comparing lines, ignore any EMS memory in your system, and use a tab width of 4. Visual Mode 14 _____________________________________________________________________ Visual Compare can be run in batch mode by using the /C, /S, or /D command line option. However, most of the time you will probably run Visual Compare in visual mode. In visual mode you can easily see the differences between two program source files and you can also selectively discard differences in order to quickly undo some of the changes that were made. If the /C, /S, or /D command line option is not given, Visual Compare will enter visual mode. In visual mode you will be presented with a scrollable display of a composite of file one and file two. The composite file consists of lines that are common to file one and file two, lines unique to file one (deleted from file one), and lines unique to file two (inserted from file two). Invoke the F1 help function to see a list of the available functions and their keys. To selectively discard differences, use the F7 remove one function, the F8 remove two function, the Del key, and the Minus key to remove insertions and deletions from the composite file. Then invoke the F2 write function to write the modified composite file to disk. All lines in the composite file except those that have been removed will be written to disk. When you invoke the F2 write function, you will be prompted for a composite file name. Use the F5 show/hide function to display insertions and deletions that have been removed. Use the F4 number function to mark the removed insertions and deletions. Use the Shift-F7 key, the Shift-F8 key, the Ins key, and the Plus key to unremove insertions and deletions. To use the Ins or Plus key to unremove an insertion or deletion, you must first position the cursor on the removed insertion or deletion (the removed insertion or deletion must be displayed with the F5 show/hide function). If there are lines that are too long to be completely displayed, use the right and left arrow keys, the End key, and the Home key to horizontally scroll the display. The End key will scroll the display so that the last character of the longest displayed line is visible. Miscellaneous Notes 15 _____________________________________________________________________ Lines in file one and file two can be delimited with Cr, Lf, or Cr-Lf. The maximum allowed line length in file one and file two is 2048 characters. The maximum number of lines that file one and file two each can contain is 16368. The maximum number of lines that the composite file can contain is 16368. Visual Compare will normally terminate with a return code of 1. However, if Visual Compare determines that file one and file two are identical, it will display an appropriate message and terminate with a return code of 0. Also, if Visual Compare encounters an error condition while not in visual mode, it will display an appropriate message and terminate with a return code of 2. Visual Compare uses a comparison algorithm that is described by Eugene W. Myers in "An O(ND) difference algorithm and its variations" (Algorithmica, 1986, pp. 251-266). Visual Compare uses the linear space refinement of the basic algorithm. New Features 16 _____________________________________________________________________ Fixed a bug where Visual Compare was writing to a pointer after it was freed. This was happening when Visual Compare was prompting for arguments, after Visual Compare was started with no command line arguments. The computer would sometimes "lock up" after the Enter key was used to accept the arguments. Removed the requirement to end fileone or filetwo with a backslash (\) symbol, when specifying a directory to be appended with the filename (file name and optional extension) from the other fileone or filetwo command line argument.