README for RCS 5.7 for PC's running under OS/2, DOS or Win95/NT
---------------------------------------------------------------

Release date: Jan 12th 1997

Changes: - added binary mode support to cii/coo (from Hans-Otto Ultes)
	 - fixed bug causing "ci -f" to fail if no headers to expand
	 - fixed bug causing crash with pseudo symlinks
	 - fixed bug causing misleading error message due to nobody
	   being logged on to networking software recognized by RCS
         - include GNU info, TeX DVI and OS/2 IPF formatted docs
           (from K.H. Marbaise)
         - make Win95/NT executables with RSXNT 1.3, 
           a few source changes were required

Release date: May 20th 1996

Changes: - fixed serious bug with every other file argument 
           often not working

Release date: May 14th 1996

Changes: - upgraded RCS to GNU RCS 5.7
	 - upgraded diff to GNU diff 2.7.2
	 - DOS 32-bit diff now only supplied in Watcom+PMODE/W version
	 - support for binary files working now, see below
	 - support for pseudo symbolic links
	 - support for Windows 95 and Windows NT

Release date: May 1st 1995

Changes: - the cii (rcsfront) indirect invocation method did not 
           work for DOS, now just use the real executable
         - cii itself did not work correctly on FAT file system
         - integrated fix from Paul Eggert for "rcs -o"
         - minor adjustments for emx 0.9a
         - added a second 32-bit diff for DOS, created with
           Watcom C 10.0 and the PMODE/W extender, for those
           that have trouble with the emx generated one

Release date: December 16th 1994

Changes: - fixed another problem with 32-bit executables for OS/2,
           they seem to work fine now
         - updated emx and rsx DOS extender runtime modules

Release date: September 17th 1994 (never made public)

Changes: - fixed problem with checkout failures for 32-bit executables
	 - significant speedup for checkout of old revisions with
           the 32-bit executables (side effect of above fix)

Release date: August 1st 1994

Changes: - added workaround for bug in MS-DOS SHARE.EXE
	 - new MS-DOS executables
	 - slightly corrected rcs/src/ms/Makefile and README files

Initial Release date: July 11th 1994


0. Archive Locations
--------------------

This package is primarily distributed as

  ftp://ftp.leo.org/pub/comp/os/os2/gnu/devtools/rcs57pc1.zip
  ftp://ftp.leo.org/pub/comp/os/os2/gnu/devtools/rcs57pc2.zip

and

  ftp://ftp.cs.purdue.edu/pub/RCS/rcs57pc1.zip
  ftp://ftp.cs.purdue.edu/pub/RCS/rcs57pc2.zip

The first archive contains the more widely used DOS, Win95/NT and OS/2
32-bit executables as well as formatted documentation files. The
second one contains the not so often needed OS/2 16-bit executables,
source code and unformatted documentation files.

As long as the author of this revision maintains the PC versions of
RCS and has access to this archive site, the latest version can be
found there (with file names indicating higher revisions, perhaps).

Other sites will have copies of this archive too, such as

  ftp://ftp.cdrom.com/os2/... (see 00index.txt file for exact location)
  ftp://ftp-os2.nmsu.edu/os2/... (the Hobbes archive, see their index)

which are the best known OS/2 ftp archive sites on the Internet. In
addition, one should be able to find it in the "Simtel" archive.

Related packages that may be of interest for RCS users include (all
path names relative to ftp://ftp.leo.org/pub/comp/os/os2/): 

- CVS 1.4 (gnu/devtools/cvs14p9b.zip and cvs14p9s.zip) or newer

  CVS is a more advanced revision control system for multi user access
  to shared source code without locks and with conflict resolution.
  It works on top of RCS.

- GNU make 3.74 or newer (gnu/devtools/gnumake.zip)

  This is a "make" program that knows how to access source files
  maintained with RCS without need to specify special rules.

- GNU Emacs 19.30 or newer (gnu/emacs-19/*)

  The GNU Emacs editor is a very powerful programmer's editor that
  provides easy access to files maintained with RCS via its included
  "vc" package.

And, because they can be used to create executables of this RCS
version: 

- the emx programming environment (gnu/emx+gcc/*)

  The emx environment (current version 0.9c) provides
  tools to create and run 32-bit programs under OS/2 2.x and
  MS-DOS. It uses many GNU programs, such as the gcc C/C++ compiler,
  gas assembler, gdb debugger and libg++ class library.

- the RSX DOS extender and Win95/NT runtime environment for emx, 
  currently v5.10 (gnu/emx+gcc/contrib/rsx510.zip and rsxnt13.zip)

  This is an alternative DOS extender for emx to let emx programs
  run in a MS-DOS DPMI environment (such as Microsoft Windows 3.x)
  as well as a kind of "emx runtime for Win32".


1. Overview
-----------

RCS is a revision control system, usually used by software developers
to maintain revisions of the source code for the software they write.

This package contains in subdirectories:

rcs	 	the source code for RCS 5.7

rcsfront	the source code for RCSFRONT, a small (and unsupported) 
		front end tool for easier management of a collection
		of files under RCS control

diff, diff16	the source code for the GNU diff program, an important
		tool required for RCS (two versions, see below)

doc		preformatted documentation (plain text and 
		PostScript format)

bin32		OS/2 2.x executable programs (32-bit)
bin16		OS/2 1.x executable programs (16-bit)
bindos		MS-DOS executable programs (16-bit, but see below)
binnt		Windows 95 and NT executable programs (32-bit)

It is assumed that you are familiar with the concept and usage of
RCS. If that is not the case, please read (or print and read) the
original RCS documentation and manual pages available in the "doc"
subdirectory. This file only documents platform and/or release
specific information.


2. Installation
---------------

First, just pick the right set of executable programs and put them in
a directory, which should be listed in the PATH environment
variable. For the OS/2 32-bit executables, since they use a few DLL's
(dynamic link libraries), this directory should also be listed in the
LIBPATH statement in CONFIG.SYS.

Second, you need to set/check a few environment variables:

a) Either the USER or LOGNAME variable must contain the user's
   (i.e. your) last name, unless you have network software installed
   and want to use the name with which the user is logged on to the
   network (see below). In this latter case, you need not set one of
   these variables, if RCS is able to detect the logged on user name.

b) The TZ environment variable should contain your proper time zone
   definition. If you use the OS/2 32-bit executables, you can also
   use the EMXTZ variable if some other software on your machine
   requires a more complicated value of this variable which programs
   compiled with emx (see below) don't understand. 

   The TZ variable usually contains, the time zone name, the time zone
   offset in hours to GMT and optionally the daylight savings time
   zone name, examples are:

	SET TZ=PST8PDT		(pacific standard time)
	SET TZ=CET-1		(central europe time)

c) The RCSINIT variable can contain options for RCS you want to use all
   the time. The default value is suitable for work under DOS and on FAT
   file systems under OS/2, i.e. all RCS files go into a subdirectory
   RCS of the working directory and have no special suffix.

   If you work under OS/2 on a HPFS file system (or any other file
   system that can handle long names), you may want to follow the Unix
   convention of using RCS files in the working directory that may
   also have a suffix of ",v". For this case, use "SET RCSINIT=-x,v/".

   Windows 95 and NT also support long file names and the ,v suffix,
   but the ,v suffix not on FAT file systems, only on network drives
   (that reside on OS/2 HPFS or NT NTFS servers or on Unix NFS
   servers).

   See the RCS manual pages for details about all other available
   options.

d) Make sure you have a properly set TMP (and possibly TEMP)
   environment variable that points to a directory where
   temporary files should be stored.

e) (this is optional, for OS/2 32-bit executables only)

   The RCSLOAD environment variable can be set to a decimal number
   specifying the amount of minutes to keep the RCS (and diff)
   executables preloaded in memory. This requires that you have the
   emx runtime package installed (emxload.exe is required). This
   method may speed up the use of RCS from within GNU Emacs or with
   CVS if many files are checked in/out in a batch because that can
   result in a large number of executed subprocesses with RCS
   programs.

After these steps, you should be able to use the RCS commands.


3. RCS
------

RCS is a widely used revision control system available for most Unix
systems and several other platforms (such as in this package, for OS/2
and MS-DOS/Windows, Windows 95 and Windows NT). It allows shared use
of RCS files in heterogenous networks, for example. A few notes on PC
specific details, however:

* Note 1: Network Software

The RCS programs recognize certain PC networking software and query it
for the name of the logged on user. The result can be overridden by
the value of the USER or LOGNAME environment variables. The LOGNAME
variable has precedence over the USER variable.

Under OS/2, the RCS programs recognize the following networking
products:

- IBM LAN Server
- IBM Peer (Warp Connect)
- Microsoft LAN Manager
- Novell NetWare

In addition, the installation of the IBM TCP/IP for OS/2 product
usually sets the USER environment variable in CONFIG.SYS.

Under MS-DOS, the following networking products are recognized:

- IBM DOS LAN Requester or DOS LAN Services
- IBM PC Network
- Microsoft LAN Manager Client
- Novell NetWare Client

Also the locally logged on user name is recognized if networking
components are used in:

- Microsoft Windows for Workgroups
- Microsoft Windows 95
- Microsoft Windows NT

Any product compatible to those mentioned should work as well.

Note that network support in RCS means only that the RCS commands can
retrieve the current user name from the networking software, nothing
more. In particular, RCS relies on correct support for file locking
and "strange" file modes (such as creating a read-only file and
writing to it before closing it for the first time) on network drives.
RCS only uses regular OS file system services on network drives.

* Note 2: binary files

This version of RCS for the PC does now support revision control of
binary files. The main goal, however, is to allow control of source
files in heterogenous environments. In such environments, the systems
can have different conventions for line separation in source code
files. To allow shared use of RCS files between systems with different
line separators, a conversion must take place when checking in/out
files. 

This, naturally, would break many binary files. Therefore a special
option, -kb, must be used for binary files with this RCS version to
mark them as binary files. Before you can check in a binary file you
must initialize an empty RCS file with "rcs -i -kb <rcsfile>". Do not
use -kb for plain text files because it makes those RCS files
non-portable to other operating environments.

The way how RCS currently stores "differences" between the revisions
of a binary file is quite inefficient (but more or less portable).
Future version of RCS may support better methods.

* Note 3: RCS file path names

Whenever a path name passed to a RCS program has /RCS/ in it, it is
treated as a RCS (rather than a working) file. However, that /RCS/
component must be specified in upper case even on the PC operating
systems where path names are normally not case sensitive.

So, d:/work/RCS/foo.c and e:/proj/RCS/subproj/bar.c are recognized as
RCS files while e:/proj/free/rcs/src/ci.c is recognized as a working
file.

In addition all PC operating systems treat / in path names exactly
like \ as a path name separator even though \ is much more widely
known and used as such. However, under Unix / is the only path name
separator and thus RCS uses it in both the programs and the 
documentation. Please don't be confused by this fact and keep in mind
that it simply doesn't matter which one is used on the PC, at least
as far as RCS is concerned.

* Note 4: pseudo symbolic links

RCS usually uses the ./RCS directory for separating the RCS files from
the working files. There are tools like RCSFRONT (see below) and CVS
to separate them further (allowing to put them in entirely different
locations). For users of plain RCS, under Unix it is a widely used
practice to make ./RCS a symbolic link to a different location in the
directory tree in order to separate working and RCS files.

There is now a new feature in RCS for the PC that mimics Unix-style
symbolic links for the PC operating systems because they don't support
symbolic links natively in most cases (you can have symbolic links if
you use TVFS under OS/2).

How does it work? When, instead of the ./RCS subdirectory, a regular
file ./RCS exists, a single line of text is read from it and treated as
the actual path name of the RCS directory. This can be either an
absolute path name or a path name relative to the current directory. 

So if you are currently working in the directory E:\Work and have a
file RCS there that contains the line N:\Project\Repository, then a
command like "ci foobar.c" will check in foobar.c into the RCS file
N:\Project\Repository\foobar.c,v as if ./RCS were a Unix-style
symbolic link to that location. (Note: the ,v suffix is only available
when long file names and the , character in file names are supported
and also RCSINIT is set accordingly.)

However, you must either use the ,v suffix for the RCS file names
(set RCSINIT accordingly) or specify a path name in the ./RCS file
that contains a /RCS/ component (/RCS/ must be in upper case), 
otherwise the RCS programs will abort because they can't determine 
where to store the RCS file.

* Note 4: rcsfreeze

RCS contains one utility program (rcsfreeze) not written in the C
language but as a bourne shell script. Even with a bourne shell for
the PC it is not advisable to use it on the PC. Instead, I have
rewritten the exact same semantics as a REXX procedure which can be
used under OS/2 (1.x or 2.x).

This REXX procedure is, of course, useless on MS-DOS for two reasons.
First, unless you have IBM PC-DOS 7 (or newer) or a free REXX
interpreter for DOS, you cannot even get it to run. Second, it depends
on long filenames. 

If you have a REXX interpreter for Windows 95 or Windows NT, you may get
it to run with some changes, but that has not been attempted so far.

Rewriting the program in C would solve that problem but would also cause
extra work ...


4. RCSFRONT
-----------

The RCSFRONT program, written by Jason P. Winters and Craig J. Kim is
distributed by the Free Software Foundation. It allows checking in/out
whole collections of files or even whole directory trees with RCS. It
was heavily modified to run on the PC. In addition, it does not seem
to be maintained actively any longer.

Of course, RCSFRONT is no substitute for more sophisticated software
that builds on RCS for similar goals, such as CVS. But it may be
sufficient for use on standalone systems or single-programmer
projects. See its manual page in the "doc" subdirectory for more
details. It is a bit difficult to get it working if you are unfamiliar
with it.

Note: only single line log messages are posssible with cii at the
moment, due to limitations in RCS's ci and the PC command line
interpreters.


5. GNU diff
-----------

The RCS programs depend on the availability of the diff command under
Unix, to compare two files (or two different revisions of a file in
the context of RCS). Since that is not a standard command on PC
operating systems, a version of it, the Free Software Foundation's GNU
diff program, is included in this package. Please use only this diff
program with RCS if possible.

Since the reliability of RCS depends on that of the diff program very
heavily, a few more words on this topic:

This package supports PC's running OS/2 2.x (a 32-bit operating
system), OS/2 1.x (a 16-bit operating system) and MS-DOS (a 16-bit
operating system which, due to lack of any protection, allows
implementing so-called DOS-extenders to run 32-bit programs on top of
it). Windows 95 and NT are also supported.

The GNU diff program (current version is 2.7.1), which works very well
with RCS, is inherently a 32-bit program (it uses rather large data
structures, for example). It can be compiled for OS/2 2.x and Windows
95/NT without much effort. However, that is not the case for the
16-bit target systems. Because of this fact, long time ago I put a LOT
of effort into porting the then current version (1.15) to let it run
under OS/2 1.x and under MS-DOS, and testing it thoroughly. As you can
see from the version numbers, it has undergone quite some development
since then and porting the current version again to OS/2 1.x and
MS-DOS would be a lot of work.

Because the functionality of diff that is used by RCS has not changed
since 1.15 and since it does not make sense to spend a lot of time for
the 16-bit target operating systems any longer, I decided to include
*two* versions of GNU diff in this package. The old version, 1.15, is
included for use under OS/2 1.x and MS-DOS in the "diff16" subdirectory
and the current version, 2.7.1, is included for use under OS/2 2.x and
Windows 95/NT (and MS-DOS on 386 or better CPU's, see below) in the
"diff" subdirectory.

Since MS-DOS can be used to also run 32-bit programs with some kind of
DOS extender, this current version of GNU diff can also be used under
MS-DOS, if a 386 or higher CPU is available. This is very important
because MS-DOS limits normal DOS programs to use only up to 640k of
memory less the amount used for MS-DOS itself. And since some RCS
programs call diff as a subprogram, even less memory is available for
diff. So, naturally, the diff program when running under DOS can fail
with "out of memory"-type errors if you try to use RCS commands on
larger files. If that occurs, you should switch to the 32-bit version
of diff, diff-32.exe in the "bindos" subdirectory and rename that to
diff.exe.

The RCS commands merge and rcsmerge depend on the availability of
another related command, the diff3 program. This program is a
three-way file comparison/merge program that in turn uses the diff
program as a subprogram. A version of it is included with the GNU diff
program in the same package. 

The user interface of the diff3 program was changed noticable between
versions 1.15 and 2.1 and the RCS programs merge and rcsmerge require
at least the diff3 program included with GNU diff 2.1. For this reason
and since it is a much smaller program than diff itself, the GNU diff
2.6's diff3 program has been "ported back" to GNU diff 1.15 and is
also used in the 16-bit target environments.

To make a long story short, while the executables for the RCS programs
and RCSFRONT for all target environments are made from the same source
code, two different versions of GNU diff (1.15 and 2.7.1) are used to
create the diff program's executables for the target platforms, 1.15 for
16-bit OS/2 1.x and MS-DOS and 2.7.1 for 32-bit OS/2 2.x, Windows 95/NT
and MS-DOS on 386 and up PC's.


6. The emx toolkit and the emx and rsx DOS extenders
----------------------------------------------------

The emx 0.9c kit with patch 2 applied was used to create the 32-bit OS/2
2.x executables. This toolkit uses the GNU gcc compiler and is freely
available to everyone. At least the 0.9b version is absolutely required
or you can experience loss of data with the generated programs, if you
want to recompile yourself.

The emx kit also includes a DOS extender (emx.exe) that allows to run
32-bit emx-compiled programs under plain DOS and in VCPI environment
(certain DOS "memory managers" provide this environment). To run them in
a DPMI environment (such as in DOS windows under Microsoft Windows 3.x,
OS/2 2.x, Windows 95 or NT), a different DOS extender is available,
called rsx (rsx.exe). The emx-compiled 32-bit DOS programs automatically
select the right extender to run on at runtime. 

So should you want to use 32-bit DOS emx-compiled RCS executables, you
should make yourself familiar with those two extenders. The 32-bit DOS
executables are not included in this package since the 16-bit ones
should fit well in almost all DOS situations. If you want the 32-bit
ones, you will have to recompile yourself. When using emx to compile RCS
for DOS, no network support is available for technical reasons, however.
But then, you don't gain much from them, since the RCS programs (as
opposed to GNU diff) do not reach the MS-DOS 640k limit.

You should be able to find the full packages of emx and rsx at the same
places where you got this RCS package. Note that you may already have
either emx.exe or rsx.exe or even both on your MS-DOS system because
they are popular and you may be using some other software that depends
on them. In such a case make sure you have only one copy (the newest
one) on your system available via the PATH environment variable.

I mentioned that the emx toolkit was used to create the OS/2 2.x
32-bit executables. To save disk space, the RCS (and RCSFRONT and GNU
diff/diff3) programs are linked with the shared runtime library of
emx, so you have only copy of it on disk and not one in each separate
executable. This emx runtime consists of emx.dll and emxlibcs.dll. If
you followed the installation instructions above, you should not
notice any difference to "normal" statically linked programs. Since
many free programs for OS/2 2.x are compiled with this
compiler/toolkit, chances are big that you already have a copy of
these DLL's on your system. Make sure you keep only one of them (the
newest one) in a directory listed in the LIBPATH statement in your
CONFIG.SYS.

In addition, because the RCS programs use a common set of utility
functions, these have been put into another shared library,
rcslib.dll. This further reduces disk space requirements
considerably. Also, the GNU regular expression library used by GNU
diff is also linked in a separate DLL, gnuregex.dll, since it is quite
large and many of the FSF's programs use it which are available for
OS/2. You need only one copy of it on your system too.


7. Other compilers
------------------

The 16-bit DOS and OS/2 executables are compiled with Microsoft C 6.00A,
an environment that is no longer maintained by Microsoft but works well
enough to keep it. Newer Microsoft compilers may work for DOS but are
untested. The Visual C++ 4.0 (Microsoft C/C++ 10.0) can be used for
Win32 executables, it supports even the shared rcslib.dll method like
emx does for OS/2 and RSX/Win32.

The Watcom C/C++ 10.6 compiler can be used for all target environments.
However, the code it generates is less compact than that created by the
other compilers so no included executable sets were generated with it,
with one exception. The diff-32.exe in tbe bindos subdirectory was
created with the 32-bit DOS (DOS4G/W) target of the Watcom compiler, but
a different (free) DOS extender was used instead of the huge DOS4GW.EXE
extender that Watcom includes with their compiler. Instead of that,
PMODE/W 1.23 has been used. 


8. Documentation
----------------

The manual pages for RCS and RCSFRONT programs and additional documents
are available in the "doc" subdirectory in two formats: as plain ASCII
files for reading with any file browser or editor and in PostScript (TM)
format for printing on a PostScript printer or viewing/printing with
GhostScript or GSView. They were all created with the OS/2 version of
the GNU groff text formatter from the "source" documents also included
in this package (in the "rcs\man" and "rcsfront" subdirectories).

The documentation for GNU diff and diff3, version 2.7.1, is available
as a TeXinfo source file in the "diff" subdirectory. A preformatted
version in GNU Info format is in the "doc" subdirectory for reading
with either the GNU Emacs editor or the standalone GNU info browser,
but it can also be viewed with any normal file browser. A PostScript
version of it, made with emTeX and dvips, is also in the "doc"
subdirectory.

If you are not yet familiar with RCS and/or GNU diff, please read this
documentation files very carefully. I repeat, read them and read them
entirely and carefully before starting to use these tools. OK?


9. Problems
-----------

Please read this file carefully. If you have problems using RCS, please
first check it again to see if you forgot something and also check the
RCS documentation in the "doc" subdirectory.

If that doesn't help, send a short and descriptive e-mail
message. Don't laugh, you don't know how often I get e-mail with
contents like "the foobar program you ported to OS/2 does not work,
what should I do?" without any more details. Remember that I can't
read your mind, especially not over such distances. :-)


10. Author / Address
--------------------

Walter F. Tichy wrote the original version of RCS.
Paul Eggert wrote the changes for RCS version 5.x, and maintains it.

This port of RCS 5.7 to MS-DOS and OS/2 is based on an earlier
release (RCS 5.6.3) made by Paul Eggert, Frank Whaley and Kai Uwe
Rommel.

The DOS and OS/2 related changes for 5.7, for the DOS, Windows 95/NT
and OS/2 32-bit targets, the networking support and the ports of 
RCSFRONT, GNU diff 1.15 and 2.7.1 were made by Kai Uwe Rommel.


/* Kai Uwe Rommel      ARS Computer & Consulting GmbH, Muenchen, Germany *
 * rommel@ars.de             CompuServe 100265,2651, Fax +49 89 324 4524 *
 * rommel@leo.org (ftp.leo.org:/pub/comp/os/os2 maintenance)             */
