			     INTRODUCTION

Note: 

"main" refers to the file stem ("base" file).

"branch" refers to a branch for a user from the main stem.

"variation" refers to a sub-branch for the user from the user branch.

"item" refers to "main", a "branch", or a "variation", and is a number.

"revision" means an "item" plus the tip, completely specifying a full
revision number.

rcs-dwr.el provides a convenient interface to rcs that allows a user
to easily check out, check in, and log changes to files that are
edited.  Having a file checked in means that it is read-only.  A user
can not unintentionally edit a file that is checked in.  Having a file
checked out means that it is writable and locked by the current user.
The current user can edit and save the file; other users can not
access or edit the file revision of the current user.  Other users can
access their own revisions of the file, and all users that are
accessing the same file (different revisions, of course) appear in the
mode-line.

rcs-dwr.el uses emerge.el which allows user-guided merges of different
branches or sub-branches of an RCS file.

This version of rcs-dwr.el works only with version 5.5 or later of
RCS.
				   
			 HISTORY AND CONCEPT

There are quite a number of rcs.el programs available.  rcs-dwr.el was
derived from what we thought was the best available rcs.el file at the
time: rcs-cks.el, from Chris Siebenmann (cks@white.toronto.edu).  The
Dept. of Water Resource extensions (multiple files, user branches,
user variations, updates and freezing, variation menu buffer, etc.)
were made for use by a small group of people who are editing common
files, and don't want to become rcs experts, but do want to maintain
their own versions of source files.  It came about as a result of our
own experience at the DWR when we had people moving from the PC world,
with no shared files, to the Unix world.  People wanted to exchange
updates to source files but didn't want to think too much about
version control systems.

As such, there should be an rcs system administrator who will set
things up for the more naive rcs users.  This document is addressed to
the rcs administrator; they can explain the emacs-rcs commands to the
other users.  It is assumed that all users are already familiar with
emacs, and that the rcs administrator is familiar with rcs.  This doc
assumes the above paradigm of numbers of users editing the same source
files, but certainly rcs-dwr.el can be used by single users.

				SETUP

The rcs administrator should look over and set the following variables
to their site's preference.  These can be found in the first section
of the rcs-dwr.el file.

rcs-diff-options
rcs-executable-path
rcs-edit-mode
rcs-make-backup-files
rcs-initial-branch
rcs-initial-rev
rcs-initial-access
rcs-keep-log
rcs-use-user-branch
rcs-clean-before-copy

Next, you will probably want to bind at least these keys:

(define-key global-map "\C-c\C-f" 'rcs-co-file)
(define-key global-map "\C-c\C-s" 'rcs-ci-buffer)
(define-key global-map "\C-ck" 'rcs-revert-buffer)

These allow users to easily checkout and checkin files in a very
similar manner to find-file and save-buffer, which they are already
familiar with.  Also they can easily kill changes made, once again
similar to the killing of a buffer.

Additionally, you might want to bind these:

(define-key global-map "\C-cd" 'rcs-diff-file)
(define-key global-map "\C-ci" 'rcs-interactive-variation-menu)
(define-key global-map "\C-x\C-f" 'rcs-find-file)

The latter binding takes some explaining.  It hacks the modeline so
that information about who has the file locked appears; but to do so
it must run rlog on the file, which takes a bit of time.  This could
be done using the find-file-hooks, but then when you do, e.g., tag
files, each file runs rlog, quite a lengthy process.  By using a
special find-file and rebinding C-x C-f, rlog is run only on single
files.

Enable strict locking in rcs, and make all source files non-writable.
Then whenever a user tries to edit a file that is read-only, they will
know they have to check it out.

Finally, with multiple users using the same source files, you will
want to set up your directories in the following manner.  Assume that
program A contains a main routine and some subroutines.

For program A, create a main directory and put the source code and RCS
subdirectory there; e.g. ..../main_A/A.c, ..../main_A/a1.c,
..../main_a/a2.c, etc., and ..../main_A/RCS/A.c,v, ..../main_A/RCS/a1.c,v
..../main_A/RCS/a2.c,v and so on.

But, don't edit those source codes!  Instead, for each user create
their own analog of the main directory structure: ..../user_A/A.c,
..../user_A/a1.c, etc.  However, instead of creating an RCS
subdirectory, link back to the real one:

 cd ..../user_A
 ln -s ..../main_A/RCS

This way there is just one copy of the ,v files, but user copies of
the source code.  The interface handles copying different user
versions around, as described below.


Once the setup is complete, users can try rcs commands from emacs.


		   PLACING A FILE UNDER RCS CONTROL

A file must be checked in the first time into rcs before it can be
checked out.

(1) Either do M-x rcs-ci-file, or from the file buffer do M-x
rcs-ci-buffer (C-c C-s if you've bound the keys as suggested).

(2) A buffer "*rcs log*" will appear, and the user will be prompted to
enter some "General descriptive text", and keys to press to complete
("exit-recursive-edit") or to abort ("abort-recursive-edit") the
check-in.

(3) Enter an appropriate message in the buffer and press the indicated
keys to complete.

(4) If all is successful, the mini-buffer will reply "Checkin
Complete".

		       CHECKING OUT AN RCS FILE

If rcs-co-file is bound to C-c C-f, then simply type C-c C-f, and the
name of the file to checkout.

If the user forgets that the file is in rcs, and gets it with C-x C-f,
they will not be able to edit it.  In that case they can type C-c C-f
and hit a return, and the file will be checked out.

Once checked out, the user can edit it as usual.  If
rcs-use-user-branch is t, then they will have their own branch, and
multiple users can checkout the same file simultaneously with no
conflicts, *if* the directories are setup as above.  Merging all these
changes is described below.

Sometimes when user branches are active, you will still want to check
out the main stem to a file.  Just use a prefix argument to
rcs-co-file and the main stem will be checked out (C-u C-c C-f).

		       CHECKING IN AN RCS FILE

Once a file has been checked in the first time, then checked out for
changes, it can be easily checked in again with rcs-ci-buffer.  As
stated above, we recommend binding C-c C-s to rcs-ci-buffer for ease
of use.  The user will be prompted for a log message, similar to the
initial checkin.  This time the message should reflect what changes
were made from the last checkin.  If rcs-ci-buffer is called with a
prefix arg (C-u), the file will be checked out again locked after the
checkin, to allow continued editting.

The checkout/checkin cycle can continue indefinitely.  Since it's easy
to do we recommend frequent checkins so as to be able to recover
previous changes easily.

			GETTING RID OF CHANGES

If a user has checked out a file, made changes, then decided they
don't want to keep the changes, they can start over with
rcs-revert-buffer.  If this is bound to, say, C-c k, then it's quite
easy to get rid of changes and return the checked-out file to its
previous state.  If rcs-revert-buffer is called with no prefix
argument, it will end up unlocked (checked in with no changes).  If a
prefix argument is given, the changes will be removed but the file
will remain locked (checked out with no changes yet).
rcs-ci-{buffer,file} will query the user if the buffer or file has
changed before removing the changes.

			   USER VARIATIONS

More sophisticated users will not want to be limited to just one
branch for themselves.  Often a user will want to edit multiple
versions of the same file, and merge them later.  To start up multiple
versions of a file, type M-x rcs-make-user-variation, then enter a
filename and a variation name.  Variations should be created in
different subdirectories, otherwise the working files will overwrite
each other.  The different subdirectories should be set up for each
variation in a manner similar to the user branch directories created
for each user.

		      CHECKING IN MULTIPLE FILES

It is common to checkout a lot of files in a directory, change just
some of them, then want to check them in with a common log message.
This is easy with the M-x rcs-ci-checked-out command.  It will ask
whether to use the first log message for all checkins in the directory
or prompt for a new log message for each file.  Files that are checked
out, but not changed, will not be checked in, but rather just unlocked.
				   
		    DIFFING VERSIONS AND BRANCHES

Sometimes before merging files the user will want to see just what is
different between two versions, or perhaps they've made changes some
time ago and want to see what the differences are now between their
last checkin and the current working file.  Comparisons of versions
and branches can be made in two basic ways:

(A) diffing using M-x rcs-diff-file results in a diff from the current
file against the previously checked in version of that file.  This is
used to compare changes made to a checked out file against the last
checked in version.  If the file is not locked, the two previous
versions are diffed.

(B) Diffing from the variation menu comes in two commands:

d -- Show places where selected item is different from the previous
checked in revision, or diffs last two versions, depending if the item
is locked or unlocked.

D -- User is prompted for both items that will be used to find
differences.  Use this one to compare between two users, or two
variations by the same user.

			VARIATION MENU BUFFER

A menu is available to access the above commands as well as others.
The menu will appear automatically when needed, or may be called at
any time with M-x rcs-interactive-variation-menu.  The help message
for the mode appears below:

Variation Menu Mode:
Major mode for editing and merging a list of RCS items.
Each line describes one of the RCS item in a file.
Letters do not insert themselves; instead, they are commands.

VARIATION MENU COMMANDS:
t -- Toggle variable that adds all file items in the variation menu.
     With prefix arg, toggle freeze symbols.
g -- Refresh Variation menu.
q -- Kill Variation menu.
? -- This HELP MENU.
, -- Next file (if in file loop).
SPC -- Move down a line.
Delete -- Back up a line.

BASIC CHECK IN AND CHECK OUT OF RCS ITEMS:
o -- Check out the item that is on the same line as the cursor.
i -- Check in the item that is on the same line as the cursor.
NOTE: * before an item indicates that item is locked.

AUXILIARY RCS COMMANDS:
m -- Make a variation.  Note: Check in all versions of the file before
     attempting to make a variation, otherwise it will abort.
c -- Copy rcs item to another rcs item.
d -- (1) If item is checked out (i.e. locked), then diff the working
         file against the last checked in version.
     (2) If item is not checked out, then diff the two most recent
         versions.
D -- User is prompted for both items that will be used to find differences.
f -- Change the filename in the variation buffer menu.
l -- Show RCS log file.
r -- Remove the item's symbolic name but do not delete ('outdate') it
     from the RCS file.
k -- Delete the tip (latest revision) of the item from the RCS file
     ('outdate' it) and remove its symbol, if the tip is the only revision
     remaining.
v -- Revert the buffer of the checked out file, i.e. nuke all changes
     made to the file and call up the most recent checked in version locked.
u -- Update first item with respect to another item (copy item2 to item1
     if item1 out-of-date wrt item2).  If given prefix arg (C-u), use emerge
     instead of copy.  Intended for multiple files.
z -- Freeze an rcs item.  Create a symbol with a freeze name set to the
     latest revision of the rcs item.  Intended for multiple files.

MERGING TWO ITEMS IN A COMMON FILE:
a -- Select item a for merge.
wa -- Select item a for merge with an ancestor item.

The freeze and update commands, while they can be done on single
files, are really meant for use with multiple files.  The freeze
command sets an RCS symbol to a full revision number for each file;
the revision number is calculated for each file differently, using the
tip (latest revision) for the item selected for each file.  So, for
instance, if you set the freeze symbol to "Rev_1a" for "main", it
might be set to "1.2" for file1, "1.4" for file2, and so on.

Update compares two items and decides if the first item is out-of-date
with respect to the second item, i.e. older than the second.  If so,
it either copies the second item to the first, or allows the user to
merge them by hand.

			  MULTIPLE FILE COMMANDS

Almost all rcs-dwr commands can be done automatically on multiple
files with the rcs-do-many command.  This first prompts for the method
of generating the file names: either tag files or RCS files in a
directory.  Then it puts the user in a Variation Menu Buffer (see
below), where they select the command they want.  Then the command is
performed on the files.

If you want to check in a series of files into RCS for the first time,
use tag files.

			   MERGING BRANCHES

After a number of branches and versions have been created by users,
they will want to merge them together.  We use the emerge.el package
to assist in this, written by Dale Worley, drw@math.mit.edu.  See the
documentation for that package for a complete description of the merge
commands.

After exiting the merge routine, the use is asked if they wish to save
the merged buffer back onto an RCS item.  The merges are saved in a
temporary file regardless.
   
			     BUG REPORTS

Please report any bugs found to rfinch@water.ca.gov.
