PDP-10.its/doc/info/srccom.9

SRCCOM command strings look like <outfile>_<in1>,<in2>
Just <in1>,<in2> outputs to the terminal.  <in2> defaults
to <in1> except that the 2nd filename defaults to ">".

SRCCOM switches are:

/digit	number of consecutive matching lines it takes to tell
	 SRCCOM that the changes have stopped.
/@	Indirect.  Take switches and file name from a previous
	 SRCCOM output file.  Must go with output file or 1st input.
/A	Archive.  Concatenate the differences to the front of the
	 output file instead of overwriting it.
/B	don't ignore Blank lines.
/C	ignore Comments.
/D	Disown self and keep running, logging out when finished.
/E	follow each run of changed lines with the next (unchanged)
	 line, if any.
/F	output a copy of file 2, with changed lines Flagged.
/I	automatic merge mode.
/K	ignore differences in Kase.
/L	try to detect Labels (MIDAS style).
/M	Manual Merge Mode.
/S	ignore differences in Spacing.
/W	say Which file (1 or 2) on each line of changes
/X	eXecute commands from a file.
/Y	try to detect labels, in a general way.
/!	Force comparison even if the two filespecs specify the
	 same file.
/#	Do binary compare of files.
/$	Do binary compare of executable file address space.  This should
	 be the first thing (preceding filenames).

For further details, or for an introductory description,
do :INFO SRCCOM


File: SRCCOM	Node: TOP	Up: (DIR)	Next: Generalities

SRCCOM is a program for comparing or merging similar ascii text files;
for example, two versions of the same program.

You can see the whole documentation file in INFO now by typing
a series of "N"'s.

* Menu:

* Gen: Generalities	Overview of using SRCCOM

* Com: Commands		Details of SRCCOM command lines

* Switch: Switches	Commands contain switches which say what
			sort of comparison and output is wanted

* Smart: Smart		Telling SRCCOM to ignore certain kinds of changes

* Format: Format	Requesting optional info in the output file

* Merge: Merge		Merging two input files (manual or automatic)

* Binary: Binary	Comparing binary file

* Archive: Archive	Keeping an archival record of changes of one
			file, from version to version.

* Xfile: Com Files	Taking commands from a file

* Output: Output	What everything in a SRCCOM output file means.

File: SRCCOM, Node: GENERALITIES, Up: Top, Previous: Top, Next: Commands

What you can do with SRCCOM:

Comparing produces a file listing the places where the two input files
differ, and what text each file has.  There are two methods of merging:
one finds each place where the input files differ, prints out each
file's version, and asks the user to choose between them for the
merge file.  The other produces automatically a file in which each
point of difference has the two alternate versions both present and
identified by which file they came from.  Searching for *** will find
all of them.  It is also made easy to compare two files and append
the differences to the front of a CMPARC file - this is good for
keeping a record of all changes in a program from version to version.

If SRCCOM is given a command via DDT, as in :SRCCOM <command> <cr>,
SRCCOM will execute the one command and then commit suicide,
if there was no error. If SRCCOM is run without a command, as
in SRCCOM^K, it will read commands from the terminal, prompting for
each one with a "*", until a command ending in "^C" is typed, or
SRCCOM is otherwise exited.  A command ending in ^C is executed
normally, but when it is finished SRCCOM will commit suicide.

Whenever SRCCOM reads input from the terminal, <rubout> cancels one
character, and ^U cancels a whole line.

The easiest thing to do with SRCCOM is to compare two files and type the
differences on the terminal.  Just give the command

:SRCCOM <file1>,<file2> <cr>

to do this.

At the bottom of the page on the terminal, SRCCOM will print
"--MORE--" (unless :TCTYP NOMORE or ^_M was used to turn off
this feature).  At that point, the user has these alternatives:
  space   --  causes SRCCOM to continue typing.
  ^C	  --  causes SRCCOM to kill itself.
  rubout  --  causes the rest of the current set of differences
		not to be printed.
  other   --  is like rubout, but remains in the input buffer
		acting as normal input.  It will eventually be
		read by SRCCOM, or some other program.

File: SRCCOM, Node: COMMANDS, Up: Top, Previous: Generalities, Next: Switches

Details of Command Strings:

A command string for SRCCOM should have the format

      <out>_<in1>,<in2>

or

      <out>_<in>

where <out> is the output file spec,
and <in1> and <in2> are the input file specs.
Switches, preceded by slashes, may also be present in between names.
The short form is an abbreviation causing <in2> to be completely
defaulted.

The filename defaults are as follows:
the SNAME default is sticky, starting out as the user's MSNAME.
The FN1 default is also sticky, but at least one FN1 must be
specified in the command line, unless no device needs one,
and the output FN1 will default to the real FN1 of the first input
file, or that of the second in the case that the first is on a
non-directory device.
The device default starts as DSK: for the input files, and is sticky.
For the output file, it is DSK:.
The input fn2's default individually to ">".
The output fn2 defaults to "COMPAR" normally, but in merge
mode the default is ">", and when /A is specified the default
is "CMPARC".  In /F mode, the default is "FLAGGD".

if the output device is to be TTY:, that can be specified
by omitting the output spec and the backarrow ("_"), thus:

      <in1>,<in2>   or   <in>



Command String Examples:

_SYSENG;TECO <		compares SYSENG;TECO < with SYSENG;TECO >,
			and outputs to <MSNAME>;TECO COMPAR.
FOO;UGH CMP_SYSENG;TECO 500,^X501
			compares SYSENG;TECO 500 with SYSENG;TECO 501,
			and outputs to FOO;UGH CMP.
FOO;_BLETCH,MUMBLE	compares FOO;BLETCH > with FOO;MUMBLE >,
			and outputs to FOO;MUMBLE COMPAR.

File: SRCCOM, Node: SWITCHES, Up: Top, Previous: Commands, Next: Smart

Switches:

Switches are used to select a mode of operation (merging verses
comparison, for example), and to enable bells and whistles.  They
are all explained in more detail in the following sections.
Each switch in this list is the name of a footnote that leads to
the node containg the description of the switch.
The switches are:

/digit	number of consecutive matching lines it takes to tell
	 SRCCOM that the changes have stopped.	*Note /digit: Smart
/@	Indirect.  Take switches and file name from a previous
	 SRCCOM output file.		        *Note /@: Archive
/A	Archive.  Concatenate the differences to the front of the
	 output file instead of overwriting it.
					        *Note /A: Archive
/B	don't ignore Blank lines.		*Note /B: Smart
/C	ignore Comments.			*Note /C: Smart
/D	Disown self and keep running, logging out when finished.
/E	follow each run of changed lines with the next (unchanged)
	 line, if any.			        *Note /E: Format
/F	output a copy of file 2, with changed lines Flagged.
					        *Note /F: Format
/I	automatic merge mode.			*Note /I: Merge
/K	ignore differences in Kase.		*Note /K: Smart
/L	try to detect Labels (MIDAS style).	*Note /L: Format
/M	Manual Merge Mode.			*Note /M: Merge
/S	ignore differences in Spacing.		*Note /S: Smart
/W	say Which file on each line of changes	*Note /W: Format
/X	eXecute commands from a file.		*Note /X: Com File
/Y	try to detect labels, in a general way	*Note /Y: Format
/#	Binary compare (word by word)		*Note /#: Binary
/$	Binary compare of executable files	*Note /$: Binary
/!	Force comparison even if the two filespecs specify the
	 same file.  If you ask to compare FOO < and FOO > when there
	 is only one version of FOO, SRCCOM will normally see this
	 instantly and just say "NO DIFFERENCES ENCOUNTERED".
	 This switch would force a comparison.  I am not sure
	 if it is ever necessary;  I put it in to make sure nobody
	 would be screwed by the feature.

File: SRCCOM, Node: SMART, Up: Top, Previous: Switches, Next: FORMAT

More Intelligent Comparison -- /C:

/C causes differences in the text of comments to be ignored, but
only when they are isolated.  In other words, if a whole run of
differences, preceded and followed by matching lines, consists of
nothing but changes in comments, it is ignored, but changes in
comments are not ignored when other, more serious, changes are nearby.

Unless /B was specified, lines containing nothing but comments will
be treated as blank lines and will be ignored if inserted or deleted.



Less Stringent Comparison -- /K, /S:

/K causes SRCCOM to ignore differences in case, so that "a" and
"A" will be considered identical.  /S causes SRCCOM to ignore changes
in spacing (and tabs, as well), so that MOVE	A and MOVE A will
be considered identical.  Unlike comment changes, spacing and case
changes are ignored even if there is a more serious change nearby.
However, if the space- or case-changed lines are actually printed
because of more serious changes, the space or case changes will be
visible in the printout.  The intent is to allow comparison of files
which have been thoroughly reformatted or converted from all upper
case to all lower case.

If /S has been specified, and /B has not been (blank lines are still
ignored), then a line containing nothing but spaces is considered
blank and its insertion or deletion is ignored.  If /S and /C are
both specified, lines containing only spaces and comments are
ignored.



Less Intelligent Comparison -- /B:

/B causes SRCCOM not to ignore blank lines.  More precisely,
SRCCOM normally considers all sequences of ^J's, ^L's and ^M's
equivalent.  /B disables that.  /B is automatically implied
by /I or /M, to prevent blank lines from being lost in the merging
process.  /B is also useful if the difference file is to be read
by some other program that will process the input files with it.


"In Phase" Criterion -- /digit:

Normally, SRCCOM does not consider that a run of changes has
ended just because it finds a pair of lines that match.  There
have to be three lines in a row from both files, matching.  You
can change the number of lines in a row that have to match by
specifying /1 ... /9, /3 thus being the default.  The time when
it may help to increase the number of consecutive matching lines
required is when SRCCOM is confused by changes occurring near
places where parts of one of the input files are repeated
identically, and SRCCOM is triggering on the wrong one.

File: SRCCOM, Node: FORMAT, Up: Top, Previous: Smart, Next: Merge

Formatting Options -- /L, /Y, /W, /E.

/W causes each line of differences to begin with "1)" or "2)", saying
which of the two input files the line came from.  That information is
redundant, but may be a useful reminder inside a long run of differences
when the header line that gives the file name is off the screen.

/L or /Y tells SRCCOM to try to find the labels in the files, and for
each run of differences to give the most recent preceding label in
each of the files.  This may make it easier to find the place in the
files where the change occurred.  /L looks for assembler labels,
ending with a colon.  /Y treats any unindented line as a label,
unless it starts with a ";".  It is good for LISP files and is
likely to be good for other sorts.

/E tells SRCCOM that after each set of differing lines is printed
the first following line (which DOES match a line from the other
file) should be printed.  This provides slightly more context for
the human reader.  Old versions of SRCCOM had this mode only.


Flagging Mode -- /F:

/F says "flag all the lines in file 2 that don't match file 1".
Instead of a list of the differences between the two input files,
you get a copy of file 2, with marks to indicate which lines were
changed from file 1.  The lines of file 2 are indented with tabs,
and at the front of each changed or inserted line there is a "|".
Places where lines form file 1 were deleted in file 2 are indicated
by four uparrows ("^") at the beginning of the next line of output.
/F automatically turns on /B, and prints nothing on the tty.
The default FN2 of the output file is "FLAGGD".

File: SRCCOM, Node: MERGE, Up: Top, Previous: Format, Next: Binary

Merge Mode -- /M and /I:

/M specifies Manual merge mode.  In this mode, all the differences
are typed on the TTY, rather than output to the specified
output file;  all the identical portions of the input files go
in the output file, as well as such versions of the different
portions as the user specifies.  Thus the output file comes
to contain a merge of the two input files.

When differences are encountered in merge mode, they will be typed
out.  The user will then be asked for input.  If "1<cr>" is typed in,
the first input file's version will go in the merge.
"2<cr>" selects the second file's version. "12<cr>" or "21<cr>"
says that both versions should go in the output file
in the spec'd order.
"I<cr>" says that both versions should go in the merge file,
surrounded by easily identified headers and trailers, as follow:

*** MERGE LOSSAGE ***
*** FILE DSK:SYSENG;FOO 1 HAS:
<text from file 1>
*** FILE DSK:SYSENG;FOO 69 HAS:
<text from file 2>
*** END OF MERGE LOSSAGE ***

The other character that may go in the
input is "T", which will cause SRCCOM to copy from the TTY
to the output file up to an altmode.  "T" may be accompanied by
"1", "2" or "I", and may appear more than once.  For example,
"T1T2T" could be used to simulate "I", if the appropriate strings
are typed in afterward for the three "T"'s.

Also, if anyone cares, "C###" sets the number of columns printed out,
and "L###" sets the number of lines of differences printed out
(### should be replaced by 3 digits) - again, when merge mode is
asking for tty input.



Automatic Merge Mode -- /I:

/I selects automatic merge mode.  This differs from manual merge mode
only in that instead of asking the user what to do, SRCCOM assumes
"I" as an answer, and doesn't bother to print out the differences.
See above under manual merge mode for what "I" does as an answer.
The result is that all the points of difference may be found by
searching through the merge file for "*** MERGE LOSSAGE ***";
The user may then edit the file to select the desired combination
of the two versions.

File: SRCCOM, Node: BINARY, Up: Top, Previous: Merge, Next: Archive

Binary Compares -- /# and /$:

It is possible to use SRCCOM for doing a "binary compare" of two files,
by using either the /# or /$ switch.  These are almost the same,
except that /$ requires the files to be executable program files;
it will load each into a process and compare the process address spaces.
Thus, differences due to symbol tables, word blocking, file formats,
and other misc info are eliminated.  /# on the other hand treats each
file as a bunch of 36-bit words and compares those one by one.

Binary compares do not search for a match when a difference is seen.
Thus, the word at location 100 of file 1 is always compared with
the word at location 100 of file 2, never with any other.  

Notes:	If used, /$ must be the FIRST thing in the command line, preceding
		any file specs.
	These switches interact very poorly with most others.  In
		particular, /I and /M will likely blow up SRCCOM.
	/$ is unlikely to work for files saved with PDUMP or SSAVE
		which have "holes" in their page maps.

These are considered bugs which eventually may be fixed.

File: SRCCOM, Node: ARCHIVE, Up: Top, Previous: Binary, Next: Com Files	

Archiving -- /A:

/A selects archiving.  In this mode, the output file is assumed to
be an archive of all changes to a single program from version to
version, and another page is added to the front of it describing
the new set of changes.  It is ok for the file not to exist -  it
will be created.  Archiving makes a difference only when the file
already exists, in appending instead of overwriting.
When archiving, the default output FN2 is "CMPARC".

To avoid certain rare screws, the /A should always be mentioned with
the output file or the first input file - never with the second input
file.



Indirection -- /@:

The first input file, <in1>, may be specified "indirectly".  That
means that the name of the output file from a previous comparison
is specified, that file is read to discover the names of the files
used to generate it, and what was then the second input file is used
as the first input file now.  From the second line of the previous
comparison's output come the switches used for that comparison; they
are automatically turned on again (only the switches ABCELSW are hacked).
An indirect specification is indicated by the switch "/@".
Thus, after FOO 1 and FOO 2 are compared into FOO COMP2, specifying
"FOO COMP2/@" in a subsequent command will cause FOO 2 to be the
first input file.  Not only the filenames but also the device and
sname are obtained from the indirect file, and they become the
defaults for the second input file.  In the previous example,
if the second input file weren't specified, FOO > would be used.

All the names of the indirect file (the previous output file,
indirected through) default to the names of the output file.  Thus,
if the command

FOOCMP 1_FOO 1

compares FOO 1 with FOO 30, and FOO 31 is generated, the command

FOOCMP >_/@

will compare FOO 30 with FOO 31 to give FOOCMP 2.
This mode works well with archiving; if FOO CMPARC is an archive
whose last comparison is FOO 29 against FOO 30,

FOO_/@/A

will compare FOO 30 and FOO >, appending the differences to the front
of FOO CMPARC.  When using /@ and /A, if the second input file is
explicitly specified the /A must come no later in the command string
than the first input file;  otherwise the defaulting of the indirect
file's FN2 will not work properly (this doesn't apply if either the
output file or the indirect file has its FN2 explicitly specified).

File: SRCCOM, Node: COM FILES, Up: Top, Previous: Archive, Next: Output

Command Files -- /X:

If a program consists of several files, it is convenient to be able
to compare all of them against old versions automatically.  This
requires that SRCCOM be able to find out what all the files' names
are.  That is done by putting a command to compare each of the files
in the desired way in a single command file.  SRCCOM may then be
given a command to take successive commands from that command file,
which may be the same file as the main file of the program!  That is
because the command file contains not bare SRCCOM commands, but
SRCCOM commands surrounded and identified by prefixes and suffixes,
and all text in the file not so identified (the program, for example)
is ignored.

The prefix that identifies a command is ";;SRCCOM COMMAND ;;".
The suffix that marks the end of it is ";;" (or <cr>).
Only the first page of the command file will be scanned.
If the prefix by itself doesn't suffice to
make the SRCCOM commands into comments for all other purposes, then
surely suitable characters in front of it will do so.

For example, if the MIDAS program FOO has files FOO, and BAR, the
following text could be put in the FOO file to make it into a SRCCOM
command file, telling SRCCOM to archive-compare both files:

;;SRCCOM COMMAND ;;FOO_/@/A
;;SRCCOM COMMAND ;;BAR_/@/A

The way to tell SRCCOM to read from a command file is to use the /X
switch, and specify the command file alone as an input file.  For
example, just "FOO/X" would cause the commands in FOO to be executed.
Each command read from a command file is typed on the terminal.  If
an error (such as an open failure) occurs, the reading of the command
file will terminate.  It is an error to try to nest command files.

Filename defaulting works slightly differently while a command file
is in use.  The command that specifies the command file also sets
up default devices and snames for the commands read from the file.
The output device and sname specifed with the command file (they may
be defaulted, of course, but will default to DSK: rather than TTY:)
become the defaults for output files while the command file is being
read.  Those files will never default to TTY: either, even if no
arrow appears in the command.  The device and sname that the command
file came from are the defaults for the first input file while the
command file is being read.  The second input file still defaults to
the first, and the handling of FN1's and FN2's is unchanged.  Also,
indirect files still default to the output files, and still override
the defaults for the input files.

File: SRCCOM, Node: OUTPUT, Up: Top, Previous: Com Files

SRCCOM's Output Format for Difference Files:

Each difference file begins with a blank line, followed
by some number of comments describing the files and switches
that controlled SRCCOM's operation - currently two.  Then
comes another blank line.  Programs should ignore all up to
the second blank line.  An example is

;SOURCE COMPARE OF DSK:SYSENG;SRCCOM 40 AND DSK:SYSENG;SRCCOM 42
;OPTIONS ARE    /3 /L


Each set of differences looks like this:

**** FILE DSK:SYSENG;SRCCOM 40, 2-41 (2009)
<text from file 1>
**** FILE DSK:SYSENG;SRCCOM 42, 2-47 (2315)
<text from file 2>
***************

In "2-41 (2009)", the "2" is the page number, the "41" is the
line number on the page, and the "2009" is the character position
in the file (0-origin, suitable for a TECO J command)
of the start of the first line of text.

When /L is set, header lines look like this, after the first label:

**** FILE DSK:SYSENG;SRCCOM 40, 2-41 (2009) AFTER FOOBAR:

where FOOBAR is the most recent label before the first following line.

Local Modes:
Mode:Text
End: