>>> rcsdos-5.7/README.TXT
>>>  $Id: README.TXT,v 1.2 1997/03/24 21:38:04 elf Exp $
>>>
>>> RCS Revision Control for MS-DOS [package: RCSDOS-5.7]
>>>   Patches and Binaries for RCS 5.7 (Patch Level 13)
>>>
>>> by Marc Singer (elf@netcom.com)
>>>    24 March 1997
>>>

0.   Introduction
1.   What and Where is RCSDOS-5.7?
2.   QuickStart Instructions for the Impatient
3.   Sharing Logfiles Between MS-DOS and Linux/UN*X
4.   Compiling and Configuring RCSDOS-5.7
5.   Bug Fixes and Extensions to RCS for MS-DOS
 .1   RCS_SOFTLINKS
 .2   CR-LF Translation
 .3   RCSBIN Environment Variable
 .4   Change Comments from Files
6.   Known problems ( none we have the answers to %^) ) 
      <Special note for Novell users>
7.   Storing Binary Files in RCS


      0. Introduction

This README provides four things.  Most importantly, it describes what
RCSDOS-5.7 is and where you can get it.  Next comes the QuickStart
section for getting RCS running at once.  There is a section
describing how to configure and compile the patched version of the
source.  And the final section describes some details about the
enhancements to the RCS sources that were necessary to make it run on
top of MS-DOS.

This version of RCSDOS is compiled for DJGPP v2.01.  It is *not*
compatible with earlier versions of DJGPP (according to advice on the
DJGPP list).  I believe that the incompatibility is due to methods
used to pass long command lines.  Overall, this version of RCS is very
stable and has been working for me (and several silently happy users)
for a couple of years.  

Some of the original speed problems have not been satisfactorily
addressed.  While I have crafted a set of perl scripts to handle
commands to report who has what files locked and to synchronize my
working directories, these operations tend to be slower with RCS than
with the commercial packages.  I have not discovered any simple
optimizations that will alleviate the bottlenecks.


      1. What and Where is RCSDOS-5.7?

It's a port of the revision control system, originally authored by
Walter Tichy and presently maintained by Paul Eggert, to MS-DOS.
You will find the compressed archives on 

  ftp://thumper.redtech.com/pub/rcsdos
or
  ftp://ftp.netcom.com/pub/el/elf/rcsdos

For a complete description of RCS and more information about using it,
see your local GNU dealer.  You can find the RCS sources

  ftp://ftp.cs.purdue.edu/pub/RCS


      2. QuickStart Instructions for the Impatient

You can find precompiled versions of the RCS programs and support
utilities in the ZIP archive file RCSDOS57.ZIP.  Fetch and uncompress
the archive.  If you retain the directory structure in the archive,
there are two directories.  One contains the RCS binaries and the
other contains the utilities.  It is best to copy all of these
executables to the same directory so that you can use the RCSBINPATH
environment variable.  More on this topic later.

Create an environment variable USER with your `login' id.  This is the
name that RCS uses to track you as the revision author, but because
this is MS-DOS and NOT Linux, you can use anything.  I use a different
id on MS-DOS from Linux so that I can keep track of where the
revisions are being made.  So, I am `elf' on Linux and `elf-pc' on
MS-DOS.

If you are using vanilla MS-DOS, you will not be able to store your
log files in the same directory as your source files due to the short
file name limitation.  Windows 95 users need to be concerned with
this problem.  Everyone else must create an environment variable
RCSINIT that specifies the -x switch so that the RCS programs will
not append ,v to the file names.  Make sure that a sub-directory
named RCS exists in your working directory to contain the log files.

The primary enhancement to RCS to make it operate on MS-DOS is the
ability to use a symbolic link that points to the log files.
Normally, the RCS programs look for a directory called RCS as a
repository for log files.  If, instead, there is a file named `RCS'
that contains an absolute pathname pointing to the real log file
directory, these RCS programs will perform the indirection
automatically.  In order to make RCSDIFF happy, the basename of this
indirect log file directory needs either be `RCS' or it must have the
extension `.RCS'.

Here is an example.

  Working directory:				c:/project/magic
  Real (shared) log file directory:		r:/magic.rcs
  Symbolic link file:				c:/project/magic/rcs
      contains the string:			r:/magic.rcs

Standard wildcards are supported, so commands like
  rlog -h c:/project/magic/rcs/*.[hc]
and
  rlog rcs/*
will work as expected.  Note that the seashell wildcard of *.{c,cpp}
does not work.


      3. Sharing Logfiles Between DOS and Linux/UN*X

There are a couple of important things to note when sharing log files
between DOS and Linux.  In general, the 5.7 release of RCS fixes the
bugs in earlier releases where this sharing was difficult.

The primary problem was that the lack CR/LF translation can interfere
with programs on either end.  Version 5.7 (and a small bug fix of my
own) fixes this.

The only other sticking point is that you must declare your timezone
on DOS so that the gmtime () function in DJGPP correctly reports GMT.
If you do not do this RCS may disallow a checkin because the date of
the previous revision is later than the date of the current revision.
Set the TZ variable in your djgpp.env file (commonly found in
C:/DJGPP/DJGPP.ENV) to something such as 

  TZ=US/Pacific

and RCS should be happy. (See note 1.)


      4. Compiling and Configuring RCSDOS

In the distribution archive RCSDOS57.ZIP, the file patch13 contains
the unified diff format patches for the changes made to the standard
RCS v5.7 source distribution.  The patch file is relative to the root
directory of the RCS source tree.  In addition to this patch, you'll
need the following:

  DJGPP v2.01 or better
  GNU C compiler for DJGPP v2.7.2.1
  GNU Make and other binary utilities (distributed with DJGPP v2.01)
  GNU Diff v2.6 (v2.7.1 is available as part of DJGPP v2.01)

If you have a version of Larry Wall's PATCH program you can patch the
source tree in place.  Otherwise, you may need to do the edits by
hand.  For the most part, the changes are isolated to a few one-line
changes in the standard RCS source files with a couple of new files,
RCSLINKS.C, GLOB.C (GNU), GLOB.H (GNU), and the contents of the MSDOS
directory.

  1) Apply the file `PATCH13'.
  2) Execute the shell script MSDOS/prepare.sh.  If you cannot execute
     the script, simply copy MSDOS/conf.h and MSDOS/Makefile.src to
     src/conf.h and src/Makefile.
  3) Run GNU make is the src subdirectory.


      5. Bug Fixes and Extensions to RCS for MS-DOS

For the most part, porting RCS to DJGPP and MS-DOS is a matter of
setting the appropriate options in the configuration file.  All of the
segment violation errors and a good number of the errant behaviors of
RCS can be corrected by finding the configuration switch that controls
the non-standard behavior of the DJGPP C libraries--these problems
appear to be rooted in MS-DOS and not any failing on the part of the
DJGPP team.

      5.1 RCS_SOFTLINKS

This feature interprets path elements with the name RCS as containers
for symbolic links and will replace all path elements up to and
including the RCS reference with the contents of that file.  Note
that this differs from the standard symbolic link which may be
relative.  Simple, right?

There are a couple of caveats.  The first is only a concern for
MS-DOS (not Windows 95) users who are using the -x switch to
eliminate the pesky ",v" logfile suffix.  RCSDIFF needs to be able to
distinguish a workfile from a logfile.  It usually uses the ",v"
suffix to identify logfiles, but the -x switch inhibits them which is
necessary without long file names.  So, in order to identify the
logfiles, the linked directory must be either `RCS' or a directory
with the extension `.RCS'.  Thus the directory name that is in the
RCS soft-link file must end with the letters `RCS'.  So far, this has
not proven to be a bother.  If you do not use the -x switch, then
this limitation is not imposed upon you.

Let me give an explicit example.  Your development directory might
have one source and the link file.

   foozle.c      RCS

The file RCS contains the absolute pathname of the real logfile
directory: c:\logfiles\projfoo.rcs.  This directory could not be
c:\logfiles\projfoo, but it could be c:\logfiles\projfoo\rcs.

The second caveat is that we now have the problem that the command

  rlog -h rcs/*

cannot be expanded by DJGPP on starting the program.  MS-DOS sees a
file named `rcs' so the wildcard is meaningless.  Thus, I added glob.c
to the sources and perform link expansion in the function getRCSINIT.

Scan the source code for RCS_SOFTLINKS for all of the places that were
modified to support links.


      5.2 CR-LF Translation

Version 5.6 of RCSDOS always read and wrote logfiles and workfiles in
the MS-DOS Text mode.  This caused binary data checked into RCS to be
vulnerable to corruption if the data contained \x0a characters with
a preceeding \x0d.  While there is a keyword mode -kb (see rcs.1),
nothing is done to allow v5.6 logfiles to be readable by v5.7
programs.  Thus, a change was made to the workfile processing code to
always generate correct line termination sequences.


      5.3 RCSBIN Environment Variable

This environment variable is optional, but recommended.  When it is
not present, the RCS programs search the PATH environment variable for
programs.  RCS runs much more quickly when it does not have to search
for programs.  RCSBIN points to the directory where the rcs
programs, including the modern DIFF.EXE and DIFF3.EXE, are found.

Note that this variable changed from RCSBINPATH to RCSBIN since the
last patch.  This is to make it compatible with CVS which uses the
variable RCSBIN to find RCS programs.


      5.4 Change Comments from Files

By prefixing the change comment with an at sign, `@', you can cause
the checkin command to read the comment from a file.  For example:

  ci -u -m @cmnt/changes.txt cycles.c


      6. Known Problems

When using DOS and not Windows 95, RCSDOS only supports the -x option
which forces RCS to use the same name for the log file as the source.
This means that you must use a separate RCS directory for the log
files.  In Windows 95, this is no longer a limitation.
 
Some Novell users have complained that co -l after initial ci
generates the error:

  RCS/source.in --> source.in
  Revision 1.1 (locked)
  co: RCS/source.in No such file or directory
  co: saved in RCS/source.i_

This is fixed in the patch 13 by changing the rename behavior to
always unlink the target before renaming. [Teun Burgers burgers@ecn.nl]

The latest patches have no outstanding bugs.


      7. Storing Binary Files in RCS

Though it has not been extensively tested, this release of RCS should
support the binary logfile type.   Logfiles that will store binary
data should be primed before storing data in them.

  rcs -i -kb tomcat.bmp

The -kb switch sets the keyword expansion mode for the file to binary.
Check-in and check-out will function normally, but the deltas will
store binary differences.


-----
Notes:
 (1) TZ is needed in programs which do not access djgpp.env.  Some
     internet access software fits in this category.  One package
     defaults to PST on e-mail if TZ is not set in AUTOEXEC.BAT. I set
     TZ=EST5 because I do not like Day Light Saving Time.  This works
     with NIST [NBS] time set as well. 
       [Frank Donahoe fdonahoe@wilkes1.wilkes.edu]
