New release from Cyclic Software

2 files changed, 530 insertions, 156 deletions

diff --git a/gnu/usr.bin/cvs/doc/ChangeLog b/gnu/usr.bin/cvs/doc/ChangeLog
index b97c695c86c..4cfcb234b48 100644
--- a/gnu/usr.bin/cvs/doc/ChangeLog
+++ b/gnu/usr.bin/cvs/doc/ChangeLog
@@ -1,3 +1,300 @@
+Mon Jan 13 15:41:02 1997  Karl Fogel  <kfogel@ynu38.ynu.edu.cn>
+
+	* cvs.texinfo (Read-only access): rephrase to imply that there may
+        be other administrative files, besides history and locks, which
+        read-only users can also affect (in the future, for example, the
+        `passwd' file).
+
+Wed Jan  8 14:50:47 1997  Jim Kingdon  <kingdon@harvey.cyclic.com>
+
+	* Makefile.in: Remove CVSid; we decided to get rid
+	of these some time ago.
+
+Wed Jan  8 09:08:36 1997  Jim Kingdon  <kingdon@harvey.cyclic.com>
+
+	* cvsclient.texi (Connection and Authentication): Document
+	restriction that cvs root sent in the cvs protocol and in the
+	pserver authentication protocol must be identical.
+
+Thu Jan  2 13:30:56 1997  Jim Kingdon  <kingdon@harvey.cyclic.com>
+
+	* Makefile.in, cvs.texinfo: Remove "675" paragraph;
+	see ../ChangeLog for rationale.
+
+Thu Jan  2 09:34:51 1997  Karl Fogel  <kfogel@ynu38.ynu.edu.cn>
+
+        * cvs.texinfo (Read-only access): new node.
+        (Repository): new menu item for above new node.
+        (Password authentication server): document the user-aliasing
+        feature.  Why was this undocumented before?
+
+Wed Jan  1 18:12:11 1997  Jim Kingdon  <kingdon@harvey.cyclic.com>
+
+	* cvs.texinfo (Conflicts example): Use @asis in example to prevent
+	starting a line with a conflict marker.  This means that when
+	maintaining the file with CVS itself, CVS will not think there is
+	a conflict merely because of the conflict marker in the example.
+	IMHO, this is totally bogus and CVS needs a better way of figuring
+	out whether a conflict is resolved (see comments elsewhere in this
+	node), but until then....  Credit to Fred Fish for reporting the
+	problem.
+
+	* cvs.texinfo (cvsignore): Add paragraph about how .cvsignore
+	files in the sources being imported by "cvs import" override
+	"-I !".  Credit goes to Fred Fish for pointing out this problem.
+
+Thu Dec 19 12:36:46 1996  Jim Kingdon  <kingdon@harvey.cyclic.com>
+
+	* cvs.texinfo (Credits): Update Roland Pesch email address per his
+	request.
+
+Tue Dec 17 12:57:56 1996  Jim Kingdon  <kingdon@harvey.cyclic.com>
+
+	* cvs.texinfo (verifymsg): In example, remove text "and reedit if
+	necessary"; it was copied from editinfo and doesn't apply here.
+	Fix syntax of if statement; remove unnecessary attempt at loop;
+	don't use -n with echo.  Add @appendixsec at start of node.
+	Add note about how verifymsg cannot change log message.
+	(editinfo): In paragraph saying editinfo is obsolete, fix various
+	typos and formatting glitches.  Mention -e as well as EDITOR.
+	(editinfo): In saying that editinfo doesn't get consulted with -m,
+	-F or client/server, recommend verifymsg.  Remove comment which
+	says, in effect, "we need a feature like verifymsg".
+	(editinfo example): Change "verifymsg" back to "editinfo" here;
+	the example is of editinfo not verifymsg.
+
+Tue Dec 17 12:45:32 1996  Abe Feldman  <feldman@cyclic.com>
+
+	* cvs.texinfo (verifymsg): New node.
+	various places: Say that editinfo is obsolete, or refer to
+	verifymsg instead of editinfo
+
+Wed Dec 11 08:55:26 1996  Jim Kingdon  <kingdon@harvey.cyclic.com>
+
+	* cvs.texinfo (Compatibility): Add comment about 1.3 and file death.
+
+	* cvs.texinfo (update output, release output): Document "P" as
+	well as "U".
+
+Tue Dec 10 16:23:40 1996  Jim Kingdon  <kingdon@harvey.cyclic.com>
+
+	* cvs.texinfo (Builds): Change "make" to "implement" and "build";
+	in this context "make" is ambiguous.
+	(Builds): Add new URL of mk web page.
+
+Mon Dec  9 11:03:37 1996  Jim Blandy  <jimb@floss.cyclic.com>
+
+	* cvs.texinfo (Password authentication client, Environment
+	variables): Remove mention of CVS_PASSWORD.
+
+Sun Dec  8 22:38:34 1996  Jim Kingdon  <kingdon@harvey.cyclic.com>
+
+	* cvs.texinfo (Repository files): Mention differences between RCS
+	files in RCS and in CVS.
+	(Tags): Tag names must start with a letter.
+
+Fri Dec  6 09:08:18 1996  Jim Kingdon  <kingdon@harvey.cyclic.com>
+
+	* cvs.texinfo (syntax): Expand discussion of regular expression
+	syntax.
+
+Fri Nov 29 09:06:41 1996  fnf@ninemoons.com (Fred Fish)
+			  and Jim Kingdon  <kingdon@harvey.cyclic.com>
+
+	* cvs.texinfo, cvsclient.texi: Make sure @ref and friends are
+	followed by "," or "." as described in the texinfo manual.  This
+	is a dubious practice as texi2html and texinfo.tex don't require
+	it, and makeinfo could insert them as needed, but since makeinfo
+	doesn't do that yet, cope.
+
+	* cvs.texinfo (From files): Suggest "diff -r" rather than "ls -R"
+	as the way to see that the sources seem to have been imported
+	correctly.
+	(Common options): -k is also available with import.
+	(admin options): Fix typo ("interrested" -> "interested").
+
+Mon Nov 25 10:03:56 1996  Jim Kingdon  <kingdon@harvey.cyclic.com>
+
+	* cvs.texinfo (Common options): Add comments about two digit
+	years, year 2000, and ambiguous/nonexistent dates.
+
+Sun Nov 24 17:27:24 1996  Jim Kingdon  <kingdon@harvey.cyclic.com>
+
+	* cvs.texinfo (First import): Don't say what the wdiff program we
+	are using as an example does--that is confusing.  Also don't show
+	untarring it--people might be familiar with cpio, ZIP, VMS BACKUP,
+	etc., instead of tar.
+
+	* cvs.texinfo (Adding files): Update comment about "cvs add -m".
+
+	* cvs.texinfo (Common options): Remove -H; -H is not a command
+	option.
+	(Global options): Also list --help and --version.  Don't say that
+	-H gives a list of commands; it doesn't any more (directly).
+
+	* cvs.texinfo: Add comment pointing to paper size web page.
+
+	* cvs.texinfo (Common options): Rewrite section on date formats.
+	Executive summary is that RFC822 and ISO8601 are now preferred.
+
+Wed Nov 20 08:39:45 1996  Jim Kingdon  <kingdon@harvey.cyclic.com>
+
+	* cvs.texinfo (Getting Notified): Add paragraph clarifying that
+	watches happen per user, not per working directory.
+
+Tue Nov 19 09:39:08 1996  Jim Kingdon  <kingdon@harvey.cyclic.com>
+
+	* cvs.texinfo (Tags): Suggest that future special tag names might
+	start with ".".  Fix typo.
+
+	* cvs.texinfo (Removing directories): -P is also available with
+	export.
+	(Moving directories): Rewrite first paragraph; now says that you
+	must use -P for the directory to disappear from working
+	directories.  Thanks to Martin Lorentzon
+	<Martin.Lorentzson@emw.ericsson.se> for reporting this bug.
+	(various): Where we mention -P, point to Removing directories
+	node.
+
+Sat Nov 16 18:03:22 1996  Jim Kingdon  <kingdon@harvey.cyclic.com>
+
+	* cvsclient.texi (Example): Rewrite to actually be based on a real
+	live example (and therefore reflect the way the protocol currently
+	works).  Add comment about formatting of the document itself.
+
+Thu Nov 14 10:22:58 1996  Jim Kingdon  <kingdon@harvey.cyclic.com>
+
+	* cvsclient.texi (Introduction): Use @ref, not @xref, after "see".
+	(Goals): Rewrite items about locking, about uploading in big
+	chunks, and about atomicity to be focused more on the protocol
+	than the current implementation.
+	(Notes): Remove this node.  The attempt to describe the basic
+	model has pretty much been replaced by the Introduction.  
+	The material about how to start the client is incomplete and
+	better left to cvs.texinfo.  And the item about the lack of
+	SERVER_FLOWCONTROL is obsolete now that SERVER_FLOWCONTROL is the
+	default.
+	(Protocol Notes): Add comment about multisite features.
+	(Requirements): Use @code for requests and responses.
+
+	* cvs.texinfo (Remote repositories): Add a few sentences defining
+	"client" and "server"; before we had been using the terms without
+	defining them.
+
+	* cvs.texinfo (What is CVS?): Add paragraph about reporting bugs.
+	Reword and expand comp.software.config-mgmt description (and add
+	comments about other newsgroup facts).  Point people at GNU list
+	of FTP sites rather than directly at prep.ai.mit.edu.
+
+Wed Nov  6 09:45:08 1996  Jim Kingdon  <kingdon@harvey.cyclic.com>
+
+	* cvs.texinfo (Tracking sources): Add comment regarding added and
+	removed files.
+
+Tue Nov  5 14:00:31 1996  Jim Kingdon  <kingdon@harvey.cyclic.com>
+
+	* cvs.texinfo: Rename node "Invoking CVS" to "CVS commands".
+	Rewrite the intro and comments to reflect addition of the new
+	Invoking CVS.
+	(Invoking CVS): New node, a quick summary of each command.
+	(annotate): Don't list the options; refer to Invoking CVS and
+	Common options instead.
+
+Sun Nov  3 21:22:42 1996  Jim Kingdon  <kingdon@harvey.cyclic.com>
+
+	* cvs.texinfo (Compatibility): New node, moved from ../README.
+
+	* cvs.texinfo (Common options): Add comment about how tar manual
+	contains documentation for getdate date formats.
+
+Fri Nov  1 14:00:31 1996  Jim Kingdon  <kingdon@harvey.cyclic.com>
+
+	* cvs.texinfo (commit examples): Rewrite "New major release
+	number" section to tighten up the wording, better motivate the
+	discussion, and replace the term "rcs revision number" with
+	"numeric revision".
+
+Fri Oct 25 07:49:21 1996  Jim Kingdon  <kingdon@harvey.cyclic.com>
+
+	* cvs.texinfo (loginfo): Don't say "a la printf"; the syntax is
+	only vaguely similar to printf.
+
+	* cvs.texinfo (loginfo): To get just the repository name, suggest
+	%{} instead of % "standing alone"; the latter is now an error.
+
+Tue Oct 22 13:08:54 1996  Noel Cragg  <noel@gargle.rain.org>
+
+	* cvs.texinfo (loginfo): add information on the new loginfo format
+ 	string specification.
+
+Mon Oct 21 17:33:44 1996  Jim Kingdon  <kingdon@harvey.cyclic.com>
+
+	* cvs.texinfo (Builds): New node.
+	(What is CVS?): Refer to it.
+
+Sat Oct 19 14:32:21 1996  Jim Meyering <meyering@asic.sc.ti.com>
+			  and Jim Kingdon  <kingdon@harvey.cyclic.com>
+
+	* cvs.texinfo (Choosing a model): Wording/grammar fix.
+
+Sat Oct 19 14:32:21 1996  Jim Kingdon  <kingdon@harvey.cyclic.com>
+
+	* cvsclient.texi (Obsolete): New node.
+	(Requests): Remove Repository and Lost and adjust Directory,
+	UseUnchanged, and other places accordingly.
+	(Required): Directory and Unchanged are now required.
+
+	* cvs.texinfo (Removing files): Don't talk about modules; they are
+	not relevant in this context.
+	(Removing directories): New node.
+	(Common options): Refer to it instead of duplicating information.
+
+Fri Oct 18 11:05:06 1996  Jim Kingdon  <kingdon@harvey.cyclic.com>
+
+	* cvs.texinfo (First import, import): Add paragraph about the fact
+	that import doesn't modify the directory which it imports from.
+
+	* cvs.texinfo (Creating a repository): Add paragraph about
+	resource requirements.
+
+	* cvs.texinfo (Copying): Replace empty node with a copy of the GPL.
+
+Thu Oct 17 12:10:55 1996  Jim Kingdon  <kingdon@harvey.cyclic.com>
+
+	* cvs.texinfo (Adding files): Revise comment to more accurately
+	reflect the functioning/nonfunctioning status of cvs add -m.
+
+	* cvs.texinfo (Reverting local changes): New node, somewhat based
+	on the version of this node from 30 Sep 96 change.
+	(admin options): Refer to it.
+
+	* cvs.texinfo: Reinstate 30 Sep 96 change from A4 to US letter.
+
+	* cvs.texinfo (Concurrency): When telling people how to clean up
+	locks, tell them to make sure the locks are owned by the person
+	who has the stale locks.
+	(update output, release output): Remove text about how CVS doesn't
+	print "? foo" for directories; CVS has since been changed (see
+	conflicts-130 in sanity.sh).
+
+Wed Oct 16 15:01:42 1996  Jim Kingdon  <kingdon@harvey.cyclic.com>
+
+	* cvs.texinfo (history options): Mention new option -x E.
+
+Mon Oct 14 15:21:25 1996  Jim Kingdon  <kingdon@harvey.cyclic.com>
+
+	* cvs.texinfo (Tags): Add paragraph on choosing a convention for
+	naming tags.
+
+Thu Oct 10 16:05:26 1996  Jim Kingdon  <kingdon@harvey.cyclic.com>
+
+	* cvs.texinfo (modules): Describe what & does.
+
+Mon Oct  7 17:20:11 1996  Ian Lance Taylor  <ian@cygnus.com>
+
+	* cvs.texinfo (Removing files): Correct apparent cut and paste
+	error: refer to the removed file, not the added file.
+
 Tue Oct  1 14:15:33 1996  Jim Kingdon  <kingdon@harvey.cyclic.com>
 
 	* cvs.texinfo: Revert all recent changes (the last unscathed one
diff --git a/gnu/usr.bin/cvs/doc/cvsclient.texi b/gnu/usr.bin/cvs/doc/cvsclient.texi
index cb4ad2cd207..7420014b4db 100644
--- a/gnu/usr.bin/cvs/doc/cvsclient.texi
+++ b/gnu/usr.bin/cvs/doc/cvsclient.texi
@@ -9,13 +9,12 @@
 This document describes the client/server protocol used by CVS.  It does
 not describe how to use or administer client/server CVS; see the regular
 CVS manual for that.  This is version @value{CVSVN} of the protocol
-specification---@xref{Introduction} for more on what this version number
+specification---@xref{Introduction}, for more on what this version number
 means.
 
 @menu
 * Introduction::      What is CVS and what is the client/server protocol for?
 * Goals::             Basic design decisions, requirements, scope, etc.
-* Notes::             Notes on the current implementation
 * Protocol Notes::    Possible enhancements, limitations, etc. of the protocol
 * Connection and Authentication::  Various ways to connect to the server
 * Protocol::          Complete description of the protocol
@@ -60,7 +59,7 @@ versions of this specification.  Although the specification is currently
 maintained in conjunction with the CVS implementation, and carries the
 same version number, it also intends to document what is involved with
 interoperating with other implementations (such as other versions of
-CVS); see @xref{Requirements}.  This version number should not be used
+CVS); see @ref{Requirements}.  This version number should not be used
 by clients or servers to determine what variant of the protocol to
 speak; they should instead use the @code{valid-requests} and
 @code{Valid-responses} mechanism (@pxref{Protocol}), which is more
@@ -83,46 +82,29 @@ Security and authentication are handled outside this protocol (but see
 below about @samp{cvs kserver} and @samp{cvs pserver}).
 
 @item
-This might be a first step towards adding transactions to CVS (i.e. a
-set of operations is either executed atomically or none of them is
-executed), improving the locking, or other features.  The current server
-implementation is a long way from being able to do any of these
-things.  The protocol, however, is not known to contain any defects
-which would preclude them.
+The protocol makes it possible for updates to be atomic with respect to
+checkins; that is if someone commits changes to several files in one cvs
+command, then an update by someone else would either get all the
+changes, or none of them.  The current @sc{cvs} server can't do this,
+but that isn't the protocol's fault.
 
 @item
-The server never has to have any CVS locks in place while it is waiting
-for communication with the client.  This makes things robust in the face
-of flaky networks.
-
-@item
-Data is transferred in large chunks, which is necessary for good
-performance.  In fact, currently the client uploads all the data
-(without waiting for server responses), and then waits for one server
-response (which consists of a massive download of all the data).  There
-may be cases in which it is better to have a richer interraction, but
-the need for the server to release all locks whenever it waits for the
-client makes it complicated.
+The protocol is, with a few exceptions, transaction-based.  That is, the
+client sends all its requests (without waiting for server responses),
+and then waits for the server to send back all responses (without
+waiting for further client requests).  This has the advantage of
+minimizing network turnarounds and the disadvantage of sometimes
+transferring more data than would be necessary if there were a richer
+interaction.  Another, more subtle, advantage is that there is no need
+for the protocol to provide locking for features such as making checkins
+atomic with respect to updates.  Any such locking can be handled
+entirely by the server.  A good server implementation (such as the
+current @sc{cvs} server) will make sure that it does not have any such
+locks in place whenever it is waiting for communication with the client;
+this prevents one client on a slow or flaky network from interfering
+with the work of others.
 @end itemize
 
-@node Notes
-@chapter Notes on the Current Implementation
-
-The client is built in to the normal @code{cvs} program, triggered by a
-specially-formatted @code{CVSROOT} variable, for example
-@code{:server:cygnus.com:/rel/cvsfiles}.
-
-The client stores what is stored in checked-out directories (including
-@file{CVS}).  The way these are stored is totally compatible with
-standard CVS.  The server requires no storage other than the repository,
-which also is totally compatible with standard CVS.
-
-The current server implementation can use up huge amounts of memory
-when transmitting a lot of data over a slow link (i.e. the network is
-slower than the server can generate the data).  There is some
-experimental code (see @code{SERVER_FLOWCONTROL} in options.h) which
-should help significantly.
-
 @node Protocol Notes
 @chapter Notes on the Protocol
 
@@ -137,6 +119,10 @@ of "cvs edit" in this case is the most sensible course (the "cvs edit"
 could be handled by a package like VC for emacs).  This would also allow
 local operation of @code{cvs diff} without arguments.
 
+@c It isn't clear exactly how this should relate to a more general
+@c multisite feature (in which one can modify the local copy even if the
+@c network is down between the local and the master, and then they get
+@c reconciled by a potentially manual process).
 @item
 Have the client keep a copy of some part of the repository.  This allows
 all of @code{cvs diff} and large parts of @code{cvs update} and
@@ -191,7 +177,11 @@ implementation, by having inetd call "cvs pserver") which defaults to
 connects, sends the string @samp{BEGIN AUTH REQUEST}, a linefeed, the
 cvs root, a linefeed, the username, a linefeed, the password trivially
 encoded (see scramble.c in the cvs sources), a linefeed, the string
-@samp{END AUTH REQUEST}, and a linefeed.  The server responds with
+@samp{END AUTH REQUEST}, and a linefeed.  The client must sent the
+identical string for cvs root here, as it sends later, in the
+@code{Root} request of the cvs
+protocol itself.  Servers are encouraged to enforce this restriction.
+The server responds with
 @samp{I LOVE YOU} and a linefeed if the authentication is successful or
 @samp{I HATE YOU} and a linefeed if the authentication fails.  After
 receiving @samp{I LOVE YOU}, the client proceeds with the cvs protocol.
@@ -216,6 +206,7 @@ to a horizontal tab.
 * Responses::                   
 * Example::                     
 * Requirements::
+* Obsolete::                        Former protocol features
 @end menu
 
 @node Entries Lines
@@ -332,23 +323,19 @@ request-list is a space separated list of tokens.
 Response expected: yes.
 Ask the server to send back a @code{Valid-requests} response.
 
-@item Repository @var{repository} \n
-Response expected: no.  Tell the server what repository to use.  This
-should be a directory name from a previous server response.  Note that
-this both gives a default for @code{Entry } and @code{Modified } and
-also for @code{ci} and the other commands; normal usage is to send a
-@code{Repository } for each directory in which there will be an
-@code{Entry } or @code{Modified }, and then a final @code{Repository }
-for the original directory, then the command.
-
 @item Directory @var{local-directory} \n
 Additional data: @var{repository} \n.  Response expected: no.
-This is like @code{Repository},
-but the local name of the directory may differ from the repository name.
+Tell the server what directory to use.  The @var{repository} should be a
+directory name from a previous server response.  Note that
+this both gives a default for @code{Entry} and @code{Modified} and
+also for @code{ci} and the other commands; normal usage is to send 
+@code{Directory} for each directory in which there will be an
+@code{Entry} or @code{Modified}, and then a final @code{Directory}
+for the original directory, then the command.
 If the client uses this request, it affects the way the server returns
 pathnames; see @ref{Responses}.  @var{local-directory} is relative to
 the top level at which the command is occurring (i.e. the last
-@code{Directory} or @code{Repository} which is sent before the command);
+@code{Directory} which is sent before the command);
 to indicate that top level, @samp{.} should be send for
 @var{local-directory}.
 
@@ -364,7 +351,7 @@ request.
 
 @item Static-directory \n
 Response expected: no.  Tell the server that the directory most recently
-specified with @code{Repository} or @code{Directory} should not have
+specified with @code{Directory} should not have
 additional files checked out unless explicitly requested.  The client
 sends this if the @code{Entries.Static} flag is set, which is controlled
 by the @code{Set-static-directory} and @code{Clear-static-directory}
@@ -372,7 +359,7 @@ responses.
 
 @item Sticky @var{tagspec} \n
 Response expected: no.  Tell the server that the directory most recently
-specified with @code{Repository} has a sticky tag or date @var{tagspec}.
+specified with @code{Directory} has a sticky tag or date @var{tagspec}.
 The first character of @var{tagspec} is @samp{T} for a tag, or @samp{D}
 for a date.  The remainder of @var{tagspec} contains the actual tag or
 date.
@@ -392,42 +379,29 @@ Such a program would have been previously set with the
 @item Entry @var{entry-line} \n
 Response expected: no.  Tell the server what version of a file is on the
 local machine.  The name in @var{entry-line} is a name relative to the
-directory most recently specified with @code{Repository}.  If the user
+directory most recently specified with @code{Directory}.  If the user
 is operating on only some files in a directory, @code{Entry} requests
 for only those files need be included.  If an @code{Entry} request is
-sent without @code{Modified}, @code{Unchanged}, or @code{Lost} for that
-file the meaning depends on whether @code{UseUnchanged} has been sent;
-if it has been it means the file is lost, if not it means the file is
-unchanged.
+sent without @code{Modified} or @code{Unchanged}, it means the file is
+lost (does not exist in the working directory).
 
 @item Modified @var{filename} \n
 Response expected: no.  Additional data: mode, \n, file transmission.
 Send the server a copy of one locally modified file.  @var{filename} is
-relative to the most recent repository sent with @code{Repository}.  If
+relative to the most recent repository sent with @code{Directory}.  If
 the user is operating on only some files in a directory, only those
 files need to be included.  This can also be sent without @code{Entry},
 if there is no entry for the file.
 
-@item Lost @var{filename} \n
-Response expected: no.  Tell the server that @var{filename} no longer
-exists.  The name is relative to the most recent repository sent with
-@code{Repository}.  This is used for any case in which @code{Entry} is
-being sent but the file no longer exists.  If the client has issued the
-@code{UseUnchanged} request, then this request is not used.
-
 @item Unchanged @var{filename} \n
 Response expected: no.  Tell the server that @var{filename} has not been
 modified in the checked out directory.  The name is relative to the most
-recent repository sent with @code{Repository}.  This request can only be
-issued if @code{UseUnchanged} has been sent.
+recent repository sent with @code{Directory}.
 
 @item UseUnchanged \n
-Response expected: no.  Tell the server that the client will be
-indicating unmodified files with @code{Unchanged}, and that files for
-which no information is sent are nonexistent on the client side, not
-unchanged.  This is necessary for correct behavior since only the server
-knows what possible files may exist, and thus what files are
-nonexistent.
+Response expected: no.  To specify the version of the protocol described
+in this document, servers must support this request (although it need
+not do anything) and clients must issue it.
 
 @item Notify @var{filename} \n
 Response expected: no.
@@ -533,9 +507,9 @@ need to expand modules on the client side.
 @itemx editors \n
 @itemx annotate \n
 Response expected: yes.  Actually do a cvs command.  This uses any
-previous @code{Argument}, @code{Repository}, @code{Entry},
-@code{Modified}, or @code{Lost} requests, if they have been sent.  The
-last @code{Repository} sent specifies the working directory at the time
+previous @code{Argument}, @code{Directory}, @code{Entry}, or
+@code{Modified} requests, if they have been sent.  The
+last @code{Directory} sent specifies the working directory at the time
 of the operation.  No provision is made for any input from the user.
 This means that @code{ci} must use a @code{-m} argument if it wants to
 specify a log message.
@@ -548,18 +522,18 @@ directory and @emph{not} a fully qualified @code{CVSROOT} variable.  The
 
 @itemx update \n
 Response expected: yes.  Actually do a @code{cvs update} command.  This
-uses any previous @code{Argument}, @code{Repository}, @code{Entry},
-@code{Modified}, or @code{Lost} requests, if they have been sent.  The
-last @code{Repository} sent specifies the working directory at the time
+uses any previous @code{Argument}, @code{Directory}, @code{Entry},
+or @code{Modified} requests, if they have been sent.  The
+last @code{Directory} sent specifies the working directory at the time
 of the operation.  The @code{-I} option is not used--files which the
 client can decide whether to ignore are not mentioned and the client
 sends the @code{Questionable} request for others.
 
 @item import \n
 Response expected: yes.  Actually do a @code{cvs import} command.  This
-uses any previous @code{Argument}, @code{Repository}, @code{Entry},
-@code{Modified}, or @code{Lost} requests, if they have been sent.  The
-last @code{Repository} sent specifies the working directory at the time
+uses any previous @code{Argument}, @code{Directory}, @code{Entry}, or
+@code{Modified} requests, if they have been sent.  The
+last @code{Directory} sent specifies the working directory at the time
 of the operation.  The files to be imported are sent in @code{Modified}
 requests (files which the client knows should be ignored are not sent;
 the server must still process the CVSROOT/cvsignore file unless -I ! is
@@ -573,8 +547,8 @@ argument.
 Response expected: yes.  Actually do the @code{cvs watch on}, @code{cvs
 watch off}, @code{cvs watch add}, and @code{cvs watch remove} commands,
 respectively.  This uses any previous @code{Argument},
-@code{Repository}, @code{Entry}, @code{Modified}, or @code{Lost}
-requests, if they have been sent.  The last @code{Repository} sent
+@code{Directory}, @code{Entry}, or @code{Modified}
+requests, if they have been sent.  The last @code{Directory} sent
 specifies the working directory at the time of the operation.
 
 @item release \n
@@ -634,14 +608,13 @@ message and exiting---this should be investigated further).
 
 @c FIXME: should better document when the specified repository needs to
 @c end in "/.".
-Pathnames are of the actual files operated on (i.e. they do not contain
-@samp{,v} endings), and are suitable for use in a subsequent
-@code{Repository} request.  However, if the client has used the
-@code{Directory} request, then it is instead a local directory name
+In the following, @var{pathname} actually indicates a pair of
+pathnames.  First, a local directory name
 relative to the directory in which the command was given (i.e. the last
 @code{Directory} before the command).  Then a newline and a repository
-name (the pathname which is sent if @code{Directory} is not used).  Then
-the slash and the filename.  For example, for a file @file{i386.mh}
+name.  Then
+a slash and the filename (without a @samp{,v} ending).
+For example, for a file @file{i386.mh}
 which is in the local directory @file{gas.clean/config} and for which
 the repository is @file{/rel/cvsfiles/devo/gas/config}:
 
@@ -827,77 +800,181 @@ The command completed successfully.
 @node Example
 @section Example
 
-@c FIXME: Use Directory, not Repository!
-@c FIXME-less-important: Use Created and Update-existing, not Updated.
-@c FIXME: the presence of timestamps in the entries lines is not right.
+@c The C:/S: convention is in imitation of RFC1869 (and presumably
+@c other RFC's).  In other formatting concerns, we might want to think
+@c about whether there is an easy way to provide RFC1543 formatting
+@c (without negating the advantages of texinfo), and whether we should
+@c use RFC822-style BNF (I fear that would be less clear than
+@c what we do now, however).  Plus what about IETF terminology (SHOULD,
+@c MUST, etc.) or ISO terminology (shall, should, or whatever they are)?
+Here is an example; lines are prefixed by @samp{C: } to indicate the
+client sends them or @samp{S: } to indicate the server sends them.
+
+The client starts by connecting, sending the root, and completing the
+protocol negotiation.  In actual practice the lists of valid responses
+and requests would be longer.
+@c The reason that we artificially shorten the lists is to avoid phony
+@c line breaks.  Any better solutions?
+@c Other than that, this exchange is taken verbatim from the data
+@c exchanged by CVS (as of Nov 1996).  That is why some of the requests and
+@c reponses are not quite what you would pick for pedagogical purposes.
+
+@example
+C: Root /home/kingdon/testing/cvsroot
+C: Valid-responses ok error Checked-in M E
+C: valid-requests
+S: Valid-requests Root Directory Entry Modified Argument Argumentx ci co
+S: ok
+C: UseUnchanged
+@end example
+
+The client wants to check out the @code{supermunger} module into a fresh
+working directory.  Therefore it first expands the @code{supermunger}
+module; this step would be omitted if the client was operating on a
+directory rather than a module.
+@c Why does it send Directory here?  The description of expand-modules
+@c doesn't really say much of anything about what use, if any, it makes of
+@c Directory and similar requests sent previously.
+
+@example
+C: Argument supermunger
+C: Directory .
+C: /home/kingdon/testing/cvsroot
+C: expand-modules
+@end example
+
+The server replies that the @code{supermunger} module expands to the
+directory @code{supermunger} (the simplest case):
+
+@example
+S: Module-expansion supermunger
+S: ok
+@end example
+
+The client then proceeds to check out the directory.  The fact that it
+sends only a single @code{Directory} request which specifies @samp{.}
+for the working directory means that there is not already a
+@code{supermunger} directory on the client.
+@c What is -N doing here?
+
+@example
+C: Argument -N
+C: Argument supermunger
+C: Directory .
+C: /home/kingdon/testing/cvsroot
+C: co
+@end example
+
+The server replies with the requested files.  In this example, there is
+only one, @file{mungeall.c}.  The @code{Clear-sticky} and
+@code{Clear-static-directory} requests are sent by the current
+implementation but they have no effect because the default is for those
+settings to be clear when a directory is newly created.
+
+@example
+S: Clear-sticky supermunger/
+S: /home/kingdon/testing/cvsroot/supermunger/
+S: Clear-static-directory supermunger/
+S: /home/kingdon/testing/cvsroot/supermunger/
+S: E cvs server: Updating supermunger
+S: M U supermunger/mungeall.c
+S: Created supermunger/
+S: /home/kingdon/testing/cvsroot/supermunger/mungeall.c
+S: /mungeall.c/1.1///
+S: u=rw,g=r,o=r
+S: 26
+S: int mein () @{ abort (); @}
+S: ok
+@end example
+
+The current client implementation would break the connection here and make a
+new connection for the next command.  However, the protocol allows it
+to keep the connection open and continue, which is what we show here.
+
+After the user modifies the file and instructs the client to check it
+back in.  The client sends arguments to specify the log message and file
+to check in:
+
+@example
+C: Argument -m
+C: Argument Well, you see, it took me hours and hours to find this typo and I
+C: Argumentx searched and searched and eventually had to ask John for help.
+C: Argument mungeall.c
+@end example
+
+It also sends information about the contents of the working directory,
+including the new contents of the modified file.  Note that the user has
+changed into the @file{supermunger} directory before executing this
+command; the top level directory is a user-visible concept because the
+server should print filenames in @code{M} and @code{E} responses
+relative to that directory.
+@c We are waving our hands about the order of the requests.  "Directory"
+@c and "Argument" can be in any order, but this probably isn't specified
+@c very well.
+
+@example
+C: Directory .
+C: /home/kingdon/testing/cvsroot/supermunger
+C: Entry /mungeall.c/1.1///
+C: Modified mungeall.c
+C: u=rw,g=r,o=r
+C: 26
+C: int main () @{ abort (); @}
+@end example
+
+And finally, the client issues the checkin command (which makes use of
+the data just sent):
+
+@example
+C: ci
+@end example
 
-Lines beginning with @samp{c>} are sent by the client; lines beginning
-with @samp{s>} are sent by the server; lines beginning with @samp{#} are
-not part of the actual exchange.
+And the server tells the client that the checkin succeeded:
 
 @example
-c> Root /rel/cvsfiles
-# In actual practice the lists of valid responses and requests would
-# be longer
-c> Valid-responses Updated Checked-in M ok error
-c> valid-requests
-s> Valid-requests Root co Modified Entry Repository ci Argument Argumentx
-s> ok
-# cvs co devo/foo
-c> Argument devo/foo
-c> co
-s> Updated /rel/cvsfiles/devo/foo/foo.c
-s> /foo.c/1.4/Mon Apr 19 15:36:47 1993 Mon Apr 19 15:36:47 1993//
-s> 26
-s> int mein () @{ abort (); @}
-s> Updated /rel/cvsfiles/devo/foo/Makefile
-s> /Makefile/1.2/Mon Apr 19 15:36:47 1993 Mon Apr 19 15:36:47 1993//
-s> 28
-s> foo: foo.c
-s>         $(CC) -o foo $<
-s> ok
-# The current implementation would break the connection here and make a
-# new connection for the next command.  However, the protocol allows it
-# to keep the connection open and continue, which is what we show here.
-c> Repository /rel/cvsfiles/devo/foo
-# foo.c relative to devo/foo just set as Repository.
-c> Entry /foo.c/1.4/Mon Apr 19 15:36:47 1993 Mon Apr 19 15:36:47 1993//
-c> Entry /Makefile/1.2/Mon Apr 19 15:36:47 1993 Mon Apr 19 15:36:47 1993//
-c> Modified foo.c
-c> 26
-c> int main () @{ abort (); @}
-# cvs ci -m <log message> foo.c
-c> Argument -m
-c> Argument Well, you see, it took me hours and hours to find this typo and I
-c> Argumentx searched and searched and eventually had to ask John for help.
-c> Argument foo.c
-c> ci
-s> Checked-in /rel/cvsfiles/devo/foo/foo.c
-s> /foo.c/1.5/ Mon Apr 19 15:54:22 CDT 1993//
-s> M Checking in foo.c;
-s> M /cygint/rel/cvsfiles/devo/foo/foo.c,v  <--  foo.c
-s> M new revision: 1.5; previous revision: 1.4
-s> M done
-s> ok
+S: M Checking in mungeall.c;
+S: E /home/kingdon/testing/cvsroot/supermunger/mungeall.c,v  <--  mungeall.c
+S: E new revision: 1.2; previous revision: 1.1
+S: E done
+S: Mode u=rw,g=r,o=r
+S: Checked-in ./
+S: /home/kingdon/testing/cvsroot/supermunger/mungeall.c
+S: /mungeall.c/1.2///
+S: ok
 @end example
 
 @node Requirements
 @section Required versus optional parts of the protocol
 
-The following are part of every known implementation of the CVS
-protocol and it is considered reasonable behavior to completely fail
-to work if you are connected with an implementation which attempts to
-not support them.  Requests: Root, Valid-responses, valid-requests,
-Repository, Entry, Modified, Argument, Argumentx, ci, co, update.
-Responses: ok, error, Valid-requests, Checked-in, Updated, Merged,
-Removed, M, E.
-
-Failure to support the Directory, UseUnchanged, and Unchanged requests
-is deprecated.  CVS 1.5 and later have supported these requests and in
-the future it will be considered reasonable behavior to completely
-fail to work with an implementation which attempts to not support
-them.  Support for the Repository and Lost requests is deprecated; CVS
-clients 1.5 and later will not use them if communicating with a server
-which supports Directory and UseUnchanged.
+The following are part of every known implementation of the CVS protocol
+(except obsolete, pre-1.5, versions of CVS) and it is considered
+reasonable behavior to completely fail to work if you are connected with
+an implementation which attempts to not support them.  Requests:
+@code{Root}, @code{Valid-responses}, @code{valid-requests},
+@code{Directory}, @code{Entry}, @code{Modified}, @code{Unchanged},
+@code{Argument}, @code{Argumentx}, @code{ci}, @code{co}, @code{update}.
+Responses: @code{ok}, @code{error}, @code{Valid-requests},
+@code{Checked-in}, @code{Updated}, @code{Merged}, @code{Removed},
+@code{M}, @code{E}.
+
+A server need not implement @code{Repository}, but in order to interoperate
+with CVS 1.5 through 1.9 it must claim to implement it (in
+@code{Valid-requests}).  The client will not actually send the request.
+
+@node Obsolete
+@section Obsolete protocol elements
+
+This section briefly describes protocol elements which are obsolete.
+There is no attempt to document them in full detail.
+
+There was a @code{Repository} request which was like @code{Directory}
+except it only provided @var{repository}, and the local directory was
+assumed to be similarly named.
+
+If the @code{UseUnchanged} request was not sent, there was a @code{Lost}
+request which was sent to indicate that a file did not exist in the
+working directory, and the meaning of sending @code{Entries} without
+@code{Lost} or @code{Modified} was different.  All current clients (CVS
+1.5 and later) will send @code{UseUnchanged} if it is supported.
 
 @bye