1 files changed, 292 insertions, 0 deletions
diff --git a/gnu/usr.bin/rcs/rcs/rcsintro.1 b/gnu/usr.bin/rcs/rcs/rcsintro.1
new file mode 100644
index 0000000..a76caa0
--- /dev/null
+++ b/gnu/usr.bin/rcs/rcs/rcsintro.1
@@ -0,0 +1,292 @@
+.de Id
+.ds Rv \\$3
+.ds Dt \\$4
+..
+.Id $Id: rcsintro.1,v 5.1 1991/04/21 12:00:46 eggert Exp $
+.ds r \&\s-1RCS\s0
+.if n .ds - \%--
+.if t .ds - \(em
+.am SS
+.LP
+..
+.TH RCSINTRO 1 \*(Dt GNU
+.SH NAME
+rcsintro \- introduction to RCS commands
+.SH DESCRIPTION
+The Revision Control System (\*r) manages multiple revisions of files.
+\*r automates the storing, retrieval, logging, identification, and merging
+of revisions.  \*r is useful for text that is revised frequently, for example
+programs, documentation, graphics, papers, and form letters.
+.PP
+The basic user interface is extremely simple.  The novice only needs
+to learn two commands:
+.BR ci (1)
+and
+.BR co (1).
+.BR ci ,
+short for \*(lqcheck in\*(rq, deposits the contents of a
+file into an archival file called an \*r file.  An \*r file
+contains all revisions of a particular file.
+.BR co ,
+short for \*(lqcheck out\*(rq, retrieves revisions from an \*r file.
+.SS "Functions of \*r"
+.IP \(bu
+Store and retrieve multiple revisions of text.  \*r saves all old
+revisions in a space efficient way.
+Changes no longer destroy the original, because the
+previous revisions remain accessible.  Revisions can be retrieved according to
+ranges of revision numbers, symbolic names, dates, authors, and
+states.
+.IP \(bu
+Maintain a complete history of changes.
+\*r logs all changes automatically.
+Besides the text of each revision, \*r stores the author, the date and time of
+check-in, and a log message summarizing the change.
+The logging makes it easy to find out
+what happened to a module, without having to compare
+source listings or having to track down colleagues.
+.IP \(bu
+Resolve access conflicts.  When two or more programmers wish to
+modify the same revision, \*r alerts the programmers and prevents one
+modification from corrupting the other.
+.IP \(bu
+Maintain a tree of revisions.  \*r can maintain separate lines of development
+for each module.  It stores a tree structure that represents the
+ancestral relationships among revisions.
+.IP \(bu
+Merge revisions and resolve conflicts.
+Two separate lines of development of a module can be coalesced by merging.
+If the revisions to be merged affect the same sections of code, \*r alerts the
+user about the overlapping changes.
+.IP \(bu
+Control releases and configurations.
+Revisions can be assigned symbolic names
+and marked as released, stable, experimental, etc.
+With these facilities, configurations of modules can be
+described simply and directly.
+.IP \(bu
+Automatically identify each revision with name, revision number,
+creation time, author, etc.
+The identification is like a stamp that can be embedded at an appropriate place
+in the text of a revision.
+The identification makes it simple to determine which
+revisions of which modules make up a given configuration.
+.IP \(bu
+Minimize secondary storage.  \*r needs little extra space for
+the revisions (only the differences).  If intermediate revisions are
+deleted, the corresponding deltas are compressed accordingly.
+.SS "Getting Started with \*r"
+Suppose you have a file
+.B f.c
+that you wish to put under control of \*r.
+If you have not already done so, make an \*r directory with the command
+.IP
+.B "mkdir  RCS"
+.LP
+Then invoke the check-in command
+.IP
+.B "ci  f.c"
+.LP
+This command creates an \*r file in the
+.B RCS
+directory,
+stores
+.B f.c
+into it as revision 1.1, and
+deletes
+.BR f.c .
+It also asks you for a description.  The description
+should be a synopsis of the contents of the file.  All later check-in
+commands will ask you for a log entry, which should summarize the
+changes that you made.
+.PP
+Files in the \*r directory are called \*r files;
+the others are called working files.
+To get back the working file
+.B f.c
+in the previous example, use the check-out
+command
+.IP
+.B "co  f.c"
+.LP
+This command extracts the latest revision from the \*r file
+and writes
+it into
+.BR f.c .
+If you want to edit
+.BR f.c ,
+you must lock it as you check it out with the command
+.IP
+.B "co  \-l  f.c"
+.LP
+You can now edit
+.BR f.c .
+.PP
+Suppose after some editing you want to know what changes that you have made.
+The command
+.IP
+.B "rcsdiff  f.c"
+.LP
+tells you the difference between the most recently checked-in version
+and the working file.
+You can check the file back in by invoking
+.IP
+.B "ci  f.c"
+.LP
+This increments the revision number properly.
+.PP
+If
+.B ci
+complains with the message
+.IP
+.BI "ci error: no lock set by " "your name"
+.LP
+then you have tried to check in a file even though you did not
+lock it when you checked it out.
+Of course, it is too late now to do the check-out with locking, because
+another check-out would
+overwrite your modifications.  Instead, invoke
+.IP
+.B "rcs  \-l  f.c"
+.LP
+This command will lock the latest revision for you, unless somebody
+else got ahead of you already.  In this case, you'll have to negotiate with
+that person.
+.PP
+Locking assures that you, and only you, can check in the next update, and
+avoids nasty problems if several people work on the same file.
+Even if a revision is locked, it can still be checked out for
+reading, compiling, etc.  All that locking
+prevents is a
+.I "check-in"
+by anybody but the locker.
+.PP
+If your \*r file is private, i.e., if you are the only person who is going
+to deposit revisions into it, strict locking is not needed and you
+can turn it off.
+If strict locking is turned off,
+the owner of the \*r file need not have a lock for check-in; all others
+still do.  Turning strict locking off and on is done with the commands
+.IP
+.BR "rcs  \-U  f.c" "     and     " "rcs  \-L  f.c"
+.LP
+If you don't want to clutter your working directory with \*r files, create
+a subdirectory called
+.B RCS
+in your working directory, and move all your \*r
+files there.  \*r commands will look first into that directory to find
+needed files.  All the commands discussed above will still work, without any
+modification.
+(Actually, pairs of \*r and working files can be specified in three ways:
+(a) both are given, (b) only the working file is given, (c) only the
+\*r file is given.  Both \*r and working files may have arbitrary path prefixes;
+\*r commands pair them up intelligently.)
+.PP
+To avoid the deletion of the working file during check-in (in case you want to
+continue editing or compiling), invoke
+.IP
+.BR "ci  \-l  f.c" "     or     " "ci  \-u  f.c"
+.LP
+These commands check in
+.B f.c
+as usual, but perform an implicit
+check-out.  The first form also locks the checked in revision, the second one
+doesn't.  Thus, these options save you one check-out operation.
+The first form is useful if you want to continue editing,
+the second one if you just want to read the file.
+Both update the identification markers in your working file (see below).
+.PP
+You can give
+.B ci
+the number you want assigned to a checked in
+revision.  Assume all your revisions were numbered 1.1, 1.2, 1.3, etc.,
+and you would like to start release 2.
+The command
+.IP
+.BR "ci  \-r2  f.c" "     or     " "ci  \-r2.1  f.c"
+.LP
+assigns the number 2.1 to the new revision.
+From then on,
+.B ci
+will number the subsequent revisions
+with 2.2, 2.3, etc.  The corresponding
+.B co
+commands
+.IP
+.BR "co  \-r2  f.c" "     and     " "co  \-r2.1  f.c"
+.PP
+retrieve the latest revision numbered
+.RI 2. x
+and the revision 2.1,
+respectively.
+.B co
+without a revision number selects
+the latest revision on the
+.IR trunk ,
+i.e. the highest
+revision with a number consisting of two fields.  Numbers with more than two
+fields are needed for branches.
+For example, to start a branch at revision 1.3, invoke
+.IP
+.B "ci  \-r1.3.1  f.c"
+.LP
+This command starts a branch numbered 1 at revision 1.3, and assigns
+the number 1.3.1.1 to the new revision.  For more information about
+branches, see
+.BR rcsfile (5).
+.SS "Automatic Identification"
+\*r can put special strings for identification into your source and object
+code.  To obtain such identification, place the marker
+.IP
+.B "$\&Id$"
+.LP
+into your text, for instance inside a comment.
+\*r will replace this marker with a string of the form
+.IP
+.BI $\&Id: "  filename  revision  date  time  author  state  " $
+.LP
+With such a marker on the first page of each module, you can
+always see with which revision you are working.
+\*r keeps the markers up to date automatically.
+To propagate the markers into your object code, simply put
+them into literal character strings.  In C, this is done as follows:
+.IP
+.ft 3
+static char rcsid[] = \&"$\&Id$\&";
+.ft
+.LP
+The command
+.B ident
+extracts such markers from any file, even object code
+and dumps.
+Thus,
+.B ident
+lets you find out
+which revisions of which modules were used in a given program.
+.PP
+You may also find it useful to put the marker
+.B $\&Log$
+into your text, inside a comment.  This marker accumulates
+the log messages that are requested during check-in.
+Thus, you can maintain the complete history of your file directly inside it.
+There are several additional identification markers; see
+.BR co (1)
+for
+details.
+.SH IDENTIFICATION
+Author: Walter F. Tichy.
+.br
+Revision Number: \*(Rv; Release Date: \*(Dt.
+.br
+Copyright \(co 1982, 1988, 1989 by Walter F. Tichy.
+.br
+Copyright \(co 1990, 1991 by Paul Eggert.
+.SH "SEE ALSO"
+ci(1), co(1), ident(1), rcs(1), rcsdiff(1), rcsintro(1), rcsmerge(1), rlog(1)
+.br
+Walter F. Tichy,
+\*r\*-A System for Version Control,
+.I "Software\*-Practice & Experience"
+.BR 15 ,
+7 (July 1985), 637-654.
+.br