MREV - Mark REVisions Utility v.1.1
Written for the public domain by Paul R. Van Sickle
Portions copywrite (c) 1987, True BASIC, Inc.


Introduction
------------
Very often in the course of developing or maintaining any
type of documentation or programming system that is shared by a
group of people, it is extremely helpful to have some handle on
the revisions made to those documents or programs. MREV's main
function is to compare two standard ASCII format text files, (one
assumed to be the original text, the other a revision of that
text) and output a third text file that is based on the revision
file, with the revisions marked or date stamped. When printed,
the marked revision document quickly draws the reader who was
familiar with the original to scrutinize the revisions, thereby
saving him or her considerable time in having to discern what the
revisions were before auditing their content.

While this is certainly not a new idea, its implementation
on micro computer based software seems to be. MREV was written
for the public domain in the hopes that it would draw attention
to the need for revision standards. MREV is designed to be
flexible enough so that it can be incorporated in almost any
documentation or source code revision procedure. With the
introduction of MREV, all that is really required is the desire
and time to invent such a procedure, and the discipline to use
it.

MREV allows you to tailor the revision stamping to your
specific requirements, and save them as default options. For the
programmer, MREV also offers a line number resequencing function
that can provides the capability of using any editor or word
processor to edit source files requiring sequence numbers.


Command Line Syntax
-------------------
The program uses the DOS "command line" for all input, which
allows it to be executed from a batch file. If the program is
invoked without any input, the command line syntax for all
options and switches will be displayed and control will
immediately be returned to DOS. The general command line syntax
is:

MREV orgfile.ext revfile.ext [options] [switches]

where:

| "orgfile.ext" is the name of the original file, "revfile.ext" is
the name of the revision file. Path and/or drive designations
can also be included. (Note [options] and [switches] will be
individually explained later).

The file arguments given should be standard ASCII format text
files, or the results will be unpredictable. Since most word
processors have a way of producing such a file, this shouldn't be
too much of a problem, but it might require an extra step... and
a little research on your part. If you're using a simple text or
program editor, chances are its output files will work just fine
"as is".

After the original and revision file parameters are given, the
[options] and [switches] can be given in any order, with or
without intervening spaces, in upper or lower case, as long as
each conforms to its given syntax. Each option and switch is
discussed in detail in the following sections.


Change Stamp - /C Option
------------------------
The syntax for the Change Stamp - /C option is:

/C [begin-column],[length],["literal"],[(i)nsert | (o)verwrite]

where:

[begin-column] is a number indicating the starting column of the
change stamp.

[length] is a number indicating how long the change stamp is.

| ["literal"] is an alpha-numeric expression representing the actual
| change stamp. It MUST be enclosed within double quote (") marks.
Note that if [length] is greater or smaller than the number of

characters represented by ["literal"], the literal will either be
truncated to [length], or left justified with trailing spaces.
There are three special literals:

"JDATE" - will stamp current Julian date in the form:
YYDDD. (example: 88024)

"DATE" - will stamp current Gregorian date in the form:
CCYYMMDD. (example: 19880124)

"TIME" - will stamp current time in the form: HH:MM:SS.
(24 hour clock. example: 23:12:07)

[(i)nsert | (o)verwrite] is a single character, either "i" or
"o", representing the change stamp MODE. The change stamp mode
determines whether the change stamp is to be INSERTED (i) into
the text, or OVERWRITTEN (o) on top of the text. If "I" is used,
all characters in the text from [begin-column] to the end of ALL
lines (both original and revision lines) will be shifted to the
right of the change stamp. (Original lines will be padded with
spaces in the change stamp area). If "O" is used, any characters
on a REVISION line (not original lines) corresponding to the
| change stamp columns will be overlaid with the change stamp. If
it is desired to clear the change stamp area in original lines,
use the /R reset switch (explained below).

| The internal Change Stamp default is: /c1,5,"|",i. This will
insert the change stamp "| " in front of each revised text
line. Original text lines will have 5 spaces padded in front of
each to allow the text to remain properly aligned. You can
create your own default with the /W write options switch
(explained below).


OUT FILE NAME - /F Option
-------------------------
The syntax for the Out File Name - /F option is:

/F [filename.ext]

where:

[filename.ext] is any valid DOS file name, with or without a path
name and/or drive designator.

The internal Out File default is a derivative of the revision
file name with the extension: ".CHG". You can create your own
default with the /W write options switch (explained below).

Note that the original file or the revision file can also be used
as the Out File name. A warning message will be issued in time
to inform you of this fact, just in case this was an unintended
mistake.


SEQUENCE NUMBER - /S Option
---------------------------
The syntax for the Sequence Number - /S option is:

/S [begin-column],[length],[increment],[(i)nsert | (o)verwrite

where:

[begin-column] is a number indicating the starting column of the
sequence number.

[length] is a number indicating how long the sequence number is.

[increment] is a number indicating the incremental step of the
sequence number.

[(i)nsert | (o)verwrite] is a single character, either "i" or
"o", representing the sequence number MODE. The sequence number
mode determines whether the sequence number is to be INSERTED (i)
into the text, or OVERWRITTEN (o) on top of the text. If "I" is
used, all characters in the text from [begin-column] to the end
of all lines will be shifted to the right of the sequence number.
If "O" is used, any characters corresponding to the sequence
| number columns will be overlaid with the sequence number.

There is no internal default for the Sequence Number option. You
can create your own default with the /W write options switch
(explained below).


TRUNCATION - /T Option
----------------------
The syntax for the Truncation - /T Option is:

/T [end-column]

where:

[end-column] is a number representing the last column to be
included on each line. Any line in the revision file whose
length is in excess of this figure will be truncated to this line
length in the output file. Note that this option has no effect
in the comparison process between the original and the revision
files; all characters of each line, even those beyond the
truncation limit, will be compared.

There is no internal default for the Truncation option. You can
create your own default with the /W write options switch
(explained below).


RESET Previous Change Stamps - /R Switch
----------------------------------------
The Reset Previous Change Stamps - /R switch works in conjunction
with the Change Stamp - /C option in overwrite mode. This switch
will place spaces in the change stamp area (as defined by the
change stamp option) of all original lines in the output file.
This switch is useful if you're using MREV's output file as part
of a draft revision procedure and it is desired not to have the
revision marks accumulate but "reset" every time it needs to be
distributed. It is also useful if you are using cumulative
unique line stamps (for example, revision dates) and you want to
produce a copy of the document that hides all but the last round
of revisions.

Note that the /R switch works only change stamp overwrite mode...
it has no effect in insert mode, and will be ignored if used.


WRITE OPTIONS - /W Switch
-------------------------
The Write Options - /W switch allows you to save all options as
entered on the command line to a special file in the root
directory of the current drive called "MREV.OPT", so you might
not ever need to type them again. Subsequent executions of MREV,
(provided no options are given) will use the saved options from
that file as the default by appending them to the command line.
Note that the Reset - /R switch is also saved if present. The
| MREV.OPT file can, of course, be created and edited independently
| of MREV.EXE.


Executing the Program
---------------------
Starting off, it might be helpful to set up a couple of
fairly small test files (as a sample original and revision
file) and experiment with the options until you get the desired
result.

As noted earlier, when the program is invoked without any
additional parameters, a synopsis of all options and switches is
displayed and control returns to DOS.

Diagnostic error messages will appear if invalid file names
or syntactically incorrect options are given. The program will
halt and return to DOS whenever a fatal error is detected.

Once the "PROCESS: Load Revision File to memory..."
message appears, you'll know that you've at least gotten through
all of the initial command line parsing edits and file checks.
How long the processing takes depends entirely on the speed of
your machine, the size of your files, and the amount of your
revisions. (The more revisions, the longer it will take.
Conversely, the more similarities between the original and
revision files, the shorter it will take).

A note on file sizes: This program requires the revision
file to be loaded into memory. Therefore, there must be enough
free memory for both the program and the file to fit into. MREV
will test available memory before attempting to load the file,
and produce an error message if it appears to be insufficient.
Note that if you have this problem and have a lot of TSR
(Terminate & Stay Resident) "pop up" programs loaded, you may be
able to solve it by temporarily removing them from your AUTOEXEC
batch file.

When MREV terminates after processing, a brief report of
line totals and execution time will appear on the screen.

You can use whatever tools you have at your disposal to view
or print the output file, or simply TYPE it to see what it looks
like.

You may be surprised to note that extra blank lines in the
revised text will NOT be marked... this is because the program
only compares TEXT lines, not null (CR/LF only) lines. I view
this to be more of a feature than a problem, however.

Note that this program only works with ASCII text files... do
NOT attempt to use word processor files directly, as the results
are unpredictable. You will probably want to come up with some
scheme for creating "print image" ASCII files with your word
processor for use with this program. Consult your word
processor's manual if you're not sure how to go about doing that.

Programming Notes
-----------------
I decided to write this program after a frustrating search to
locate ANY PC product that would accomplish this task, either in
the public or private domain. Obviously, the most efficient way
to perform this task would be to have the function incorporated
directly into a word processor... but I haven't found any word
processor that advertises this feature, and even if there are
some out there, I seriously doubt that they could be as flexible
as this utility. There are a number of "file comparer" programs
available in the public domain, but I haven't found any that
produce output that highlights the differences in the context of
the documents themselves. If you hear or know of anything like
this, please drop me a line.

The program was written in True BASIC version 2.01, which is
published by Addison-Wesley. It is the only BASIC compiler I
know of that allows you to load string arrays up to the limits of
memory. It is also one of the most "elegant" languages I've ever
worked with on a micro. (And no, they didn't pay me to say that,
either!) I originally wrote the program using another, more well
known BASIC compiler (who shall remain nameless), but because of
the string array 64K limitation, I was forced into concessions
that produced unaceptably long run times.

No doubt this program could have been written in C or Pascal
with considerable savings in .EXE file size and extra speed, but
I don't know those languages well enough and I simply don't have
enough time to learn them right now.

The source code is included in this archive just in case you
have any interest in seeing how the program works or (God forbid)
you need to debug the program. If you have a True BASIC compiler
and you'd like to make enhancements to it for public consumption,
all I ask is that you send me a copy of the revised source code
and give me a chance to review and approve it before you download
it to the rest of the world.

If you do study the source code, you'll note it is written
using a very simple, "Top-Down" approach, with very few comments.
There are no GOTO's, but there aren't any subroutines, either.
There is only one DEF function, which is used to format the
output line. Everything is written down pretty much in the order
| it is needed or executed, and as such, should be fairly easy
reading for anyone even if you aren't familiar with this form of
BASIC. One legitimate criticism is that I probably should have
attempted to use CASE statements to replace some deeply nested
IF's. Never the less, the program conforms to my "Top-Down"
philosophy, which is perhaps best expressed in my trait of never
subscribing to a magazine if it contains phrases like, "continued
on page 182".




| Disclaimers
| -----------
| Since the intention of this program right from the start is
| to never make me even one plug nickel, I also don't expect to be
| held personally, legally, financially, or morally liable for its
| use or abuse by anyone what so ever, no matter what the
| circumstances are, from now until the end of time.

Suffice to say that I've made every effort to insure the
| quality and safety of the program as distributed. If problems,
| bugs, or bogus versions are found, publish your findings on a BBS
| as soon as possible so that as many people can know what you
| know, and, if so inclined, send me a letter to let ME know. My
| address is:

Paul R. Van Sickle
9171 Milton Lane
Clarence, NY 14031

I can't make any promises about future fixes or enhancement
versions of the program. At the present time, I have no way to
| gauge what the response to this utility will be, nor to the
| concepts that it represents. And, while I would like to closely
| monitor the success or failure of this endeavor, I am presently
| quite busy enough with my own professional career to preclude any
| role more than as an occasional (albeit paternal) consultant.

| THIS SOFTWARE IS NOT FOR SALE IN ANY FORM. This software is
| entirely original and was written partly as a very small way of
| my saying "Thanks" to all those unrecognized and often taken for
| granted authors who've contributed so much to the public domain,
| and whose programs I use almost every day. If someone has or has
| tried to sell you this program, I'd suggest you publicly disgrace
| them as loudly as possible. On the other hand, I wouldn't want
| you to spend a bundle for lawyers, either. I encourage anyone
| with enough entrepreneurial enthusiasm (not to mention time) to
| borrow any of the concepts or code contained here in developing a
| product or system that includes all or more of the functionality
| of this one... as long as it isn't THIS one.

| Many happy revisions to one and all.


| - pvs January 30, 1988
|