cvs: remove ~3.5Mb of doc files from contrib (texi/pdf)
authorJohn Marino <draco@marino.st>
Fri, 3 Apr 2015 08:59:00 +0000 (10:59 +0200)
committerJohn Marino <draco@marino.st>
Fri, 3 Apr 2015 08:59:00 +0000 (10:59 +0200)
The only documentation we needs from cvs is in man/cvs.5 and doc/cvs.1.
Everything else is unused, including the pre-generated pdf files, so
lets save shallow repos from pulling these large unused files.

20 files changed:
contrib/cvs-1.12/README.DELETED
contrib/cvs-1.12/doc/HACKING.DOCS [deleted file]
contrib/cvs-1.12/doc/cvs-paper.pdf [deleted file]
contrib/cvs-1.12/doc/cvs.man.footer [deleted file]
contrib/cvs-1.12/doc/cvs.man.header [deleted file]
contrib/cvs-1.12/doc/cvs.pdf [deleted file]
contrib/cvs-1.12/doc/cvs.texinfo [deleted file]
contrib/cvs-1.12/doc/cvsclient.pdf [deleted file]
contrib/cvs-1.12/doc/cvsclient.texi [deleted file]
contrib/cvs-1.12/doc/getdate-cvs.texi [deleted file]
contrib/cvs-1.12/doc/getdate.texi [deleted file]
contrib/cvs-1.12/doc/i18n/ChangeLog [deleted file]
contrib/cvs-1.12/doc/i18n/README [deleted file]
contrib/cvs-1.12/doc/i18n/pt_BR/ChangeLog [deleted file]
contrib/cvs-1.12/doc/i18n/pt_BR/README [deleted file]
contrib/cvs-1.12/doc/i18n/pt_BR/cvs.texinfo [deleted file]
contrib/cvs-1.12/doc/mkman.pl [deleted file]
contrib/cvs-1.12/doc/version-client.texi [deleted file]
contrib/cvs-1.12/doc/version.texi [deleted file]
contrib/cvs-1.12/doc/writeproxy.rtf [deleted file]

index 2972163..38f05a8 100644 (file)
@@ -59,23 +59,32 @@ diff/libdiff.mak
 doc/.cvsignore
 doc/ChangeLog
 doc/ChangeLog.fsf
+doc/HACKING.DOCS
 doc/Makefile.am
 doc/Makefile.in
 doc/RCSFILES
 doc/cvs-paper.ms
+doc/cvs-paper.pdf
 doc/cvs.info
 doc/cvs.info-1
 doc/cvs.info-2
+doc/cvs.man.footer
+doc/cvs.man.header
+doc/cvs.pdf
+doc/cvs.texinfo
 doc/cvsclient.info
-doc/i18n/.cvsignore
-doc/i18n/Makefile.am
-doc/i18n/Makefile.in
-doc/i18n/pt_BR/.cvsignore
-doc/i18n/pt_BR/Makefile.am
-doc/i18n/pt_BR/Makefile.in
+doc/cvsclient.pdf
+doc/cvsclient.texi
+doc/getdate-cvs.texi
+doc/getdate.texi
+doc/i18n/
 doc/mdate-sh
+doc/mkman.pl
 doc/stamp-1
 doc/stamp-vti
+doc/version-client.texi
+doc/version.texi
+doc/writeproxy.rtf
 emx/
 lib/.cvsignore
 lib/ChangeLog
diff --git a/contrib/cvs-1.12/doc/HACKING.DOCS b/contrib/cvs-1.12/doc/HACKING.DOCS
deleted file mode 100644 (file)
index adf6077..0000000
+++ /dev/null
@@ -1,46 +0,0 @@
-Here's some of the texinfo conventions the CVS documentation uses:
-
-@code{ ... }                   command usage & command snippets, including
-                               command names.
-@var{ ... }                    variables - text which the user is expected to
-                               replace with some meaningful text of their own
-                               in actual usage.
-@file{ ... }                   file names
-@samp{ ... }                   for most anything else you need quotes around
-                               (often still misused for command snippets)
-@example ... @end example      example command usage and output, etc.
-@emph{ ... }                   emphasis - warnings, stress, etc.  This will be
-                               bracketed by underline characters in info files
-                               (_ ... _) and in italics in PDF & probably in
-                               postscript & HTML.
-@strong{ ... }                 Similar to @emph{}, but the effect is to
-                               bracket with asterisks in info files (* ... *)
-                               and in bold in PDF & probably in postscript &
-                               HTML.
-@noindent                      Suppresses indentation of the following
-                               paragraph.  This can ocassionally be useful
-                               after examples and the like.
-@cindex ...                    Add a tag to the index.
-@pxref{ ... }                  Cross reference in parentheses.
-@xref{ ... }                   Cross reference.
-
-Preformatted text should be marked as such (use @example... there may be other
-ways) since many of the final output formats can use relational fonts otherwise
-and marking it as formatted should restrict it to a fixed width font.  Keep
-this sort of text to 80 characters or less per line since larger may not be
-properly viewable for some info users.
-
-There are dictionary lists and function definition markers.  Scan cvs.texinfo
-for their usage.  There may be table definitions as well but I haven't used
-them.
-
-Use lots of index markers.  Scan the index for the current style.  Try to reuse
-an existing entry if the meaning is similar.
-
-`makeinfo' 3.11 or greater is required for output generation since earlier
-versions do not support the @ifnottex & @ifnothtml commands.  There may be
-other commands used in `cvs.texinfo' that are unsupported by earlier versions
-of `makeinfo' by the time you read this.
-
-For more on using texinfo docs, see the `info texinfo' documentation or
-http://www.gnu.org/manual/texinfo/texinfo.html .
diff --git a/contrib/cvs-1.12/doc/cvs-paper.pdf b/contrib/cvs-1.12/doc/cvs-paper.pdf
deleted file mode 100644 (file)
index 4a153dd..0000000
Binary files a/contrib/cvs-1.12/doc/cvs-paper.pdf and /dev/null differ
diff --git a/contrib/cvs-1.12/doc/cvs.man.footer b/contrib/cvs-1.12/doc/cvs.man.footer
deleted file mode 100644 (file)
index 2987e1a..0000000
+++ /dev/null
@@ -1,58 +0,0 @@
-.SH "AUTHORS"
-.TP
-Dick Grune
-Original author of the
-.B cvs
-shell script version posted to
-.B comp.sources.unix
-in the volume6 release of December, 1986.
-Credited with much of the
-.B cvs
-conflict resolution algorithms.
-.TP
-Brian Berliner
-Coder and designer of the
-.B cvs
-program itself in April, 1989, based on the original work done by Dick.
-.TP
-Jeff Polk
-Helped Brian with the design of the
-.B cvs
-module and vendor branch support and author of the
-.BR checkin ( 1 )
-shell script (the ancestor of \fBcvs import\fP).
-.TP
-Larry Jones, Derek R. Price, and Mark D. Baushke
-Have helped maintain
-.B cvs
-for many years.
-.TP
-And many others too numerous to mention here.
-.SH "SEE ALSO"
-The most comprehensive manual for CVS is
-Version Management with CVS by Per Cederqvist et al.  Depending on
-your system, you may be able to get it with the
-.B info CVS
-command or it may be available as cvs.pdf (Portable Document Format),
-cvs.ps (PostScript), cvs.texinfo (Texinfo source), or cvs.html.
-.SP
-For CVS updates, more information on documentation, software related
-to CVS, development of CVS, and more, see:
-.in +1i
-.SP
-.PD 0
-.IP "" 4
-.B http://www.nongnu.org/cvs/
-.in -1i
-.SP
-.BR ci ( 1 ),
-.BR co ( 1 ),
-.BR cvs ( 5 ),
-.BR cvsbug ( 8 ),
-.BR diff ( 1 ),
-.BR grep ( 1 ),
-.BR patch ( 1 ),
-.BR rcs ( 1 ),
-.BR rcsdiff ( 1 ),
-.BR rcsmerge ( 1 ),
-.BR rlog ( 1 ).
diff --git a/contrib/cvs-1.12/doc/cvs.man.header b/contrib/cvs-1.12/doc/cvs.man.header
deleted file mode 100644 (file)
index cbc4f7d..0000000
+++ /dev/null
@@ -1,61 +0,0 @@
-.\" This is the man page for CVS.  It is auto-generated from the
-.\" cvs.man.header, cvs.texinfo, & cvs.man.footer files.  Please make changes
-.\" there.  A full copyright & license notice may also be found in cvs.texinfo.
-.\"
-.\" Man page autogeneration, including this header file, is
-.\" Copyright 2004-2005 The Free Software Foundation, Inc.,
-.\"                     Derek R. Price, & Ximbiot <http://ximbiot.com>.
-.\"
-.\" This documentation is free software; you can redistribute it and/or modify
-.\" it under the terms of the GNU General Public License as published by
-.\" the Free Software Foundation; either version 2, or (at your option)
-.\" any later version.
-.\"
-.\" This documentation is distributed in the hope that it will be useful,
-.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
-.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-.\" GNU General Public License for more details.
-.\"
-.\" You should have received a copy of the GNU General Public License
-.\" along with this documentation; if not, write to the Free Software
-.\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-.de Id
-.ds Rv \\$3
-.ds Dt \\$4
-..
-.TH CVS 1 "\*(Dt"
-.\" Full space in nroff; half space in troff
-.de SP
-.if n .sp
-.if t .sp .5
-..
-.\" quoted command
-.de `
-.RB ` "\|\\$1\|" '\\$2
-..
-.SH "NAME"
-cvs \- Concurrent Versions System
-.SH "SYNOPSIS"
-.TP
-\fBcvs\fP [ \fIcvs_options\fP ]
-.I cvs_command
-[
-.I command_options
-] [
-.I command_args
-]
-.SH "NOTE"
-.IX "revision control system" "\fLcvs\fR"
-.IX  cvs  ""  "\fLcvs\fP \- concurrent versions system"
-.IX  "concurrent versions system \- \fLcvs\fP"
-.IX  "release control system"  "cvs command"  ""  "\fLcvs\fP \- concurrent versions system"
-.IX  "source control system"  "cvs command"  ""  "\fLcvs\fP \- concurrent versions system"
-.IX  revisions  "cvs command"  ""  "\fLcvs\fP \- source control"
-This manpage is a summary of some of the features of
-\fBcvs\fP.  It is auto-generated from an appendix of the CVS manual.
-For more in-depth documentation, please consult the
-Cederqvist manual (via the
-.B info CVS
-command or otherwise,
-as described in the SEE ALSO section of this manpage).  Cross-references
-in this man page refer to nodes in the same.
diff --git a/contrib/cvs-1.12/doc/cvs.pdf b/contrib/cvs-1.12/doc/cvs.pdf
deleted file mode 100644 (file)
index 0facba6..0000000
Binary files a/contrib/cvs-1.12/doc/cvs.pdf and /dev/null differ
diff --git a/contrib/cvs-1.12/doc/cvs.texinfo b/contrib/cvs-1.12/doc/cvs.texinfo
deleted file mode 100644 (file)
index 123ab93..0000000
+++ /dev/null
@@ -1,15928 +0,0 @@
-\input texinfo  @c -*-texinfo-*-
-@comment Documentation for CVS.
-@setfilename cvs.info
-@macro copyleftnotice
-@noindent
-Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
-                       2001, 2002, 2003, 2004, 2005
-                       Free Software Foundation, Inc.
-
-@multitable @columnfractions .12 .88
-@item Portions
-@item @tab Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005
-                                  Derek R. Price,
-@item @tab Copyright @copyright{} 2002, 2003, 2004, 2005
-                                  Ximbiot @url{http://ximbiot.com},
-@item @tab Copyright @copyright{} 1992, 1993, 1999 Signum Support AB,
-@item @tab and Copyright @copyright{} others.
-@end multitable
-
-@ignore
-Permission is granted to process this file through Tex and print the
-results, provided the printed document carries copying permission
-notice identical to this one except for the removal of this paragraph
-(this paragraph not being relevant to the printed manual).
-
-@end ignore
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
-
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided also that the
-entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions,
-except that this permission notice may be stated in a translation
-approved by the Free Software Foundation.
-@end macro
-
-@comment This file is part of the CVS distribution.
-
-@comment CVS is free software; you can redistribute it and/or modify
-@comment it under the terms of the GNU General Public License as published by
-@comment the Free Software Foundation; either version 2, or (at your option)
-@comment any later version.
-
-@comment CVS is distributed in the hope that it will be useful,
-@comment but WITHOUT ANY WARRANTY; without even the implied warranty of
-@comment MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-@comment GNU General Public License for more details.
-
-@c See ../README for A4 vs. US letter size.
-@c When we provided A4 postscript, and people tried to
-@c print it on US letter, the usual complaint was that the
-@c page numbers would get cut off.
-@c If one prints US letter on A4, reportedly there is
-@c some extra space at the top and/or bottom, and the side
-@c margins are a bit narrow, but no text is lost.
-@c
-@c See
-@c http://www.ft.uni-erlangen.de/~mskuhn/iso-paper.html
-@c for more on paper sizes.  Insuring that margins are
-@c big enough to print on either A4 or US letter does
-@c indeed seem to be the usual approach (RFC2346).
-
-@c This document seems to get overfull hboxes with some
-@c frequency (probably because the tendency is to
-@c sanity-check it with "make info" and run TeX less
-@c often).  The big ugly boxes just seem to add insult
-@c to injury, and I'm not aware of them helping to fix
-@c the overfull hboxes at all.
-@finalout
-
-@include version.texi
-@settitle CVS---Concurrent Versions System v@value{VERSION}
-@setchapternewpage odd
-
-@c -- TODO list:
-@c -- Fix all lines that match "^@c -- "
-@c -- Also places marked with FIXME should be manual
-@c problems (as opposed to FIXCVS for CVS problems).
-
-@c @splitrcskeyword{} is used to avoid keyword expansion.  It is replaced by
-@c @asis when generating info and dvi, and by <i></i> in the generated html,
-@c such that keywords are not expanded in the generated html. 
-@ifnothtml
-@macro splitrcskeyword {arg}
-@asis{}\arg\
-@end macro
-@end ifnothtml
-
-@ifhtml
-@macro splitrcskeyword {arg}
-@i{}\arg\
-@end macro
-@end ifhtml
-
-@dircategory GNU Packages
-@direntry
-* CVS: (cvs).                   Concurrent Versions System
-@end direntry
-@dircategory Individual utilities
-@direntry
-* cvs: (cvs)CVS commands.       Concurrent Versions System
-@end direntry
-
-@comment The titlepage section does not appear in the Info file.
-@titlepage
-@sp 4
-@comment The title is printed in a large font.
-@center @titlefont{Version Management}
-@sp
-@center @titlefont{with}
-@sp
-@center @titlefont{CVS}
-@sp 2
-@center for @sc{cvs} @value{VERSION}
-@comment -release-
-@sp 3
-@center Per Cederqvist et al
-
-@comment  The following two commands start the copyright page
-@comment  for the printed manual.  This will not appear in the Info file.
-@page
-@vskip 0pt plus 1filll
-@copyleftnotice
-@end titlepage
-
-@summarycontents
-
-@contents
-
-@comment ================================================================
-@comment                   The real text starts here
-@comment ================================================================
-
-@ifnottex
-@c ---------------------------------------------------------------------
-@node    Top
-@top
-
-This info manual describes how to use and administer
-@sc{cvs} version @value{VERSION}.
-@end ifnottex
-
-@ifinfo
-@copyleftnotice
-@end ifinfo
-
-@c This menu is pretty long.  Not sure how easily that
-@c can be fixed (no brilliant ideas right away)...
-@menu
-* Overview::                    An introduction to CVS
-* Repository::                  Where all your sources are stored
-* Starting a new project::      Starting a project with CVS
-* Revisions::                   Numeric and symbolic names for revisions
-* Branching and merging::       Diverging/rejoining branches of development
-* Recursive behavior::          CVS descends directories
-* Adding and removing::         Adding/removing/renaming files/directories
-* History browsing::            Viewing the history of files in various ways
-
-CVS and the Real World.
------------------------
-* Binary files::                CVS can handle binary files
-* Multiple developers::         How CVS helps a group of developers
-* Revision management::         Policy questions for revision management
-* Keyword substitution::        CVS can include the revision inside the file
-* Tracking sources::            Tracking third-party sources
-* Builds::                      Issues related to CVS and builds
-* Special Files::              Devices, links and other non-regular files
-
-References.
------------
-* CVS commands::                CVS commands share some things
-* Invoking CVS::                Quick reference to CVS commands
-* Administrative files::        Reference manual for the Administrative files
-* Environment variables::       All environment variables which affect CVS
-* Compatibility::               Upgrading CVS versions
-* Troubleshooting::             Some tips when nothing works
-* Credits::                     Some of the contributors to this manual
-* BUGS::                        Dealing with bugs in CVS or this manual
-* Index::                       Index
-@end menu
-
-@c ---------------------------------------------------------------------
-@node Overview
-@chapter Overview
-@cindex Overview
-
-This chapter is for people who have never used
-@sc{cvs}, and perhaps have never used version control
-software before.
-
-If you are already familiar with @sc{cvs} and are just
-trying to learn a particular feature or remember a
-certain command, you can probably skip everything here.
-
-@menu
-* What is CVS?::                What you can do with @sc{cvs}
-* What is CVS not?::            Problems @sc{cvs} doesn't try to solve
-* A sample session::            A tour of basic @sc{cvs} usage
-@end menu
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node What is CVS?
-@section What is CVS?
-@cindex What is CVS?
-@cindex Introduction to CVS
-@cindex CVS, introduction to
-
-@sc{cvs} is a version control system.  Using it, you can
-record the history of your source files.
-
-@c -- ///
-@c -- ///Those who cannot remember the past are condemned to repeat it.
-@c -- ///               -- George Santayana
-@c -- //////
-
-@c -- Insert history  quote here!
-For example, bugs sometimes creep in when
-software is modified, and you might not detect the bug
-until a long time after you make the modification.
-With @sc{cvs}, you can easily retrieve old versions to see
-exactly which change caused the bug.  This can
-sometimes be a big help.
-
-You could of course save every version of every file
-you have ever created.  This would
-however waste an enormous amount of disk space.  @sc{cvs}
-stores all the versions of a file in a single file in a
-clever way that only stores the differences between
-versions.
-
-@sc{cvs} also helps you if you are part of a group of people working
-on the same project.  It is all too easy to overwrite
-each others' changes unless you are extremely careful.
-Some editors, like @sc{gnu} Emacs, try to make sure that
-two people never modify the same file at the
-same time.  Unfortunately, if someone is using another
-editor, that safeguard will not work.  @sc{cvs} solves this problem
-by insulating the different developers from each other.  Every
-developer works in his own directory, and @sc{cvs} merges
-the work when each developer is done.
-
-@cindex History of CVS
-@cindex CVS, history of
-@cindex Credits (CVS program)
-@cindex Contributors (CVS program)
-@sc{cvs} started out as a bunch of shell scripts written by
-Dick Grune, posted to the newsgroup
-@code{comp.sources.unix} in the volume 6
-release of July, 1986.  While no actual code from
-these shell scripts is present in the current version
-of @sc{cvs} much of the @sc{cvs} conflict resolution algorithms
-come from them.
-
-In April, 1989, Brian Berliner designed and coded @sc{cvs}.
-Jeff Polk later helped Brian with the design of the @sc{cvs}
-module and vendor branch support.
-
-@cindex Source, getting CVS source
-You can get @sc{cvs} in a variety of ways, including
-free download from the Internet.  For more information
-on downloading @sc{cvs} and other @sc{cvs} topics, see:
-
-@example
-@url{http://cvs.nongnu.org/}
-@end example
-
-@cindex Mailing list
-@cindex List, mailing list
-@cindex Newsgroups
-There is a mailing list, known as @email{info-cvs@@nongnu.org},
-devoted to @sc{cvs}.  To subscribe or
-unsubscribe
-write to
-@email{info-cvs-request@@nongnu.org}.
-If you prefer a Usenet group, there is a one-way mirror (posts to the email
-list are usually sent to the news group, but not visa versa) of
-@email{info-cvs@@nongnu.org} at @url{news:gnu.cvs.help}.  The right
-Usenet group for posts is @url{news:comp.software.config-mgmt} which is for
-@sc{cvs} discussions (along with other configuration
-management systems).  In the future, it might be
-possible to create a
-@code{comp.software.config-mgmt.cvs}, but probably only
-if there is sufficient @sc{cvs} traffic on
-@url{news:comp.software.config-mgmt}.
-@c Other random data is that the tale was very
-@c skeptical of comp.software.config-mgmt.cvs when the
-@c subject came up around 1995 or so (for one
-@c thing, because creating it would be a "reorg" which
-@c would need to take a more comprehensive look at the
-@c whole comp.software.config-mgmt.* hierarchy).
-
-You can also subscribe to the @email{bug-cvs@@nongnu.org} mailing list,
-described in more detail in @ref{BUGS}.  To subscribe
-send mail to @email{bug-cvs-request@@nongnu.org}.  There is a two-way
-Usenet mirror (posts to the Usenet group are usually sent to the email list and
-visa versa) of @email{bug-cvs@@nongnu.org} named @url{news:gnu.cvs.bug}.
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node What is CVS not?
-@section What is CVS not?
-@cindex What is CVS not?
-
-@sc{cvs} can do a lot of things for you, but it does
-not try to be everything for everyone.
-
-@table @asis
-@item @sc{cvs} is not a build system.
-
-Though the structure of your repository and modules
-file interact with your build system
-(e.g. @file{Makefile}s), they are essentially
-independent.
-
-@sc{cvs} does not dictate how you build anything.  It
-merely stores files for retrieval in a tree structure
-you devise.
-
-@sc{cvs} does not dictate how to use disk space in the
-checked out working directories.  If you write your
-@file{Makefile}s or scripts in every directory so they
-have to know the relative positions of everything else,
-you wind up requiring the entire repository to be
-checked out.
-
-If you modularize your work, and construct a build
-system that will share files (via links, mounts,
-@code{VPATH} in @file{Makefile}s, etc.), you can
-arrange your disk usage however you like.
-
-But you have to remember that @emph{any} such system is
-a lot of work to construct and maintain.  @sc{cvs} does
-not address the issues involved.
-
-Of course, you should place the tools created to
-support such a build system (scripts, @file{Makefile}s,
-etc) under @sc{cvs}.
-
-Figuring out what files need to be rebuilt when
-something changes is, again, something to be handled
-outside the scope of @sc{cvs}.  One traditional
-approach is to use @code{make} for building, and use
-some automated tool for generating the dependencies which
-@code{make} uses.
-
-See @ref{Builds}, for more information on doing builds
-in conjunction with @sc{cvs}.
-
-@item @sc{cvs} is not a substitute for management.
-
-Your managers and project leaders are expected to talk
-to you frequently enough to make certain you are aware
-of schedules, merge points, branch names and release
-dates.  If they don't, @sc{cvs} can't help.
-
-@sc{cvs} is an instrument for making sources dance to
-your tune.  But you are the piper and the composer.  No
-instrument plays itself or writes its own music.
-
-@item @sc{cvs} is not a substitute for developer communication.
-
-When faced with conflicts within a single file, most
-developers manage to resolve them without too much
-effort.  But a more general definition of ``conflict''
-includes problems too difficult to solve without
-communication between developers.
-
-@sc{cvs} cannot determine when simultaneous changes
-within a single file, or across a whole collection of
-files, will logically conflict with one another.  Its
-concept of a @dfn{conflict} is purely textual, arising
-when two changes to the same base file are near enough
-to spook the merge (i.e. @code{diff3}) command.
-
-@sc{cvs} does not claim to help at all in figuring out
-non-textual or distributed conflicts in program logic.
-
-For example: Say you change the arguments to function
-@code{X} defined in file @file{A}.  At the same time,
-someone edits file @file{B}, adding new calls to
-function @code{X} using the old arguments.  You are
-outside the realm of @sc{cvs}'s competence.
-
-Acquire the habit of reading specs and talking to your
-peers.
-
-
-@item @sc{cvs} does not have change control
-
-Change control refers to a number of things.  First of
-all it can mean @dfn{bug-tracking}, that is being able
-to keep a database of reported bugs and the status of
-each one (is it fixed?  in what release?  has the bug
-submitter agreed that it is fixed?).  For interfacing
-@sc{cvs} to an external bug-tracking system, see the
-@file{rcsinfo} and @file{verifymsg} files
-(@pxref{Administrative files}).
-
-Another aspect of change control is keeping track of
-the fact that changes to several files were in fact
-changed together as one logical change.  If you check
-in several files in a single @code{cvs commit}
-operation, @sc{cvs} then forgets that those files were
-checked in together, and the fact that they have the
-same log message is the only thing tying them
-together.  Keeping a @sc{gnu} style @file{ChangeLog}
-can help somewhat.
-@c FIXME: should have an xref to a section which talks
-@c more about keeping ChangeLog's with CVS, but that
-@c section hasn't been written yet.
-
-Another aspect of change control, in some systems, is
-the ability to keep track of the status of each
-change.  Some changes have been written by a developer,
-others have been reviewed by a second developer, and so
-on.  Generally, the way to do this with @sc{cvs} is to
-generate a diff (using @code{cvs diff} or @code{diff})
-and email it to someone who can then apply it using the
-@code{patch} utility.  This is very flexible, but
-depends on mechanisms outside @sc{cvs} to make sure
-nothing falls through the cracks.
-
-@item @sc{cvs} is not an automated testing program
-
-It should be possible to enforce mandatory use of a
-test suite using the @code{commitinfo} file.  I haven't
-heard a lot about projects trying to do that or whether
-there are subtle gotchas, however.
-
-@item @sc{cvs} does not have a built-in process model
-
-Some systems provide ways to ensure that changes or
-releases go through various steps, with various
-approvals as needed.  Generally, one can accomplish
-this with @sc{cvs} but it might be a little more work.
-In some cases you'll want to use the @file{commitinfo},
-@file{loginfo}, @file{rcsinfo}, or @file{verifymsg}
-files, to require that certain steps be performed
-before cvs will allow a checkin.  Also consider whether
-features such as branches and tags can be used to
-perform tasks such as doing work in a development tree
-and then merging certain changes over to a stable tree
-only once they have been proven.
-@end table
-
-@c ---------------------------------------------------------------------
-@node A sample session
-@section A sample session
-@cindex Example of a work-session
-@cindex Getting started
-@cindex Work-session, example of
-@cindex tc, Trivial Compiler (example)
-@cindex Trivial Compiler (example)
-
-@c I think an example is a pretty good way to start.  But
-@c somewhere in here, maybe after the sample session,
-@c we need something which is kind of
-@c a "roadmap" which is more directed at sketching out
-@c the functionality of CVS and pointing people to
-@c various other parts of the manual.  As it stands now
-@c people who read in order get dumped right into all
-@c manner of hair regarding remote repositories,
-@c creating a repository, etc.
-@c
-@c The following was in the old Basic concepts node.  I don't
-@c know how good a job it does at introducing modules,
-@c or whether they need to be introduced so soon, but
-@c something of this sort might go into some
-@c introductory material somewhere.
-@ignore
-@cindex Modules (intro)
-The repository contains directories and files, in an
-arbitrary tree.  The @dfn{modules} feature can be used
-to group together a set of directories or files into a
-single entity (@pxref{modules}).  A typical usage is to
-define one module per project.
-@end ignore
-
-As a way of introducing @sc{cvs}, we'll go through a
-typical work-session using @sc{cvs}.  The first thing
-to understand is that @sc{cvs} stores all files in a
-centralized @dfn{repository} (@pxref{Repository}); this
-section assumes that a repository is set up.
-@c I'm not sure that the sentence concerning the
-@c repository quite tells the user what they need to
-@c know at this point.  Might need to expand on "centralized"
-@c slightly (maybe not here, maybe further down in the example?)
-
-Suppose you are working on a simple compiler.  The source
-consists of a handful of C files and a @file{Makefile}.
-The compiler is called @samp{tc} (Trivial Compiler),
-and the repository is set up so that there is a module
-called @samp{tc}.
-
-@menu
-* Getting the source::          Creating a workspace
-* Committing your changes::     Making your work available to others
-* Cleaning up::                 Cleaning up
-* Viewing differences::         Viewing differences
-@end menu
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Getting the source
-@subsection Getting the source
-@cindex Getting the source
-@cindex Checking out source
-@cindex Fetching source
-@cindex Source, getting from CVS
-@cindex Checkout, example
-
-The first thing you must do is to get your own working copy of the
-source for @samp{tc}.  For this, you use the @code{checkout} command:
-
-@example
-$ cvs checkout tc
-@end example
-
-@noindent
-This will create a new directory called @file{tc} and populate it with
-the source files.
-
-@example
-$ cd tc
-$ ls
-CVS         Makefile    backend.c   driver.c    frontend.c  parser.c
-@end example
-
-The @file{CVS} directory is used internally by
-@sc{cvs}.  Normally, you should not modify or remove
-any of the files in it.
-
-You start your favorite editor, hack away at @file{backend.c}, and a couple
-of hours later you have added an optimization pass to the compiler.
-A note to @sc{rcs} and @sc{sccs} users: There is no need to lock the files that
-you want to edit.  @xref{Multiple developers}, for an explanation.
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Committing your changes
-@subsection Committing your changes
-@cindex Committing changes to files
-@cindex Log message entry
-
-When you have checked that the compiler is still compilable you decide
-to make a new version of @file{backend.c}.  This will
-store your new @file{backend.c} in the repository and
-make it available to anyone else who is using that same
-repository.
-
-@example
-$ cvs commit backend.c
-@end example
-
-@noindent
-@sc{cvs} starts an editor, to allow you to enter a log
-message.  You type in ``Added an optimization pass.'',
-save the temporary file, and exit the editor.
-
-@cindex CVSEDITOR, environment variable
-@cindex EDITOR, environment variable
-The environment variable @code{$CVSEDITOR} determines
-which editor is started.  If @code{$CVSEDITOR} is not
-set, then if the environment variable @code{$EDITOR} is
-set, it will be used. If both @code{$CVSEDITOR} and
-@code{$EDITOR} are not set then there is a default
-which will vary with your operating system, for example
-@code{vi} for unix or @code{notepad} for Windows
-NT/95.
-
-@cindex VISUAL, environment variable
-In addition, @sc{cvs} checks the @code{$VISUAL} environment
-variable.  Opinions vary on whether this behavior is desirable and
-whether future releases of @sc{cvs} should check @code{$VISUAL} or
-ignore it.  You will be OK either way if you make sure that
-@code{$VISUAL} is either unset or set to the same thing as
-@code{$EDITOR}.
-
-@c This probably should go into some new node
-@c containing detailed info on the editor, rather than
-@c the intro.  In fact, perhaps some of the stuff with
-@c CVSEDITOR and -m and so on should too.
-When @sc{cvs} starts the editor, it includes a list of
-files which are modified.  For the @sc{cvs} client,
-this list is based on comparing the modification time
-of the file against the modification time that the file
-had when it was last gotten or updated.  Therefore, if
-a file's modification time has changed but its contents
-have not, it will show up as modified.  The simplest
-way to handle this is simply not to worry about it---if
-you proceed with the commit @sc{cvs} will detect that
-the contents are not modified and treat it as an
-unmodified file.  The next @code{update} will clue
-@sc{cvs} in to the fact that the file is unmodified,
-and it will reset its stored timestamp so that the file
-will not show up in future editor sessions.
-@c FIXCVS: Might be nice if "commit" and other commands
-@c would reset that timestamp too, but currently commit
-@c doesn't.
-@c FIXME: Need to talk more about the process of
-@c prompting for the log message.  Like show an example
-@c of what it pops up in the editor, for example.  Also
-@c a discussion of how to get the "a)bort, c)ontinue,
-@c e)dit" prompt and what to do with it.  Might also
-@c work in the suggestion that if you want a diff, you
-@c should make it before running commit (someone
-@c suggested that the diff pop up in the editor.  I'm
-@c not sure that is better than telling people to run
-@c "cvs diff" first if that is what they want, but if
-@c we want to tell people that, the manual possibly
-@c should say it).
-
-If you want to avoid
-starting an editor you can specify the log message on
-the command line using the @samp{-m} flag instead, like
-this:
-
-@example
-$ cvs commit -m "Added an optimization pass" backend.c
-@end example
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Cleaning up
-@subsection Cleaning up
-@cindex Cleaning up
-@cindex Working copy, removing
-@cindex Removing your working copy
-@cindex Releasing your working copy
-
-Before you turn to other tasks you decide to remove your working copy of
-tc.  One acceptable way to do that is of course
-
-@example
-$ cd ..
-$ rm -r tc
-@end example
-
-@noindent
-but a better way is to use the @code{release} command (@pxref{release}):
-
-@example
-$ cd ..
-$ cvs release -d tc
-M driver.c
-? tc
-You have [1] altered files in this repository.
-Are you sure you want to release (and delete) directory `tc': n
-** `release' aborted by user choice.
-@end example
-
-The @code{release} command checks that all your modifications have been
-committed.  If history logging is enabled it also makes a note in the
-history file.  @xref{history file}.
-
-When you use the @samp{-d} flag with @code{release}, it
-also removes your working copy.
-
-In the example above, the @code{release} command wrote a couple of lines
-of output.  @samp{? tc} means that the file @file{tc} is unknown to @sc{cvs}.
-That is nothing to worry about: @file{tc} is the executable compiler,
-and it should not be stored in the repository.  @xref{cvsignore},
-for information about how to make that warning go away.
-@xref{release output}, for a complete explanation of
-all possible output from @code{release}.
-
-@samp{M driver.c} is more serious.  It means that the
-file @file{driver.c} has been modified since it was
-checked out.
-
-The @code{release} command always finishes by telling
-you how many modified files you have in your working
-copy of the sources, and then asks you for confirmation
-before deleting any files or making any note in the
-history file.
-
-You decide to play it safe and answer @kbd{n @key{RET}}
-when @code{release} asks for confirmation.
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Viewing differences
-@subsection Viewing differences
-@cindex Viewing differences
-@cindex Diff
-
-You do not remember modifying @file{driver.c}, so you want to see what
-has happened to that file.
-
-@example
-$ cd tc
-$ cvs diff driver.c
-@end example
-
-This command runs @code{diff} to compare the version of @file{driver.c}
-that you checked out with your working copy.  When you see the output
-you remember that you added a command line option that enabled the
-optimization pass.  You check it in, and release the module.
-@c FIXME: we haven't yet defined the term "check in".
-
-@example
-$ cvs commit -m "Added an optimization pass" driver.c
-Checking in driver.c;
-/usr/local/cvsroot/tc/driver.c,v  <--  driver.c
-new revision: 1.2; previous revision: 1.1
-done
-$ cd ..
-$ cvs release -d tc
-? tc
-You have [0] altered files in this repository.
-Are you sure you want to release (and delete) directory `tc': y
-@end example
-
-@c ---------------------------------------------------------------------
-@node Repository
-@chapter The Repository
-@cindex Repository (intro)
-@cindex Repository, example
-@cindex Layout of repository
-@cindex Typical repository
-@cindex /usr/local/cvsroot, as example repository
-@cindex cvsroot
-
-The @sc{cvs} @dfn{repository} stores a complete copy of
-all the files and directories which are under version
-control.
-
-Normally, you never access any of the files in the
-repository directly.  Instead, you use @sc{cvs}
-commands to get your own copy of the files into a
-@dfn{working directory}, and then
-work on that copy.  When you've finished a set of
-changes, you check (or @dfn{commit}) them back into the
-repository.  The repository then contains the changes
-which you have made, as well as recording exactly what
-you changed, when you changed it, and other such
-information.  Note that the repository is not a
-subdirectory of the working directory, or vice versa;
-they should be in separate locations.
-@c Need some example, e.g. repository
-@c /usr/local/cvsroot; working directory
-@c /home/joe/sources.  But this node is too long
-@c as it is; need a little reorganization...
-
-@cindex :local:, setting up
-@sc{cvs} can access a repository by a variety of
-means.  It might be on the local computer, or it might
-be on a computer across the room or across the world.
-To distinguish various ways to access a repository, the
-repository name can start with an @dfn{access method}.
-For example, the access method @code{:local:} means to
-access a repository directory, so the repository
-@code{:local:/usr/local/cvsroot} means that the
-repository is in @file{/usr/local/cvsroot} on the
-computer running @sc{cvs}.  For information on other
-access methods, see @ref{Remote repositories}.
-
-@c Can se say this more concisely?  Like by passing
-@c more of the buck to the Remote repositories node?
-If the access method is omitted, then if the repository
-starts with @samp{/}, then @code{:local:} is
-assumed.  If it does not start with @samp{/} then either
-@code{:ext:} or @code{:server:} is assumed.  For
-example, if you have a local repository in
-@file{/usr/local/cvsroot}, you can use
-@code{/usr/local/cvsroot} instead of
-@code{:local:/usr/local/cvsroot}.  But if (under
-Windows NT, for example) your local repository is
-@file{c:\src\cvsroot}, then you must specify the access
-method, as in @code{:local:c:/src/cvsroot}.
-
-@c This might appear to go in Repository storage, but
-@c actually it is describing something which is quite
-@c user-visible, when you do a "cvs co CVSROOT".  This
-@c isn't necessary the perfect place for that, though.
-The repository is split in two parts.  @file{$CVSROOT/CVSROOT} contains
-administrative files for @sc{cvs}.  The other directories contain the actual
-user-defined modules.
-
-@menu
-* Specifying a repository::     Telling CVS where your repository is
-* Repository storage::          The structure of the repository
-* Working directory storage::   The structure of working directories
-* Intro administrative files::  Defining modules
-* Multiple repositories::       Multiple repositories
-* Creating a repository::       Creating a repository
-* Backing up::                  Backing up a repository
-* Moving a repository::         Moving a repository
-* Remote repositories::         Accessing repositories on remote machines
-* Read-only access::            Granting read-only access to the repository
-* Server temporary directory::  The server creates temporary directories
-@end menu
-
-@node Specifying a repository
-@section Telling CVS where your repository is
-
-There are several ways to tell @sc{cvs}
-where to find the repository.  You can name the
-repository on the command line explicitly, with the
-@code{-d} (for "directory") option:
-
-@example
-cvs -d /usr/local/cvsroot checkout yoyodyne/tc
-@end example
-
-@cindex .profile, setting CVSROOT in
-@cindex .cshrc, setting CVSROOT in
-@cindex .tcshrc, setting CVSROOT in
-@cindex .bashrc, setting CVSROOT in
-@cindex CVSROOT, environment variable
-        Or you can set the @code{$CVSROOT} environment
-variable to an absolute path to the root of the
-repository, @file{/usr/local/cvsroot} in this example.
-To set @code{$CVSROOT}, @code{csh} and @code{tcsh}
-users should have this line in their @file{.cshrc} or
-@file{.tcshrc} files:
-
-@example
-setenv CVSROOT /usr/local/cvsroot
-@end example
-
-@noindent
-@code{sh} and @code{bash} users should instead have these lines in their
-@file{.profile} or @file{.bashrc}:
-
-@example
-CVSROOT=/usr/local/cvsroot
-export CVSROOT
-@end example
-
-@cindex Root file, in CVS directory
-@cindex CVS/Root file
-        A repository specified with @code{-d} will
-override the @code{$CVSROOT} environment variable.
-Once you've checked a working copy out from the
-repository, it will remember where its repository is
-(the information is recorded in the
-@file{CVS/Root} file in the working copy).
-
-The @code{-d} option and the @file{CVS/Root} file both
-override the @code{$CVSROOT} environment variable.  If
-@code{-d} option differs from @file{CVS/Root}, the
-former is used.  Of course, for proper operation they
-should be two ways of referring to the same repository.
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Repository storage
-@section How data is stored in the repository
-@cindex Repository, how data is stored
-
-For most purposes it isn't important @emph{how}
-@sc{cvs} stores information in the repository.  In
-fact, the format has changed in the past, and is likely
-to change in the future.  Since in almost all cases one
-accesses the repository via @sc{cvs} commands, such
-changes need not be disruptive.
-
-However, in some cases it may be necessary to
-understand how @sc{cvs} stores data in the repository,
-for example you might need to track down @sc{cvs} locks
-(@pxref{Concurrency}) or you might need to deal with
-the file permissions appropriate for the repository.
-
-@menu
-* Repository files::            What files are stored in the repository
-* File permissions::            File permissions
-* Windows permissions::         Issues specific to Windows
-* Attic::                       Some files are stored in the Attic
-* CVS in repository::           Additional information in CVS directory
-* Locks::                       CVS locks control concurrent accesses
-* CVSROOT storage::             A few things about CVSROOT are different
-@end menu
-
-@node Repository files
-@subsection Where files are stored within the repository
-
-@c @cindex Filenames, legal
-@c @cindex Legal filenames
-@c Somewhere we need to say something about legitimate
-@c characters in filenames in working directory and
-@c repository.  Not "/" (not even on non-unix).  And
-@c here is a specific set of issues:
-@c     Files starting with a - are handled inconsistently. They can not
-@c   be added to a repository with an add command, because it they are
-@c   interpreted as a switch. They can appear in a repository if they are
-@c   part of a tree that is imported. They can not be removed from the tree
-@c   once they are there.
-@c Note that "--" *is* supported (as a
-@c consequence of using GNU getopt).  Should document
-@c this somewhere ("Common options"?).  The other usual technique,
-@c "./-foo", isn't as effective, at least for "cvs add"
-@c which doesn't support pathnames containing "/".
-
-The overall structure of the repository is a directory
-tree corresponding to the directories in the working
-directory.  For example, supposing the repository is in
-
-@example
-/usr/local/cvsroot
-@end example
-
-@noindent
-here is a possible directory tree (showing only the
-directories):
-
-@example
-@t{/usr}
- |
- +--@t{local}
- |   |
- |   +--@t{cvsroot}
- |   |    |
- |   |    +--@t{CVSROOT}
-          |      (administrative files)
-          |
-          +--@t{gnu}
-          |   |
-          |   +--@t{diff}
-          |   |   (source code to @sc{gnu} diff)
-          |   |
-          |   +--@t{rcs}
-          |   |   (source code to @sc{rcs})
-          |   |
-          |   +--@t{cvs}
-          |       (source code to @sc{cvs})
-          |
-          +--@t{yoyodyne}
-              |
-              +--@t{tc}
-              |    |
-              |    +--@t{man}
-              |    |
-              |    +--@t{testing}
-              |
-              +--(other Yoyodyne software)
-@end example
-
-With the directories are @dfn{history files} for each file
-under version control.  The name of the history file is
-the name of the corresponding file with @samp{,v}
-appended to the end.  Here is what the repository for
-the @file{yoyodyne/tc} directory might look like:
-@c FIXME: Should also mention CVS (CVSREP)
-@c FIXME? Should we introduce Attic with an xref to
-@c Attic?  Not sure whether that is a good idea or not.
-@example
-  @code{$CVSROOT}
-    |
-    +--@t{yoyodyne}
-    |   |
-    |   +--@t{tc}
-    |   |   |
-            +--@t{Makefile,v}
-            +--@t{backend.c,v}
-            +--@t{driver.c,v}
-            +--@t{frontend.c,v}
-            +--@t{parser.c,v}
-            +--@t{man}
-            |    |
-            |    +--@t{tc.1,v}
-            |
-            +--@t{testing}
-                 |
-                 +--@t{testpgm.t,v}
-                 +--@t{test2.t,v}
-@end example
-
-@cindex History files
-@cindex RCS history files
-@c The first sentence, about what history files
-@c contain, is kind of redundant with our intro to what the
-@c repository does in node Repository....
-The history files contain, among other things, enough
-information to recreate any revision of the file, a log
-of all commit messages and the user-name of the person
-who committed the revision.  The history files are
-known as @dfn{RCS files}, because the first program to
-store files in that format was a version control system
-known as @sc{rcs}.  For a full
-description of the file format, see the @code{man} page
-@cite{rcsfile(5)}, distributed with @sc{rcs}, or the
-file @file{doc/RCSFILES} in the @sc{cvs} source
-distribution.  This
-file format has become very common---many systems other
-than @sc{cvs} or @sc{rcs} can at least import history
-files in this format.
-@c FIXME: Think about including documentation for this
-@c rather than citing it?  In the long run, getting
-@c this to be a standard (not sure if we can cope with
-@c a standards process as formal as IEEE/ANSI/ISO/etc,
-@c though...) is the way to go, so maybe citing is
-@c better.
-
-The @sc{rcs} files used in @sc{cvs} differ in a few
-ways from the standard format.  The biggest difference
-is magic branches; for more information see @ref{Magic
-branch numbers}.  Also in @sc{cvs} the valid tag names
-are a subset of what @sc{rcs} accepts; for @sc{cvs}'s
-rules see @ref{Tags}.
-
-@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
-@node File permissions
-@subsection File permissions
-@c -- Move this to @node Creating a repository or similar
-@cindex Security, file permissions in repository
-@cindex File permissions, general
-@cindex Permissions, general
-@c FIXME: we need to somehow reflect "permissions in
-@c repository" versus "permissions in working
-@c directory" in the index entries.
-@cindex Group, UNIX file permissions, in repository
-@cindex Read-only files, in repository
-All @samp{,v} files are created read-only, and you
-should not change the permission of those files.  The
-directories inside the repository should be writable by
-the persons that have permission to modify the files in
-each directory.  This normally means that you must
-create a UNIX group (see group(5)) consisting of the
-persons that are to edit the files in a project, and
-set up the repository so that it is that group that
-owns the directory.
-(On some systems, you also need to set the set-group-ID-on-execution bit
-on the repository directories (see chmod(1)) so that newly-created files
-and directories get the group-ID of the parent directory rather than
-that of the current process.)
-
-@c See also comment in commitinfo node regarding cases
-@c which are really awkward with unix groups.
-
-This means that you can only control access to files on
-a per-directory basis.
-
-Note that users must also have write access to check
-out files, because @sc{cvs} needs to create lock files
-(@pxref{Concurrency}).  You can use LockDir in CVSROOT/config
-to put the lock files somewhere other than in the repository
-if you want to allow read-only access to some directories
-(@pxref{config}).
-
-@c CVS seems to use CVSUMASK in picking permissions for
-@c val-tags, but maybe we should say more about this.
-@c Like val-tags gets created by someone who doesn't
-@c have CVSUMASK set right?
-@cindex CVSROOT/val-tags file, and read-only access to projects
-@cindex val-tags file, and read-only access to projects
-Also note that users must have write access to the
-@file{CVSROOT/val-tags} file.  @sc{cvs} uses it to keep
-track of what tags are valid tag names (it is sometimes
-updated when tags are used, as well as when they are
-created).
-
-Each @sc{rcs} file will be owned by the user who last
-checked it in.  This has little significance; what
-really matters is who owns the directories.
-
-@cindex CVSUMASK, environment variable
-@cindex Umask, for repository files
-@sc{cvs} tries to set up reasonable file permissions
-for new directories that are added inside the tree, but
-you must fix the permissions manually when a new
-directory should have different permissions than its
-parent directory.  If you set the @code{CVSUMASK}
-environment variable that will control the file
-permissions which @sc{cvs} uses in creating directories
-and/or files in the repository.  @code{CVSUMASK} does
-not affect the file permissions in the working
-directory; such files have the permissions which are
-typical for newly created files, except that sometimes
-@sc{cvs} creates them read-only (see the sections on
-watches, @ref{Setting a watch}; -r, @ref{Global
-options}; or @code{CVSREAD}, @ref{Environment variables}).
-@c FIXME: Need more discussion of which
-@c group should own the file in the repository.
-@c Include a somewhat detailed example of the usual
-@c case where CVSUMASK is 007, the developers are all
-@c in a group, and that group owns stuff in the
-@c repository.  Need to talk about group ownership of
-@c newly-created directories/files (on some unices,
-@c such as SunOS4, setting the setgid bit on the
-@c directories will make files inherit the directory's
-@c group.  On other unices, your mileage may vary.  I
-@c can't remember what POSIX says about this, if
-@c anything).
-
-Note that using the client/server @sc{cvs}
-(@pxref{Remote repositories}), there is no good way to
-set @code{CVSUMASK}; the setting on the client machine
-has no effect.  If you are connecting with @code{rsh}, you
-can set @code{CVSUMASK} in @file{.bashrc} or @file{.cshrc}, as
-described in the documentation for your operating
-system.  This behavior might change in future versions
-of @sc{cvs}; do not rely on the setting of
-@code{CVSUMASK} on the client having no effect.
-@c FIXME: need to explain what a umask is or cite
-@c someplace which does.
-@c
-@c There is also a larger (largely separate) issue
-@c about the meaning of CVSUMASK in a non-unix context.
-@c For example, whether there is
-@c an equivalent which fits better into other
-@c protection schemes like POSIX.6, VMS, &c.
-@c
-@c FIXME: Need one place which discusses this
-@c read-only files thing.  Why would one use -r or
-@c CVSREAD?  Why would one use watches?  How do they
-@c interact?
-@c
-@c FIXME: We need to state
-@c whether using CVSUMASK removes the need for manually
-@c fixing permissions (in fact, if we are going to mention
-@c manually fixing permission, we better document a lot
-@c better just what we mean by "fix").
-
-Using pserver, you will generally need stricter
-permissions on the @sc{cvsroot} directory and
-directories above it in the tree; see @ref{Password
-authentication security}.
-
-@cindex Setuid
-@cindex Setgid
-@cindex Security, setuid
-@cindex Installed images (VMS)
-Some operating systems have features which allow a
-particular program to run with the ability to perform
-operations which the caller of the program could not.
-For example, the set user ID (setuid) or set group ID
-(setgid) features of unix or the installed image
-feature of VMS.  @sc{cvs} was not written to use such
-features and therefore attempting to install @sc{cvs} in
-this fashion will provide protection against only
-accidental lapses; anyone who is trying to circumvent
-the measure will be able to do so, and depending on how
-you have set it up may gain access to more than just
-@sc{cvs}.  You may wish to instead consider pserver.  It
-shares some of the same attributes, in terms of
-possibly providing a false sense of security or opening
-security holes wider than the ones you are trying to
-fix, so read the documentation on pserver security
-carefully if you are considering this option
-(@ref{Password authentication security}).
-
-@node Windows permissions
-@subsection File Permission issues specific to Windows
-@cindex Windows, and permissions
-@cindex File permissions, Windows-specific
-@cindex Permissions, Windows-specific
-
-Some file permission issues are specific to Windows
-operating systems (Windows 95, Windows NT, and
-presumably future operating systems in this family.
-Some of the following might apply to OS/2 but I'm not
-sure).
-
-If you are using local @sc{cvs} and the repository is on a
-networked file system which is served by the Samba SMB
-server, some people have reported problems with
-permissions.  Enabling WRITE=YES in the samba
-configuration is said to fix/workaround it.
-Disclaimer: I haven't investigated enough to know the
-implications of enabling that option, nor do I know
-whether there is something which @sc{cvs} could be doing
-differently in order to avoid the problem.  If you find
-something out, please let us know as described in
-@ref{BUGS}.
-
-@node Attic
-@subsection The attic
-@cindex Attic
-
-You will notice that sometimes @sc{cvs} stores an
-@sc{rcs} file in the @code{Attic}.  For example, if the
-@sc{cvsroot} is @file{/usr/local/cvsroot} and we are
-talking about the file @file{backend.c} in the
-directory @file{yoyodyne/tc}, then the file normally
-would be in
-
-@example
-/usr/local/cvsroot/yoyodyne/tc/backend.c,v
-@end example
-
-@noindent
-but if it goes in the attic, it would be in
-
-@example
-/usr/local/cvsroot/yoyodyne/tc/Attic/backend.c,v
-@end example
-
-@noindent
-@cindex Dead state
-instead.  It should not matter from a user point of
-view whether a file is in the attic; @sc{cvs} keeps
-track of this and looks in the attic when it needs to.
-But in case you want to know, the rule is that the RCS
-file is stored in the attic if and only if the head
-revision on the trunk has state @code{dead}.  A
-@code{dead} state means that file has been removed, or
-never added, for that revision.  For example, if you
-add a file on a branch, it will have a trunk revision
-in @code{dead} state, and a branch revision in a
-non-@code{dead} state.
-@c Probably should have some more concrete examples
-@c here, or somewhere (not sure exactly how we should
-@c arrange the discussion of the dead state, versus
-@c discussion of the attic).
-
-@node CVS in repository
-@subsection The CVS directory in the repository
-@cindex CVS directory, in repository
-
-The @file{CVS} directory in each repository directory
-contains information such as file attributes (in a file
-called @file{CVS/fileattr}.  In the
-future additional files may be added to this directory,
-so implementations should silently ignore additional
-files.
-
-This behavior is implemented only by @sc{cvs} 1.7 and
-later; for details see @ref{Watches Compatibility}.
-
-The format of the @file{fileattr} file is a series of entries
-of the following form (where @samp{@{} and @samp{@}}
-means the text between the braces can be repeated zero
-or more times):
-
-@var{ent-type} @var{filename} <tab> @var{attrname} = @var{attrval}
-  @{; @var{attrname} = @var{attrval}@} <linefeed>
-
-@var{ent-type} is @samp{F} for a file, in which case the entry specifies the
-attributes for that file.
-
-@var{ent-type} is @samp{D},
-and @var{filename} empty, to specify default attributes
-to be used for newly added files.
-
-Other @var{ent-type} are reserved for future expansion.  @sc{cvs} 1.9 and older
-will delete them any time it writes file attributes.
-@sc{cvs} 1.10 and later will preserve them.
-
-Note that the order of the lines is not significant;
-a program writing the fileattr file may
-rearrange them at its convenience.
-
-There is currently no way of quoting tabs or line feeds in the
-filename, @samp{=} in @var{attrname},
-@samp{;} in @var{attrval}, etc.  Note: some implementations also
-don't handle a NUL character in any of the fields, but
-implementations are encouraged to allow it.
-
-By convention, @var{attrname} starting with @samp{_} is for an attribute given
-special meaning by @sc{cvs}; other @var{attrname}s are for user-defined attributes
-(or will be, once implementations start supporting user-defined attributes).
-
-Built-in attributes:
-
-@table @code
-@item _watched
-Present means the file is watched and should be checked out
-read-only.
-
-@item _watchers
-Users with watches for this file.  Value is
-@var{watcher} > @var{type} @{ , @var{watcher} > @var{type} @}
-where @var{watcher} is a username, and @var{type}
-is zero or more of edit,unedit,commit separated by
-@samp{+} (that is, nothing if none; there is no "none" or "all" keyword).
-
-@item _editors
-Users editing this file.  Value is
-@var{editor} > @var{val} @{ , @var{editor} > @var{val} @}
-where @var{editor} is a username, and @var{val} is
-@var{time}+@var{hostname}+@var{pathname}, where
-@var{time} is when the @code{cvs edit} command (or
-equivalent) happened,
-and @var{hostname} and @var{pathname} are for the working directory.
-@end table
-
-Example:
-
-@c FIXME: sanity.sh should contain a similar test case
-@c so we can compare this example from something from
-@c Real Life(TM).  See cvsclient.texi (under Notify) for more
-@c discussion of the date format of _editors.
-@example
-Ffile1 _watched=;_watchers=joe>edit,mary>commit
-Ffile2 _watched=;_editors=sue>8 Jan 1975+workstn1+/home/sue/cvs
-D _watched=
-@end example
-
-@noindent
-means that the file @file{file1} should be checked out
-read-only.  Furthermore, joe is watching for edits and
-mary is watching for commits.  The file @file{file2}
-should be checked out read-only; sue started editing it
-on 8 Jan 1975 in the directory @file{/home/sue/cvs} on
-the machine @code{workstn1}.  Future files which are
-added should be checked out read-only.  To represent
-this example here, we have shown a space after
-@samp{D}, @samp{Ffile1}, and @samp{Ffile2}, but in fact
-there must be a single tab character there and no spaces.
-
-@node Locks
-@subsection CVS locks in the repository
-
-@cindex #cvs.rfl, technical details
-@cindex #cvs.pfl, technical details
-@cindex #cvs.wfl, technical details
-@cindex #cvs.lock, technical details
-@cindex Locks, cvs, technical details
-For an introduction to @sc{cvs} locks focusing on
-user-visible behavior, see @ref{Concurrency}.  The
-following section is aimed at people who are writing
-tools which want to access a @sc{cvs} repository without
-interfering with other tools accessing the same
-repository.  If you find yourself confused by concepts
-described here, like @dfn{read lock}, @dfn{write lock},
-and @dfn{deadlock}, you might consult the literature on
-operating systems or databases.
-
-@cindex #cvs.tfl
-Any file in the repository with a name starting
-with @file{#cvs.rfl.} is a read lock.  Any file in
-the repository with a name starting with
-@file{#cvs.pfl} is a promotable read lock.  Any file in
-the repository with a name starting with
-@file{#cvs.wfl} is a write lock.  Old versions of @sc{cvs}
-(before @sc{cvs} 1.5) also created files with names starting
-with @file{#cvs.tfl}, but they are not discussed here.
-The directory @file{#cvs.lock} serves as a master
-lock.  That is, one must obtain this lock first before
-creating any of the other locks.
-
-To obtain a read lock, first create the @file{#cvs.lock}
-directory.  This operation must be atomic (which should
-be true for creating a directory under most operating
-systems).  If it fails because the directory already
-existed, wait for a while and try again.  After
-obtaining the @file{#cvs.lock} lock, create a file
-whose name is @file{#cvs.rfl.} followed by information
-of your choice (for example, hostname and process
-identification number).  Then remove the
-@file{#cvs.lock} directory to release the master lock.
-Then proceed with reading the repository.  When you are
-done, remove the @file{#cvs.rfl} file to release the
-read lock.
-
-Promotable read locks are a concept you may not find in other literature on
-concurrency.  They are used to allow a two (or more) pass process to only lock
-a file for read on the first (read) pass(es), then upgrade its read locks to
-write locks if necessary for a final pass, still assured that the files have
-not changed since they were first read.  @sc{cvs} uses promotable read locks,
-for example, to prevent commit and tag verification passes from interfering
-with other reading processes.  It can then lock only a single directory at a
-time for write during the write pass.
-
-To obtain a promotable read lock, first create the @file{#cvs.lock} directory,
-as with a non-promotable read lock.  Then check
-that there are no files that start with
-@file{#cvs.pfl}.  If there are, remove the master @file{#cvs.lock} directory,
-wait awhile (CVS waits 30 seconds between lock attempts), and try again.  If
-there are no other promotable locks, go ahead and create a file whose name is
-@file{#cvs.pfl} followed by information of your choice (for example, CVS uses
-its hostname and the process identification number of the CVS server process
-creating the lock).  If versions of @sc{cvs} older than version 1.12.4 access
-your repository directly (not via a @sc{cvs} server of version 1.12.4 or
-later), then you should also create a read lock since older versions of CVS
-will ignore the promotable lock when attempting to create their own write lock.
-Then remove the master @file{#cvs.lock} directory in order to allow other
-processes to obtain read locks.
-
-To obtain a write lock, first create the
-@file{#cvs.lock} directory, as with read locks.  Then
-check that there are no files whose names start with
-@file{#cvs.rfl.} and no files whose names start with @file{#cvs.pfl} that are
-not owned by the process attempting to get the write lock.  If either exist,
-remove @file{#cvs.lock}, wait for a while, and try again.  If
-there are no readers or promotable locks from other processes, then create a
-file whose name is @file{#cvs.wfl} followed by information of your choice
-(again, CVS uses the hostname and server process identification
-number).  Remove your @file{#cvs.pfl} file if present.  Hang on to the
-@file{#cvs.lock} lock.  Proceed
-with writing the repository.  When you are done, first
-remove the @file{#cvs.wfl} file and then the
-@file{#cvs.lock} directory. Note that unlike the
-@file{#cvs.rfl} file, the @file{#cvs.wfl} file is just
-informational; it has no effect on the locking operation
-beyond what is provided by holding on to the
-@file{#cvs.lock} lock itself.
-
-Note that each lock (write lock or read lock) only locks
-a single directory in the repository, including
-@file{Attic} and @file{CVS} but not including
-subdirectories which represent other directories under
-version control.  To lock an entire tree, you need to
-lock each directory (note that if you fail to obtain
-any lock you need, you must release the whole tree
-before waiting and trying again, to avoid deadlocks).
-
-Note also that @sc{cvs} expects write locks to control
-access to individual @file{foo,v} files.  @sc{rcs} has
-a scheme where the @file{,foo,} file serves as a lock,
-but @sc{cvs} does not implement it and so taking out a
-@sc{cvs} write lock is recommended.  See the comments at
-rcs_internal_lockfile in the @sc{cvs} source code for
-further discussion/rationale.
-
-@node CVSROOT storage
-@subsection How files are stored in the CVSROOT directory
-@cindex CVSROOT, storage of files
-
-The @file{$CVSROOT/CVSROOT} directory contains the
-various administrative files.  In some ways this
-directory is just like any other directory in the
-repository; it contains @sc{rcs} files whose names end
-in @samp{,v}, and many of the @sc{cvs} commands operate
-on it the same way.  However, there are a few
-differences.
-
-For each administrative file, in addition to the
-@sc{rcs} file, there is also a checked out copy of the
-file.  For example, there is an @sc{rcs} file
-@file{loginfo,v} and a file @file{loginfo} which
-contains the latest revision contained in
-@file{loginfo,v}.  When you check in an administrative
-file, @sc{cvs} should print
-
-@example
-cvs commit: Rebuilding administrative file database
-@end example
-
-@noindent
-and update the checked out copy in
-@file{$CVSROOT/CVSROOT}.  If it does not, there is
-something wrong (@pxref{BUGS}).  To add your own files
-to the files to be updated in this fashion, you can add
-them to the @file{checkoutlist} administrative file
-(@pxref{checkoutlist}).
-
-@cindex modules.db
-@cindex modules.pag
-@cindex modules.dir
-By default, the @file{modules} file behaves as
-described above.  If the modules file is very large,
-storing it as a flat text file may make looking up
-modules slow (I'm not sure whether this is as much of a
-concern now as when @sc{cvs} first evolved this
-feature; I haven't seen benchmarks).  Therefore, by
-making appropriate edits to the @sc{cvs} source code
-one can store the modules file in a database which
-implements the @code{ndbm} interface, such as Berkeley
-db or GDBM.  If this option is in use, then the modules
-database will be stored in the files @file{modules.db},
-@file{modules.pag}, and/or @file{modules.dir}.
-@c I think fileattr also will use the database stuff.
-@c Anything else?
-
-For information on the meaning of the various
-administrative files, see @ref{Administrative files}.
-
-@node Working directory storage
-@section How data is stored in the working directory
-
-@c FIXME: Somewhere we should discuss timestamps (test
-@c case "stamps" in sanity.sh).  But not here.  Maybe
-@c in some kind of "working directory" chapter which
-@c would encompass the "Builds" one?  But I'm not sure
-@c whether that is a good organization (is it based on
-@c what the user wants to do?).
-
-@cindex CVS directory, in working directory
-While we are discussing @sc{cvs} internals which may
-become visible from time to time, we might as well talk
-about what @sc{cvs} puts in the @file{CVS} directories
-in the working directories.  As with the repository,
-@sc{cvs} handles this information and one can usually
-access it via @sc{cvs} commands.  But in some cases it
-may be useful to look at it, and other programs, such
-as the @code{jCVS} graphical user interface or the
-@code{VC} package for emacs, may need to look at it.
-Such programs should follow the recommendations in this
-section if they hope to be able to work with other
-programs which use those files, including future
-versions of the programs just mentioned and the
-command-line @sc{cvs} client.
-
-The @file{CVS} directory contains several files.
-Programs which are reading this directory should
-silently ignore files which are in the directory but
-which are not documented here, to allow for future
-expansion.
-
-The files are stored according to the text file
-convention for the system in question.  This means that
-working directories are not portable between systems
-with differing conventions for storing text files.
-This is intentional, on the theory that the files being
-managed by @sc{cvs} probably will not be portable between
-such systems either.
-
-@table @file
-@item Root
-This file contains the current @sc{cvs} root, as
-described in @ref{Specifying a repository}.
-
-@cindex Repository file, in CVS directory
-@cindex CVS/Repository file
-@item Repository
-This file contains the directory within the repository
-which the current directory corresponds with.  It can
-be either an absolute pathname or a relative pathname;
-@sc{cvs} has had the ability to read either format
-since at least version 1.3 or so.  The relative
-pathname is relative to the root, and is the more
-sensible approach, but the absolute pathname is quite
-common and implementations should accept either.  For
-example, after the command
-
-@example
-cvs -d :local:/usr/local/cvsroot checkout yoyodyne/tc
-@end example
-
-@noindent
-@file{Root} will contain
-
-@example
-:local:/usr/local/cvsroot
-@end example
-
-@noindent
-and @file{Repository} will contain either
-
-@example
-/usr/local/cvsroot/yoyodyne/tc
-@end example
-
-@noindent
-or
-
-@example
-yoyodyne/tc
-@end example
-
-If the particular working directory does not correspond
-to a directory in the repository, then @file{Repository}
-should contain @file{CVSROOT/Emptydir}.
-@cindex Emptydir, in CVSROOT directory
-@cindex CVSROOT/Emptydir directory
-
-@cindex Entries file, in CVS directory
-@cindex CVS/Entries file
-@item Entries
-This file lists the files and directories in the
-working directory.
-The first character of each line indicates what sort of
-line it is.  If the character is unrecognized, programs
-reading the file should silently skip that line, to
-allow for future expansion.
-
-If the first character is @samp{/}, then the format is:
-
-@example
-/@var{name}/@var{revision}/@var{timestamp}[+@var{conflict}]/@var{options}/@var{tagdate}
-@end example
-
-@noindent
-where @samp{[} and @samp{]} are not part of the entry,
-but instead indicate that the @samp{+} and conflict
-marker are optional.  @var{name} is the name of the
-file within the directory.  @var{revision} is the
-revision that the file in the working derives from, or
-@samp{0} for an added file, or @samp{-} followed by a
-revision for a removed file.  @var{timestamp} is the
-timestamp of the file at the time that @sc{cvs} created
-it; if the timestamp differs with the actual
-modification time of the file it means the file has
-been modified.  It is stored in
-the format used by the ISO C asctime() function (for
-example, @samp{Sun Apr  7 01:29:26 1996}).  One may
-write a string which is not in that format, for
-example, @samp{Result of merge}, to indicate that the
-file should always be considered to be modified.  This
-is not a special case; to see whether a file is
-modified a program should take the timestamp of the file
-and simply do a string compare with @var{timestamp}.
-If there was a conflict, @var{conflict} can be set to
-the modification time of the file after the file has been
-written with conflict markers (@pxref{Conflicts example}).
-Thus if @var{conflict} is subsequently the same as the actual
-modification time of the file it means that the user
-has obviously not resolved the conflict.  @var{options}
-contains sticky options (for example @samp{-kb} for a
-binary file).  @var{tagdate} contains @samp{T} followed
-by a tag name, or @samp{D} for a date, followed by a
-sticky tag or date.  Note that if @var{timestamp}
-contains a pair of timestamps separated by a space,
-rather than a single timestamp, you are dealing with a
-version of @sc{cvs} earlier than @sc{cvs} 1.5 (not
-documented here).
-
-The timezone on the timestamp in CVS/Entries (local or
-universal) should be the same as the operating system
-stores for the timestamp of the file itself.  For
-example, on Unix the file's timestamp is in universal
-time (UT), so the timestamp in CVS/Entries should be
-too.  On @sc{vms}, the file's timestamp is in local
-time, so @sc{cvs} on @sc{vms} should use local time.
-This rule is so that files do not appear to be modified
-merely because the timezone changed (for example, to or
-from summer time).
-@c See comments and calls to gmtime() and friends in
-@c src/vers_ts.c (function time_stamp).
-
-If the first character of a line in @file{Entries} is
-@samp{D}, then it indicates a subdirectory.  @samp{D}
-on a line all by itself indicates that the program
-which wrote the @file{Entries} file does record
-subdirectories (therefore, if there is such a line and
-no other lines beginning with @samp{D}, one knows there
-are no subdirectories).  Otherwise, the line looks
-like:
-
-@example
-D/@var{name}/@var{filler1}/@var{filler2}/@var{filler3}/@var{filler4}
-@end example
-
-@noindent
-where @var{name} is the name of the subdirectory, and
-all the @var{filler} fields should be silently ignored,
-for future expansion.  Programs which modify
-@code{Entries} files should preserve these fields.
-
-The lines in the @file{Entries} file can be in any order.
-
-@cindex Entries.Log file, in CVS directory
-@cindex CVS/Entries.Log file
-@item Entries.Log
-This file does not record any information beyond that
-in @file{Entries}, but it does provide a way to update
-the information without having to rewrite the entire
-@file{Entries} file, including the ability to preserve
-the information even if the program writing
-@file{Entries} and @file{Entries.Log} abruptly aborts.
-Programs which are reading the @file{Entries} file
-should also check for @file{Entries.Log}.  If the latter
-exists, they should read @file{Entries} and then apply
-the changes mentioned in @file{Entries.Log}.  After
-applying the changes, the recommended practice is to
-rewrite @file{Entries} and then delete @file{Entries.Log}.
-The format of a line in @file{Entries.Log} is a single
-character command followed by a space followed by a
-line in the format specified for a line in
-@file{Entries}.  The single character command is
-@samp{A} to indicate that the entry is being added,
-@samp{R} to indicate that the entry is being removed,
-or any other character to indicate that the entire line
-in @file{Entries.Log} should be silently ignored (for
-future expansion).  If the second character of the line
-in @file{Entries.Log} is not a space, then it was
-written by an older version of @sc{cvs} (not documented
-here).
-
-Programs which are writing rather than reading can
-safely ignore @file{Entries.Log} if they so choose.
-
-@cindex Entries.Backup file, in CVS directory
-@cindex CVS/Entries.Backup file
-@item Entries.Backup
-This is a temporary file.  Recommended usage is to
-write a new entries file to @file{Entries.Backup}, and
-then to rename it (atomically, where possible) to @file{Entries}.
-
-@cindex Entries.Static file, in CVS directory
-@cindex CVS/Entries.Static file
-@item Entries.Static
-The only relevant thing about this file is whether it
-exists or not.  If it exists, then it means that only
-part of a directory was gotten and @sc{cvs} will
-not create additional files in that directory.  To
-clear it, use the @code{update} command with the
-@samp{-d} option, which will get the additional files
-and remove @file{Entries.Static}.
-@c FIXME: This needs to be better documented, in places
-@c other than Working Directory Storage.
-@c FIXCVS: The fact that this setting exists needs to
-@c be more visible to the user.  For example "cvs
-@c status foo", in the case where the file would be
-@c gotten except for Entries.Static, might say
-@c something to distinguish this from other cases.
-@c One thing that periodically gets suggested is to
-@c have "cvs update" print something when it skips
-@c files due to Entries.Static, but IMHO that kind of
-@c noise pretty much makes the Entries.Static feature
-@c useless.
-
-@cindex Tag file, in CVS directory
-@cindex CVS/Tag file
-@cindex Sticky tags/dates, per-directory
-@cindex Per-directory sticky tags/dates
-@item Tag
-This file contains per-directory sticky tags or dates.
-The first character is @samp{T} for a branch tag,
-@samp{N} for a non-branch tag, or @samp{D} for a date,
-or another character to mean the file should be
-silently ignored, for future expansion.  This character
-is followed by the tag or date.  Note that
-per-directory sticky tags or dates are used for things
-like applying to files which are newly added; they
-might not be the same as the sticky tags or dates on
-individual files.  For general information on sticky
-tags and dates, see @ref{Sticky tags}.
-@c FIXME: This needs to be much better documented,
-@c preferably not in the context of "working directory
-@c storage".
-@c FIXME: The Sticky tags node needs to discuss, or xref to
-@c someplace which discusses, per-directory sticky
-@c tags and the distinction with per-file sticky tags.
-
-@cindex Notify file, in CVS directory
-@cindex CVS/Notify file
-@item Notify
-This file stores notifications (for example, for
-@code{edit} or @code{unedit}) which have not yet been
-sent to the server.  Its format is not yet documented
-here.
-
-@cindex Notify.tmp file, in CVS directory
-@cindex CVS/Notify.tmp file
-@item Notify.tmp
-This file is to @file{Notify} as @file{Entries.Backup}
-is to @file{Entries}.  That is, to write @file{Notify},
-first write the new contents to @file{Notify.tmp} and
-then (atomically where possible), rename it to
-@file{Notify}.
-
-@cindex Base directory, in CVS directory
-@cindex CVS/Base directory
-@item Base
-If watches are in use, then an @code{edit} command
-stores the original copy of the file in the @file{Base}
-directory.  This allows the @code{unedit} command to
-operate even if it is unable to communicate with the
-server.
-
-@cindex Baserev file, in CVS directory
-@cindex CVS/Baserev file
-@item Baserev
-The file lists the revision for each of the files in
-the @file{Base} directory.  The format is:
-
-@example
-B@var{name}/@var{rev}/@var{expansion}
-@end example
-
-@noindent
-where @var{expansion} should be ignored, to allow for
-future expansion.
-
-@cindex Baserev.tmp file, in CVS directory
-@cindex CVS/Baserev.tmp file
-@item Baserev.tmp
-This file is to @file{Baserev} as @file{Entries.Backup}
-is to @file{Entries}.  That is, to write @file{Baserev},
-first write the new contents to @file{Baserev.tmp} and
-then (atomically where possible), rename it to
-@file{Baserev}.
-
-@cindex Template file, in CVS directory
-@cindex CVS/Template file
-@item Template
-This file contains the template specified by the
-@file{rcsinfo} file (@pxref{rcsinfo}).  It is only used
-by the client; the non-client/server @sc{cvs} consults
-@file{rcsinfo} directly.
-@end table
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Intro administrative files
-@section The administrative files
-@cindex Administrative files (intro)
-@cindex Modules file
-@cindex CVSROOT, module name
-@cindex Defining modules (intro)
-
-@c FIXME: this node should be reorganized into "general
-@c information about admin files" and put the "editing
-@c admin files" stuff up front rather than jumping into
-@c the details of modules right away.  Then the
-@c Administrative files node can go away, the information
-@c on each admin file distributed to a place appropriate
-@c to its function, and this node can contain a table
-@c listing each file and a @ref to its detailed description.
-
-The directory @file{$CVSROOT/CVSROOT} contains some @dfn{administrative
-files}.  @xref{Administrative files}, for a complete description.
-You can use @sc{cvs} without any of these files, but
-some commands work better when at least the
-@file{modules} file is properly set up.
-
-The most important of these files is the @file{modules}
-file.  It defines all modules in the repository.  This
-is a sample @file{modules} file.
-
-@c FIXME: The CVSROOT line is a goofy example now that
-@c mkmodules doesn't exist.
-@example
-CVSROOT         CVSROOT
-modules         CVSROOT modules
-cvs             gnu/cvs
-rcs             gnu/rcs
-diff            gnu/diff
-tc              yoyodyne/tc
-@end example
-
-The @file{modules} file is line oriented.  In its
-simplest form each line contains the name of the
-module, whitespace, and the directory where the module
-resides.  The directory is a path relative to
-@code{$CVSROOT}.  The last four lines in the example
-above are examples of such lines.
-
-@c FIXME: might want to introduce the concept of options in modules file
-@c (the old example which was here, -i mkmodules, is obsolete).
-
-The line that defines the module called @samp{modules}
-uses features that are not explained here.
-@xref{modules}, for a full explanation of all the
-available features.
-
-@c FIXME: subsection without node is bogus
-@subsection Editing administrative files
-@cindex Editing administrative files
-@cindex Administrative files, editing them
-
-You edit the administrative files in the same way that you would edit
-any other module.  Use @samp{cvs checkout CVSROOT} to get a working
-copy, edit it, and commit your changes in the normal way.
-
-It is possible to commit an erroneous administrative
-file.  You can often fix the error and check in a new
-revision, but sometimes a particularly bad error in the
-administrative file makes it impossible to commit new
-revisions.
-@c @xref{Bad administrative files} for a hint
-@c about how to solve such situations.
-@c -- administrative file checking--
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Multiple repositories
-@section Multiple repositories
-@cindex Multiple repositories
-@cindex Repositories, multiple
-@cindex Many repositories
-@cindex Parallel repositories
-@cindex Disjoint repositories
-@cindex CVSROOT, multiple repositories
-
-In some situations it is a good idea to have more than
-one repository, for instance if you have two
-development groups that work on separate projects
-without sharing any code.  All you have to do to have
-several repositories is to specify the appropriate
-repository, using the @code{CVSROOT} environment
-variable, the @samp{-d} option to @sc{cvs}, or (once
-you have checked out a working directory) by simply
-allowing @sc{cvs} to use the repository that was used
-to check out the working directory
-(@pxref{Specifying a repository}).
-
-The big advantage of having multiple repositories is
-that they can reside on different servers.  With @sc{cvs}
-version 1.10, a single command cannot recurse into
-directories from different repositories.  With development
-versions of @sc{cvs}, you can check out code from multiple
-servers into your working directory.  @sc{cvs} will
-recurse and handle all the details of making
-connections to as many server machines as necessary to
-perform the requested command.  Here is an example of
-how to set up a working directory:
-
-@example
-cvs -d server1:/cvs co dir1
-cd dir1
-cvs -d server2:/root co sdir
-cvs update
-@end example
-
-The @code{cvs co} commands set up the working
-directory, and then the @code{cvs update} command will
-contact server2, to update the dir1/sdir subdirectory,
-and server1, to update everything else.
-
-@c FIXME: Does the FAQ have more about this?  I have a
-@c dim recollection, but I'm too lazy to check right now.
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Creating a repository
-@section Creating a repository
-
-@cindex Repository, setting up
-@cindex Creating a repository
-@cindex Setting up a repository
-
-This section describes how to set up a @sc{cvs} repository for any
-sort of access method.  After completing the setup described in this
-section, you should be able to access your @sc{cvs} repository immediately
-via the local access method and several remote access methods.  For
-more information on setting up remote access to the repository you create
-in this section, please read the section on @xref{Remote repositories}.
-
-To set up a @sc{cvs} repository, first choose the
-machine and disk on which you want to store the
-revision history of the source files.  CPU and memory
-requirements are modest, so most machines should be
-adequate.  For details see @ref{Server requirements}.
-@c Possible that we should be providing a quick rule of
-@c thumb, like the 32M memory for the server.  That
-@c might increase the number of people who are happy
-@c with the answer, without following the xref.
-
-To estimate disk space
-requirements, if you are importing RCS files from
-another system, the size of those files is the
-approximate initial size of your repository, or if you
-are starting without any version history, a rule of
-thumb is to allow for the server approximately three
-times the size of the code to be under @sc{cvs} for the
-repository (you will eventually outgrow this, but not
-for a while).  On the machines on which the developers
-will be working, you'll want disk space for
-approximately one working directory for each developer
-(either the entire tree or a portion of it, depending
-on what each developer uses).
-
-The repository should be accessible
-(directly or via a networked file system) from all
-machines which want to use @sc{cvs} in server or local
-mode; the client machines need not have any access to
-it other than via the @sc{cvs} protocol.  It is not
-possible to use @sc{cvs} to read from a repository
-which one only has read access to; @sc{cvs} needs to be
-able to create lock files (@pxref{Concurrency}).
-
-@cindex init (subcommand)
-To create a repository, run the @code{cvs init}
-command.  It will set up an empty repository in the
-@sc{cvs} root specified in the usual way
-(@pxref{Repository}).  For example,
-
-@example
-cvs -d /usr/local/cvsroot init
-@end example
-
-@code{cvs init} is careful to never overwrite any
-existing files in the repository, so no harm is done if
-you run @code{cvs init} on an already set-up
-repository.
-
-@code{cvs init} will enable history logging; if you
-don't want that, remove the history file after running
-@code{cvs init}.  @xref{history file}.
-
-@node Backing up
-@section Backing up a repository
-@cindex Repository, backing up
-@cindex Backing up, repository
-
-There is nothing particularly magical about the files
-in the repository; for the most part it is possible to
-back them up just like any other files.  However, there
-are a few issues to consider.
-
-@cindex Locks, cvs, and backups
-@cindex #cvs.rfl, and backups
-The first is that to be paranoid, one should either not
-use @sc{cvs} during the backup, or have the backup
-program lock @sc{cvs} while doing the backup.  To not
-use @sc{cvs}, you might forbid logins to machines which
-can access the repository, turn off your @sc{cvs}
-server, or similar mechanisms.  The details would
-depend on your operating system and how you have
-@sc{cvs} set up.  To lock @sc{cvs}, you would create
-@file{#cvs.rfl} locks in each repository directory.
-See @ref{Concurrency}, for more on @sc{cvs} locks.
-Having said all this, if you just back up without any
-of these precautions, the results are unlikely to be
-particularly dire.  Restoring from backup, the
-repository might be in an inconsistent state, but this
-would not be particularly hard to fix manually.
-
-When you restore a repository from backup, assuming
-that changes in the repository were made after the time
-of the backup, working directories which were not
-affected by the failure may refer to revisions which no
-longer exist in the repository.  Trying to run @sc{cvs}
-in such directories will typically produce an error
-message.  One way to get those changes back into the
-repository is as follows:
-
-@itemize @bullet
-@item
-Get a new working directory.
-
-@item
-Copy the files from the working directory from before
-the failure over to the new working directory (do not
-copy the contents of the @file{CVS} directories, of
-course).
-
-@item
-Working in the new working directory, use commands such
-as @code{cvs update} and @code{cvs diff} to figure out
-what has changed, and then when you are ready, commit
-the changes into the repository.
-@end itemize
-
-@node Moving a repository
-@section Moving a repository
-@cindex Repository, moving
-@cindex Moving a repository
-@cindex Copying a repository
-
-Just as backing up the files in the repository is
-pretty much like backing up any other files, if you
-need to move a repository from one place to another it
-is also pretty much like just moving any other
-collection of files.
-
-The main thing to consider is that working directories
-point to the repository.  The simplest way to deal with
-a moved repository is to just get a fresh working
-directory after the move.  Of course, you'll want to
-make sure that the old working directory had been
-checked in before the move, or you figured out some
-other way to make sure that you don't lose any
-changes.  If you really do want to reuse the existing
-working directory, it should be possible with manual
-surgery on the @file{CVS/Repository} files.  You can
-see @ref{Working directory storage}, for information on
-the @file{CVS/Repository} and @file{CVS/Root} files, but
-unless you are sure you want to bother, it probably
-isn't worth it.
-@c FIXME: Surgery on CVS/Repository should be avoided
-@c by making RELATIVE_REPOS the default.
-@c FIXME-maybe: might want some documented way to
-@c change the CVS/Root files in some particular tree.
-@c But then again, I don't know, maybe just having
-@c people do this in perl/shell/&c isn't so bad...
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Remote repositories
-@section Remote repositories
-@cindex Repositories, remote
-@cindex Remote repositories
-@cindex Client/Server Operation
-@cindex Server, CVS
-@cindex Remote repositories, port specification
-@cindex Repositories, remote, port specification
-@cindex Client/Server Operation, port specification
-@cindex pserver (client/server connection method), port specification
-@cindex kserver (client/server connection method), port specification
-@cindex gserver (client/server connection method), port specification
-@cindex port, specifying for remote repositories
-
-        Your working copy of the sources can be on a
-different machine than the repository.  Using @sc{cvs}
-in this manner is known as @dfn{client/server}
-operation.  You run @sc{cvs} on a machine which can
-mount your working directory, known as the
-@dfn{client}, and tell it to communicate to a machine
-which can mount the repository, known as the
-@dfn{server}.  Generally, using a remote
-repository is just like using a local one, except that
-the format of the repository name is:
-
-@example
-[:@var{method}:][[@var{user}][:@var{password}]@@]@var{hostname}[:[@var{port}]]/path/to/repository
-@end example
-
-Specifying a password in the repository name is not recommended during
-checkout, since this will cause @sc{cvs} to store a cleartext copy of the
-password in each created directory.  @code{cvs login} first instead
-(@pxref{Password authentication client}).
-
-The details of exactly what needs to be set up depend
-on how you are connecting to the server.
-
-@c Should we try to explain which platforms are which?
-@c Platforms like unix and VMS, which only allow
-@c privileged programs to bind to sockets <1024 lose on
-@c :server:
-@c Platforms like Mac and VMS, whose rsh program is
-@c unusable or nonexistent, lose on :ext:
-@c Platforms like OS/2 and NT probably could plausibly
-@c default either way (modulo -b troubles).
-
-@menu
-* Server requirements::         Memory and other resources for servers
-* The connection method::       Connection methods and method options
-* Connecting via rsh::          Using the @code{rsh} program to connect
-* Password authenticated::      Direct connections using passwords
-* GSSAPI authenticated::        Direct connections using GSSAPI
-* Kerberos authenticated::      Direct connections with Kerberos
-* Connecting via fork::         Using a forked @code{cvs server} to connect
-* Write proxies::               Distributing load across several CVS servers
-@end menu
-
-@node Server requirements
-@subsection Server requirements
-
-The quick answer to what sort of machine is suitable as
-a server is that requirements are modest---a server
-with 32M of memory or even less can handle a fairly
-large source tree with a fair amount of activity.
-@c Say something about CPU speed too?  I'm even less sure
-@c what to say on that subject...
-
-The real answer, of course, is more complicated.
-Estimating the known areas of large memory consumption
-should be sufficient to estimate memory requirements.
-There are two such areas documented here; other memory
-consumption should be small by comparison (if you find
-that is not the case, let us know, as described in
-@ref{BUGS}, so we can update this documentation).
-
-The first area of big memory consumption is large
-checkouts, when using the @sc{cvs} server.  The server
-consists of two processes for each client that it is
-serving.  Memory consumption on the child process
-should remain fairly small.  Memory consumption on the
-parent process, particularly if the network connection
-to the client is slow, can be expected to grow to
-slightly more than the size of the sources in a single
-directory, or two megabytes, whichever is larger.
-@c "two megabytes" of course is SERVER_HI_WATER.  But
-@c we don't mention that here because we are
-@c documenting the default configuration of CVS.  If it
-@c is a "standard" thing to change that value, it
-@c should be some kind of run-time configuration.
-@c
-@c See cvsclient.texi for more on the design decision
-@c to not have locks in place while waiting for the
-@c client, which is what results in memory consumption
-@c as high as this.
-
-Multiplying the size of each @sc{cvs} server by the
-number of servers which you expect to have active at
-one time should give an idea of memory requirements for
-the server.  For the most part, the memory consumed by
-the parent process probably can be swap space rather
-than physical memory.
-@c Has anyone verified that notion about swap space?
-@c I say it based pretty much on guessing that the
-@c ->text of the struct buffer_data only gets accessed
-@c in a first in, first out fashion, but I haven't
-@c looked very closely.
-
-@c What about disk usage in /tmp on the server?  I think that
-@c it can be substantial, but I haven't looked at this
-@c again and tried to figure it out ("cvs import" is
-@c probably the worst case...).
-
-The second area of large memory consumption is
-@code{diff}, when checking in large files.  This is
-required even for binary files.  The rule of thumb is
-to allow about ten times the size of the largest file
-you will want to check in, although five times may be
-adequate.  For example, if you want to check in a file
-which is 10 megabytes, you should have 100 megabytes of
-memory on the machine doing the checkin (the server
-machine for client/server, or the machine running
-@sc{cvs} for non-client/server).  This can be swap
-space rather than physical memory.  Because the memory
-is only required briefly, there is no particular need
-to allow memory for more than one such checkin at a
-time.
-@c The 5-10 times rule of thumb is from Paul Eggert for
-@c GNU diff.  I don't think it is in the GNU diff
-@c manual or anyplace like that.
-@c
-@c Probably we could be saying more about
-@c non-client/server CVS.
-@c I would guess for non-client/server CVS in an NFS
-@c environment the biggest issues are the network and
-@c the NFS server.
-
-Resource consumption for the client is even more
-modest---any machine with enough capacity to run the
-operating system in question should have little
-trouble.
-@c Is that true?  I think the client still wants to
-@c (bogusly) store entire files in memory at times.
-
-For information on disk space requirements, see
-@ref{Creating a repository}.
-
-@node The connection method
-@subsection The connection method
-
-In its simplest form, the @var{method} portion of the repository string
-(@pxref{Remote repositories}) may be one of @samp{ext}, @samp{fork},
-@samp{gserver}, @samp{kserver}, @samp{local}, @samp{pserver}, and, on some
-platforms, @samp{server}.
-
-If @var{method} is not specified, and the repository
-name starts with a @samp{/}, then the default is @code{local}.
-If @var{method} is not specified, and the repository
-name does not start with a @samp{/}, then the default is @code{ext}
-or @code{server}, depending on your platform; both the @samp{ext}
-and @samp{server} methods are described in @ref{Connecting via rsh}.
-
-@cindex connection method options
-@cindex options, connection method
-The @code{ext}, @code{fork}, @code{gserver}, and @code{pserver} connection
-methods all accept optional method options, specified as part of the
-@var{method} string, like so:
-
-@example
-:@var{method}[;@var{option}=@var{arg}...]:@var{other_connection_data}
-@end example
-
-@sc{cvs} is not sensitive to the case of @var{method} or @var{option}, though
-it may sometimes be sensitive to the case of @var{arg}.  The possible method
-options are as follows:
-
-@table @code
-@cindex CVS_PROXY_PORT
-@cindex proxy, method option
-@cindex proxyport, method option
-@cindex proxies, web, connecting via
-@cindex web proxies, connecting via
-@cindex proxies, HTTP, connecting via
-@cindex HTTP proxies, connecting via
-@item proxy=@var{hostname}
-@itemx proxyport=@var{port}
-These two method options can be used to connect via an HTTP tunnel style web
-proxy.  @var{hostname} should be the name of the HTTP proxy server to connect
-through and @var{port} is the port number on the HTTP proxy server to connect
-via.  @var{port} defaults to 8080.
-
-@strong{NOTE: An HTTP proxy server is not the same as a @sc{cvs} write proxy
-server - please see @ref{Write proxies} for more on @sc{cvs} write proxies.}
-
-For example, to connect pserver via a web proxy listening on port 8000 of
-www.myproxy.net, you would use a method of:
-
-@example
-:pserver;proxy=www.myproxy.net;proxyport=8000:@var{pserver_connection_string}
-@end example
-
-@strong{NOTE: In the above example, @var{pserver_connection_string} is still
-required to connect and authenticate to the CVS server, as noted in the
-upcoming sections on password authentication, @code{gserver}, and
-@code{kserver}.  The example above only demonstrates a modification to the
-@var{method} portion of the repository name.}
-
-These options first appeared in @sc{cvs} version 1.12.7 and are valid as
-modifcations to the @code{gserver} and @code{pserver} connection methods.
-
-@cindex CVS_RSH method option
-@item CVS_RSH=@var{path}
-This method option can be used with the @code{ext} method to specify the path
-the @sc{cvs} client will use to find the remote shell used to contact the
-@sc{cvs} server and takes precedence over any path specified in the
-@code{$CVS_RSH} environment variable (@pxref{Connecting via rsh}).  For
-example, to connect to a @sc{cvs} server via the local
-@file{/path/to/ssh/command} command, you could choose to specify the following
-@var{path} via the @code{CVS_RSH} method option:
-
-@example
-:ext;CVS_RSH=/path/to/ssh/command:@var{ext_connection_string}
-@end example
-
-This method option first appeared in @sc{cvs} version 1.12.11 and is valid only
-as a modifcation to the @code{ext} connection method.
-
-@cindex CVS_SERVER method option
-@item CVS_SERVER=@var{path}
-This method option can be used with the @code{ext} and @code{fork} methods to
-specify the path @sc{cvs} will use to find the @sc{cvs} executable on the
-@sc{cvs} server and takes precedence over any path specified in the
-@code{$CVS_SERVER} environment variable (@pxref{Connecting via rsh}).  For
-example, to select the remote @file{/path/to/cvs/command} executable as your
-@sc{cvs} server application on the @sc{cvs} server machine, you could choose to
-specify the following @var{path} via the @code{CVS_SERVER} method option:
-
-@example
-:ext;CVS_SERVER=/path/to/cvs/command:@var{ext_connection_string}
-@end example
-
-@noindent
-or, to select an executable named @samp{cvs-1.12.11}, assuming it is in your
-@code{$PATH} on the @sc{cvs} server:
-
-@example
-:ext;CVS_SERVER=cvs-1.12.11:@var{ext_connection_string}
-@end example
-
-This method option first appeared in @sc{cvs} version 1.12.11 and is valid
-as a modifcation to both the @code{ext} and @code{fork} connection methods.
-
-@cindex Redirect, method option
-@item Redirect=@var{boolean-state}
-The @code{Redirect} method option determines whether the @sc{cvs} client will
-allow a @sc{cvs} server to redirect it to a different @sc{cvs} server, usually
-for write requests, as in a write proxy setup.
-
-A @var{boolean-state} of any value acceptable for boolean @file{CVSROOT/config}
-file options is acceptable here (@pxref{config}).  For example, @samp{on},
-@samp{off}, @samp{true}, and @samp{false} are all valid values for
-@var{boolean-state}.  @var{boolean-state} for the @code{Redirect} method option
-defaults to @samp{on}.
-
-This option will have no effect when talking to any non-secondary @sc{cvs}
-server.  For more on write proxies and secondary servers, please see
-@ref{Write proxies}.
-
-This method option first appeared in @sc{cvs} version 1.12.11 and is valid only
-as a modifcation to the @code{ext} connection method.
-@end table
-
-As a further example, to combine both the @code{CVS_RSH} and @code{CVS_SERVER}
-options, a method specification like the following would work:
-
-@example
-:ext;CVS_RSH=/path/to/ssh/command;CVS_SERVER=/path/to/cvs/command:
-@end example
-
-This means that you would not need to have
-the @code{CVS_SERVER} or @code{CVS_RSH} environment
-variables set correctly.  See @ref{Connecting via rsh}, for more details on
-these environment variables.
-
-@node Connecting via rsh
-@subsection Connecting with rsh
-
-@cindex rsh
-@sc{cvs} uses the @samp{rsh} protocol to perform these
-operations, so the remote user host needs to have a
-@file{.rhosts} file which grants access to the local
-user. Note that the program that @sc{cvs} uses for this
-purpose may be specified using the @file{--with-rsh}
-flag to configure.
-
-For example, suppose you are the user @samp{mozart} on
-the local machine @samp{toe.example.com}, and the
-server machine is @samp{faun.example.org}.  On
-faun, put the following line into the file
-@file{.rhosts} in @samp{bach}'s home directory:
-
-@example
-toe.example.com  mozart
-@end example
-
-@noindent
-Then test that @samp{rsh} is working with
-
-@example
-rsh -l bach faun.example.org 'echo $PATH'
-@end example
-
-@cindex CVS_SERVER, environment variable
-Next you have to make sure that @code{rsh} will be able
-to find the server.  Make sure that the path which
-@code{rsh} printed in the above example includes the
-directory containing a program named @code{cvs} which
-is the server.  You need to set the path in
-@file{.bashrc}, @file{.cshrc}, etc., not @file{.login}
-or @file{.profile}.  Alternately, you can set the
-environment variable @code{CVS_SERVER} on the client
-machine to the filename of the server you want to use,
-for example @file{/usr/local/bin/cvs-1.6}.
-For the @code{ext} and @code{fork} methods, you may
-also specify @var{CVS_SERVER} as an otpion in the
-@var{CVSROOT} so that you may use different servers for
-differnt roots. See @ref{Remote repositories} for more
-details.
-
-There is no need to edit @file{inetd.conf} or start a
-@sc{cvs} server daemon.
-
-@cindex :server:, setting up
-@cindex :ext:, setting up
-@cindex Kerberos, using kerberized rsh
-@cindex SSH (rsh replacement)
-@cindex rsh replacements (Kerberized, SSH, &c)
-There are two access methods that you use in @code{CVSROOT}
-for rsh.  @code{:server:} specifies an internal rsh
-client, which is supported only by some @sc{cvs} ports.
-@code{:ext:} specifies an external rsh program.  By
-default this is @code{rsh} (unless otherwise specified
-by the @file{--with-rsh} flag to configure) but you may set the
-@code{CVS_RSH} environment variable to invoke another
-program which can access the remote server (for
-example, @code{remsh} on HP-UX 9 because @code{rsh} is
-something different).  It must be a program which can
-transmit data to and from the server without modifying
-it; for example the Windows NT @code{rsh} is not
-suitable since it by default translates between CRLF
-and LF.  The OS/2 @sc{cvs} port has a hack to pass @samp{-b}
-to @code{rsh} to get around this, but since this could
-potentially cause problems for programs other than the
-standard @code{rsh}, it may change in the future.  If
-you set @code{CVS_RSH} to @code{SSH} or some other rsh
-replacement, the instructions in the rest of this
-section concerning @file{.rhosts} and so on are likely
-to be inapplicable; consult the documentation for your rsh
-replacement.
-
-You may choose to specify the @var{CVS_RSH} option as a method option
-in the @var{CVSROOT} string to allow you to use different connection tools
-for different roots (@pxref{The connection method}).  For example, allowing
-some roots to use @code{CVS_RSH=remsh} and some to use
-@code{CVS_RSH=ssh} for the @code{ext} method.  See also
-the @ref{Remote repositories} for more details.
-@c See also the comment in src/client.c for rationale
-@c concerning "rsh" being the default and never
-@c "remsh".
-
-Continuing our example, supposing you want to access
-the module @file{foo} in the repository
-@file{/usr/local/cvsroot/}, on machine
-@file{faun.example.org}, you are ready to go:
-
-@example
-cvs -d :ext:bach@@faun.example.org:/usr/local/cvsroot checkout foo
-@end example
-
-@noindent
-(The @file{bach@@} can be omitted if the username is
-the same on both the local and remote hosts.)
-
-@c Should we mention "rsh host echo hi" and "rsh host
-@c cat" (the latter followed by typing text and ^D)
-@c as troubleshooting techniques?  Probably yes
-@c (people tend to have trouble setting this up),
-@c but this kind of thing can be hard to spell out.
-
-@node Password authenticated
-@subsection Direct connection with password authentication
-
-The @sc{cvs} client can also connect to the server
-using a password protocol.  This is particularly useful
-if using @code{rsh} is not feasible (for example,
-the server is behind a firewall), and Kerberos also is
-not available.
-
-        To use this method, it is necessary to make
-some adjustments on both the server and client sides.
-
-@menu
-* Password authentication server::     Setting up the server
-* Password authentication client::     Using the client
-* Password authentication security::   What this method does and does not do
-@end menu
-
-@node Password authentication server
-@subsubsection Setting up the server for password authentication
-
-First of all, you probably want to tighten the
-permissions on the @file{$CVSROOT} and
-@file{$CVSROOT/CVSROOT} directories.  See @ref{Password
-authentication security}, for more details.
-
-@cindex pserver (subcommand)
-@cindex Remote repositories, port specification
-@cindex Repositories, remote, port specification
-@cindex Client/Server Operation, port specification
-@cindex pserver (client/server connection method), port specification
-@cindex kserver (client/server connection method), port specification
-@cindex gserver (client/server connection method), port specification
-@cindex port, specifying for remote repositories
-@cindex Password server, setting up
-@cindex Authenticating server, setting up
-@cindex inetd, configuring for pserver
-@cindex xinetd, configuring for pserver
-@c FIXME: this isn't quite right regarding port
-@c numbers; CVS looks up "cvspserver" in
-@c /etc/services (on unix, but what about non-unix?).
-On the server side, the file @file{/etc/inetd.conf}
-needs to be edited so @code{inetd} knows to run the
-command @code{cvs pserver} when it receives a
-connection on the right port.  By default, the port
-number is 2401; it would be different if your client
-were compiled with @code{CVS_AUTH_PORT} defined to
-something else, though.  This can also be specified in the CVSROOT variable
-(@pxref{Remote repositories}) or overridden with the CVS_CLIENT_PORT
-environment variable (@pxref{Environment variables}).
-
-        If your @code{inetd} allows raw port numbers in
-@file{/etc/inetd.conf}, then the following (all on a
-single line in @file{inetd.conf}) should be sufficient:
-
-@example
-2401  stream  tcp  nowait  root  /usr/local/bin/cvs
-cvs -f --allow-root=/usr/cvsroot pserver
-@end example
-
-@noindent
-(You could also use the
-@samp{-T} option to specify a temporary directory.)
-
-The @samp{--allow-root} option specifies the allowable
-@sc{cvsroot} directory.  Clients which attempt to use a
-different @sc{cvsroot} directory will not be allowed to
-connect.  If there is more than one @sc{cvsroot}
-directory which you want to allow, repeat the option.
-(Unfortunately, many versions of @code{inetd} have very small
-limits on the number of arguments and/or the total length
-of the command.  The usual solution to this problem is
-to have @code{inetd} run a shell script which then invokes
-@sc{cvs} with the necessary arguments.)
-
-        If your @code{inetd} wants a symbolic service
-name instead of a raw port number, then put this in
-@file{/etc/services}:
-
-@example
-cvspserver      2401/tcp
-@end example
-
-@noindent
-and put @code{cvspserver} instead of @code{2401} in @file{inetd.conf}.
-
-If your system uses @code{xinetd} instead of @code{inetd},
-the procedure is slightly different.
-Create a file called @file{/etc/xinetd.d/cvspserver} containing the following:
-
-@example
-service cvspserver
-@{
-   port        = 2401
-   socket_type = stream
-   protocol    = tcp
-   wait        = no
-   user        = root
-   passenv     = PATH
-   server      = /usr/local/bin/cvs
-   server_args = -f --allow-root=/usr/cvsroot pserver
-@}
-@end example
-
-@noindent
-(If @code{cvspserver} is defined in @file{/etc/services}, you can omit
-the @code{port} line.)
-
-        Once the above is taken care of, restart your
-@code{inetd}, or do whatever is necessary to force it
-to reread its initialization files.
-
-If you are having trouble setting this up, see
-@ref{Connection}.
-
-@cindex CVS passwd file
-@cindex passwd (admin file)
-Because the client stores and transmits passwords in
-cleartext (almost---see @ref{Password authentication
-security}, for details), a separate @sc{cvs} password
-file is generally used, so people don't compromise
-their regular passwords when they access the
-repository.  This file is
-@file{$CVSROOT/CVSROOT/passwd} (@pxref{Intro
-administrative files}).  It uses a colon-separated
-format, similar to @file{/etc/passwd} on Unix systems,
-except that it has fewer fields: @sc{cvs} username,
-optional password, and an optional system username for
-@sc{cvs} to run as if authentication succeeds.  Here is
-an example @file{passwd} file with five entries:
-
-@example
-anonymous:
-bach:ULtgRLXo7NRxs
-spwang:1sOp854gDF3DY
-melissa:tGX1fS8sun6rY:pubcvs
-qproj:XR4EZcEs0szik:pubcvs
-@end example
-
-@noindent
-(The passwords are encrypted according to the standard
-Unix @code{crypt()} function, so it is possible to
-paste in passwords directly from regular Unix
-@file{/etc/passwd} files.)
-
-The first line in the example will grant access to any
-@sc{cvs} client attempting to authenticate as user
-@code{anonymous}, no matter what password they use,
-including an empty password.  (This is typical for
-sites granting anonymous read-only access; for
-information on how to do the "read-only" part, see
-@ref{Read-only access}.)
-
-The second and third lines will grant access to
-@code{bach} and @code{spwang} if they supply their
-respective plaintext passwords.
-
-@cindex User aliases
-The fourth line will grant access to @code{melissa}, if
-she supplies the correct password, but her @sc{cvs}
-operations will actually run on the server side under
-the system user @code{pubcvs}.  Thus, there need not be
-any system user named @code{melissa}, but there
-@emph{must} be one named @code{pubcvs}.
-
-The fifth line shows that system user identities can be
-shared: any client who successfully authenticates as
-@code{qproj} will actually run as @code{pubcvs}, just
-as @code{melissa} does.  That way you could create a
-single, shared system user for each project in your
-repository, and give each developer their own line in
-the @file{$CVSROOT/CVSROOT/passwd} file.  The @sc{cvs}
-username on each line would be different, but the
-system username would be the same.  The reason to have
-different @sc{cvs} usernames is that @sc{cvs} will log their
-actions under those names: when @code{melissa} commits
-a change to a project, the checkin is recorded in the
-project's history under the name @code{melissa}, not
-@code{pubcvs}.  And the reason to have them share a
-system username is so that you can arrange permissions
-in the relevant area of the repository such that only
-that account has write-permission there.
-
-If the system-user field is present, all
-password-authenticated @sc{cvs} commands run as that
-user; if no system user is specified, @sc{cvs} simply
-takes the @sc{cvs} username as the system username and
-runs commands as that user.  In either case, if there
-is no such user on the system, then the @sc{cvs}
-operation will fail (regardless of whether the client
-supplied a valid password).
-
-The password and system-user fields can both be omitted
-(and if the system-user field is omitted, then also
-omit the colon that would have separated it from the
-encrypted password).  For example, this would be a
-valid @file{$CVSROOT/CVSROOT/passwd} file:
-
-@example
-anonymous::pubcvs
-fish:rKa5jzULzmhOo:kfogel
-sussman:1sOp854gDF3DY
-@end example
-
-@noindent
-When the password field is omitted or empty, then the
-client's authentication attempt will succeed with any
-password, including the empty string.  However, the
-colon after the @sc{cvs} username is always necessary,
-even if the password is empty.
-
-@sc{cvs} can also fall back to use system authentication.
-When authenticating a password, the server first checks
-for the user in the @file{$CVSROOT/CVSROOT/passwd}
-file.  If it finds the user, it will use that entry for
-authentication as described above.  But if it does not
-find the user, or if the @sc{cvs} @file{passwd} file
-does not exist, then the server can try to authenticate
-the username and password using the operating system's
-user-lookup routines (this "fallback" behavior can be
-disabled by setting @code{SystemAuth=no} in the
-@sc{cvs} @file{config} file, @pxref{config}).
-
-The default fallback behavior is to look in 
-@file{/etc/passwd} for this system user unless your
-system has PAM (Pluggable Authentication Modules)
-and your @sc{cvs} server executable was configured to
-use it at compile time (using @code{./configure --enable-pam} - see the
-INSTALL file for more).  In this case, PAM will be consulted instead.
-This means that @sc{cvs} can be configured to use any password
-authentication source PAM can be configured to use (possibilities
-include a simple UNIX password, NIS, LDAP, and others) in its
-global configuration file (usually @file{/etc/pam.conf}
-or possibly @file{/etc/pam.d/cvs}).  See your PAM documentation
-for more details on PAM configuration.
-
-Note that PAM is an experimental feature in @sc{cvs} and feedback is
-encouraged.  Please send a mail to one of the @sc{cvs} mailing lists
-(@code{info-cvs@@nongnu.org} or @code{bug-cvs@@nongnu.org}) if you use the 
-@sc{cvs} PAM support.
-
-@strong{WARNING: Using PAM gives the system administrator much more 
-flexibility about how @sc{cvs} users are authenticated but 
-no more security than other methods.  See below for more.} 
-
-CVS needs an "auth", "account" and "session" module in the 
-PAM configuration file. A typical PAM configuration 
-would therefore have the following lines 
-in @file{/etc/pam.conf} to emulate the standard @sc{cvs} 
-system @file{/etc/passwd} authentication:
-
-@example
-cvs    auth        required    pam_unix.so
-cvs    account     required    pam_unix.so
-cvs    session     required    pam_unix.so
-@end example
-
-The the equivalent @file{/etc/pam.d/cvs} would contain
-
-@example
-auth       required    pam_unix.so
-account            required    pam_unix.so
-session            required    pam_unix.so
-@end example
-
-Some systems require a full path to the module so that
-@file{pam_unix.so} (Linux) would become something like 
-@file{/usr/lib/security/$ISA/pam_unix.so.1} (Sun Solaris).
-See the @file{contrib/pam} subdirectory of the @sc{cvs}
-source distribution for further example configurations.
-
-The PAM service name given above as "cvs" is just
-the service name in the default configuration and can be
-set using
-@code{./configure --with-hardcoded-pam-service-name=<pam-service-name>}
-before compiling.  @sc{cvs} can also be configured to use whatever
-name it is invoked as as its PAM service name using
-@code{./configure --without-hardcoded-pam-service-name}, but this
-feature should not be used if you may not have control of the name
-@sc{cvs} will be invoked as.
-
-Be aware, also, that falling back to system
-authentication might be a security risk: @sc{cvs}
-operations would then be authenticated with that user's
-regular login password, and the password flies across
-the network in plaintext.  See @ref{Password
-authentication security} for more on this.
-This may be more of a problem with PAM authentication
-because it is likely that the source of the system 
-password is some central authentication service like
-LDAP which is also used to authenticate other services.
-
-On the other hand, PAM makes it very easy to change your password
-regularly.  If they are given the option of a one-password system for
-all of their activities, users are often more willing to change their
-password on a regular basis.
-
-In the non-PAM configuration where the password is stored in the
-@file{CVSROOT/passwd} file, it is difficult to change passwords on a
-regular basis since only administrative users (or in some cases
-processes that act as an administrative user) are typically given
-access to modify this file.  Either there needs to be some
-hand-crafted web page or set-uid program to update the file, or the
-update needs to be done by submitting a request to an administrator to
-perform the duty by hand.  In the first case, having to remember to
-update a separate password on a periodic basis can be difficult.  In
-the second case, the manual nature of the change will typically mean
-that the password will not be changed unless it is absolutely
-necessary.
-
-Note that PAM administrators should probably avoid configuring
-one-time-passwords (OTP) for @sc{cvs} authentication/authorization.  If
-OTPs are desired, the administrator may wish to encourage the use of
-one of the other Client/Server access methods.  See the section on
-@pxref{Remote repositories} for a list of other methods.
-
-Right now, the only way to put a password in the
-@sc{cvs} @file{passwd} file is to paste it there from
-somewhere else.  Someday, there may be a @code{cvs
-passwd} command.
-
-Unlike many of the files in @file{$CVSROOT/CVSROOT}, it
-is normal to edit the @file{passwd} file in-place,
-rather than via @sc{cvs}.  This is because of the
-possible security risks of having the @file{passwd}
-file checked out to people's working copies.  If you do
-want to include the @file{passwd} file in checkouts of
-@file{$CVSROOT/CVSROOT}, see @ref{checkoutlist}.
-
-@c We might also suggest using the @code{htpasswd} command
-@c from freely available web servers as well, but that
-@c would open up a can of worms in that the users next
-@c questions are likely to be "where do I get it?" and
-@c "how do I use it?"
-@c Also note that htpasswd, at least the version I had,
-@c likes to clobber the third field.
-
-@node Password authentication client
-@subsubsection Using the client with password authentication
-@cindex Login (subcommand)
-@cindex Password client, using
-@cindex Authenticated client, using
-@cindex :pserver:, setting up
-To run a @sc{cvs} command on a remote repository via
-the password-authenticating server, one specifies the
-@code{pserver} protocol, optional username, repository host, an
-optional port number, and path to the repository.  For example:
-
-@example
-cvs -d :pserver:faun.example.org:/usr/local/cvsroot checkout someproj
-@end example
-
-@noindent
-or
-
-@example
-CVSROOT=:pserver:bach@@faun.example.org:2401/usr/local/cvsroot
-cvs checkout someproj
-@end example
-
-However, unless you're connecting to a public-access
-repository (i.e., one where that username doesn't
-require a password), you'll need to supply a password or @dfn{log in} first.
-Logging in verifies your password with the repository and stores it in a file.
-It's done with the @code{login} command, which will
-prompt you interactively for the password if you didn't supply one as part of
-@var{$CVSROOT}:
-
-@example
-cvs -d :pserver:bach@@faun.example.org:/usr/local/cvsroot login
-CVS password:
-@end example
-
-@noindent
-or
-
-@example
-cvs -d :pserver:bach:p4ss30rd@@faun.example.org:/usr/local/cvsroot login
-@end example
-
-After you enter the password, @sc{cvs} verifies it with
-the server.  If the verification succeeds, then that
-combination of username, host, repository, and password
-is permanently recorded, so future transactions with
-that repository won't require you to run @code{cvs
-login}.  (If verification fails, @sc{cvs} will exit
-complaining that the password was incorrect, and
-nothing will be recorded.)
-
-The records are stored, by default, in the file
-@file{$HOME/.cvspass}.  That file's format is
-human-readable, and to a degree human-editable, but
-note that the passwords are not stored in
-cleartext---they are trivially encoded to protect them
-from "innocent" compromise (i.e., inadvertent viewing
-by a system administrator or other non-malicious
-person).
-
-@cindex CVS_PASSFILE, environment variable
-You can change the default location of this file by
-setting the @code{CVS_PASSFILE} environment variable.
-If you use this variable, make sure you set it
-@emph{before} @code{cvs login} is run.  If you were to
-set it after running @code{cvs login}, then later
-@sc{cvs} commands would be unable to look up the
-password for transmission to the server.
-  
-Once you have logged in, all @sc{cvs} commands using
-that remote repository and username will authenticate
-with the stored password.  So, for example
-  
-@example
-cvs -d :pserver:bach@@faun.example.org:/usr/local/cvsroot checkout foo
-@end example
-
-@noindent
-should just work (unless the password changes on the
-server side, in which case you'll have to re-run
-@code{cvs login}).
-
-Note that if the @samp{:pserver:} were not present in
-the repository specification, @sc{cvs} would assume it
-should use @code{rsh} to connect with the server
-instead (@pxref{Connecting via rsh}).
-
-Of course, once you have a working copy checked out and
-are running @sc{cvs} commands from within it, there is
-no longer any need to specify the repository
-explicitly, because @sc{cvs} can deduce the repository
-from the working copy's @file{CVS} subdirectory.
-
-@c FIXME: seems to me this needs somewhat more
-@c explanation.
-@cindex Logout (subcommand)
-The password for a given remote repository can be
-removed from the @code{CVS_PASSFILE} by using the
-@code{cvs logout} command.
-
-@node Password authentication security
-@subsubsection Security considerations with password authentication
-
-@cindex Security, of pserver
-The passwords are stored on the client side in a
-trivial encoding of the cleartext, and transmitted in
-the same encoding.  The encoding is done only to
-prevent inadvertent password compromises (i.e., a
-system administrator accidentally looking at the file),
-and will not prevent even a naive attacker from gaining
-the password.
-
-@c FIXME: The bit about "access to the repository
-@c implies general access to the system is *not* specific
-@c to pserver; it applies to kerberos and SSH and
-@c everything else too.  Should reorganize the
-@c documentation to make this clear.
-The separate @sc{cvs} password file (@pxref{Password
-authentication server}) allows people
-to use a different password for repository access than
-for login access.  On the other hand, once a user has
-non-read-only
-access to the repository, she can execute programs on
-the server system through a variety of means.  Thus, repository
-access implies fairly broad system access as well.  It
-might be possible to modify @sc{cvs} to prevent that,
-but no one has done so as of this writing.
-@c OpenBSD uses chroot() and copies the repository to
-@c provide anonymous read-only access (for details see
-@c http://www.openbsd.org/anoncvs.shar).  While this
-@c closes the most obvious holes, I'm not sure it
-@c closes enough holes to recommend it (plus it is
-@c *very* easy to accidentally screw up a setup of this
-@c type).
-
-Note that because the @file{$CVSROOT/CVSROOT} directory
-contains @file{passwd} and other files which are used
-to check security, you must control the permissions on
-this directory as tightly as the permissions on
-@file{/etc}.  The same applies to the @file{$CVSROOT}
-directory itself and any directory
-above it in the tree.  Anyone who has write access to
-such a directory will have the ability to become any
-user on the system.  Note that these permissions are
-typically tighter than you would use if you are not
-using pserver.
-@c TODO: Would be really nice to document/implement a
-@c scheme where the CVS server can run as some non-root
-@c user, e.g. "cvs".  CVSROOT/passwd would contain a
-@c bunch of entries of the form foo:xxx:cvs (or the "cvs"
-@c would be implicit).  This would greatly reduce
-@c security risks such as those hinted at in the
-@c previous paragraph.  I think minor changes to CVS
-@c might be required but mostly this would just need
-@c someone who wants to play with it, document it, &c.
-
-In summary, anyone who gets the password gets
-repository access (which may imply some measure of general system
-access as well).  The password is available to anyone
-who can sniff network packets or read a protected
-(i.e., user read-only) file.  If you want real
-security, get Kerberos.
-
-@node GSSAPI authenticated
-@subsection Direct connection with GSSAPI
-
-@cindex GSSAPI
-@cindex Security, GSSAPI
-@cindex :gserver:, setting up
-@cindex Kerberos, using :gserver:
-GSSAPI is a generic interface to network security
-systems such as Kerberos 5.
-If you have a working GSSAPI library, you can have
-@sc{cvs} connect via a direct @sc{tcp} connection,
-authenticating with GSSAPI.
-
-To do this, @sc{cvs} needs to be compiled with GSSAPI
-support; when configuring @sc{cvs} it tries to detect
-whether GSSAPI libraries using Kerberos version 5 are
-present.  You can also use the @file{--with-gssapi}
-flag to configure.
-
-The connection is authenticated using GSSAPI, but the
-message stream is @emph{not} authenticated by default.
-You must use the @code{-a} global option to request
-stream authentication.
-
-The data transmitted is @emph{not} encrypted by
-default.  Encryption support must be compiled into both
-the client and the server; use the
-@file{--enable-encrypt} configure option to turn it on.
-You must then use the @code{-x} global option to
-request encryption.
-
-GSSAPI connections are handled on the server side by
-the same server which handles the password
-authentication server; see @ref{Password authentication
-server}.  If you are using a GSSAPI mechanism such as
-Kerberos which provides for strong authentication, you
-will probably want to disable the ability to
-authenticate via cleartext passwords.  To do so, create
-an empty @file{CVSROOT/passwd} password file, and set
-@code{SystemAuth=no} in the config file
-(@pxref{config}).
-
-The GSSAPI server uses a principal name of
-cvs/@var{hostname}, where @var{hostname} is the
-canonical name of the server host.  You will have to
-set this up as required by your GSSAPI mechanism.
-
-To connect using GSSAPI, use the @samp{:gserver:} method.  For
-example,
-
-@example
-cvs -d :gserver:faun.example.org:/usr/local/cvsroot checkout foo
-@end example
-
-@node Kerberos authenticated
-@subsection Direct connection with Kerberos
-
-@cindex Kerberos, using :kserver:
-@cindex Security, Kerberos
-@cindex :kserver:, setting up
-The easiest way to use Kerberos is to use the Kerberos
-@code{rsh}, as described in @ref{Connecting via rsh}.
-The main disadvantage of using rsh is that all the data
-needs to pass through additional programs, so it may be
-slower.  So if you have Kerberos installed you can
-connect via a direct @sc{tcp} connection,
-authenticating with Kerberos.
-
-This section concerns the Kerberos network security
-system, version 4.  Kerberos version 5 is supported via
-the GSSAPI generic network security interface, as
-described in the previous section.
-
-To do this, @sc{cvs} needs to be compiled with Kerberos
-support; when configuring @sc{cvs} it tries to detect
-whether Kerberos is present or you can use the
-@file{--with-krb4} flag to configure.
-
-The data transmitted is @emph{not} encrypted by
-default.  Encryption support must be compiled into both
-the client and server; use the
-@file{--enable-encryption} configure option to turn it
-on.  You must then use the @code{-x} global option to
-request encryption.
-
-The CVS client will attempt to connect to port 1999 by default.
-
-@cindex kinit
-When you want to use @sc{cvs}, get a ticket in the
-usual way (generally @code{kinit}); it must be a ticket
-which allows you to log into the server machine.  Then
-you are ready to go:
-
-@example
-cvs -d :kserver:faun.example.org:/usr/local/cvsroot checkout foo
-@end example
-
-Previous versions of @sc{cvs} would fall back to a
-connection via rsh; this version will not do so.
-
-@node Connecting via fork
-@subsection Connecting with fork
-
-@cindex fork, access method
-@cindex :fork:, setting up
-This access method allows you to connect to a
-repository on your local disk via the remote protocol.
-In other words it does pretty much the same thing as
-@code{:local:}, but various quirks, bugs and the like are
-those of the remote @sc{cvs} rather than the local
-@sc{cvs}.
-
-For day-to-day operations you might prefer either
-@code{:local:} or @code{:fork:}, depending on your
-preferences.  Of course @code{:fork:} comes in
-particularly handy in testing or
-debugging @code{cvs} and the remote protocol.
-Specifically, we avoid all of the network-related
-setup/configuration, timeouts, and authentication
-inherent in the other remote access methods but still
-create a connection which uses the remote protocol.
-
-To connect using the @code{fork} method, use
-@samp{:fork:} and the pathname to your local
-repository.  For example:
-
-@example
-cvs -d :fork:/usr/local/cvsroot checkout foo
-@end example
-
-@cindex CVS_SERVER, and :fork:
-As with @code{:ext:}, the server is called @samp{cvs}
-by default, or the value of the @code{CVS_SERVER}
-environment variable.
-
-
-@node Write proxies
-@subsection Distributing load across several CVS servers
-
-@cindex PrimaryServer, in CVSROOT/config
-@cindex Primary server
-@cindex Secondary server
-@cindex proxy, write
-@cindex write proxy
-@sc{cvs} can be configured to distribute usage across several @sc{cvs}
-servers.  This is accomplished by means of one or more @dfn{write proxies}, or
-@dfn{secondary servers}, for a single @dfn{primary server}.
-
-When a @sc{cvs} client accesses a secondary server and only sends read
-requests, then the secondary server handles the entire request.  If the client
-sends any write requests, however, the secondary server asks the client to
-redirect its write request to the primary server, if the client supports
-redirect requests, and otherwise becomes a transparent proxy for the primary
-server, which actually handles the write request.
-
-In this manner, any number of read-only secondary servers may be configured as
-write proxies for the primary server, effectively distributing the load from
-all read operations between the secondary servers and restricting the load on
-the primary server to write operations and pushing changes to the secondaries.
-
-Primary servers will not automatically push changes to secondaries.  This must
-be configured via @file{loginfo}, @file{postadmin}, @file{posttag}, &
-@file{postwatch} scripts (@pxref{Trigger Scripts}) like the following:
-
-@example
-ALL    rsync -gopr -essh ./ secondary:/cvsroot/%p &
-@end example
-
-You would probably actually want to lock directories for write on the secondary
-and for read on the primary before running the @samp{rsync} in the above
-example, but describing such a setup is beyond the scope of this document.
-
-A secondary advantage of a write proxy setup is that users pointing at the
-secondary server can still execute fast read operations while on a network that
-connects to the primary over a slow link or even one where the link to the
-primary is periodically broken.  Only write operations will require the network
-link to the primary.
-
-To configure write proxies, the primary must be specified with the
-@samp{PrimaryServer} option in @file{CVSROOT/config} (@pxref{config}).  For the
-transparent proxy mode to work, all secondary servers must also be running the
-same version of the @sc{cvs} server, or at least one that provides the same
-list of supported requests to the client as the primary server.  This is not
-necessary for redirection.
-
-Once a primary server is configured, secondary servers may be configured by:
-
-@enumerate
-@item
-Duplicating the primary repository at the new location.
-@item
-Setting up the @file{loginfo}, @file{postadmin}, @file{posttag}, and
-@file{postwatch} files on the primary to propagate writes to the new secondary.
-@item
-Configure remote access to the secondary(ies) as you would configure access
-to any other CVS server (@pxref{Remote repositories}).
-@item
-Ensuring that @code{--allow-root=@var{secondary-cvsroot}} is passed to
-@strong{all} incovations of the secondary server if the path to the @sc{cvs}
-repository directory is different on the two servers and you wish to support
-clients that do not handle the @samp{Redirect} resopnse (CVS 1.12.9 and earlier
-clients do not handle the @samp{Redirect} response).
-
-Please note, again, that writethrough proxy suport requires
-@code{--allow-root=@var{secondary-cvsroot}} to be specified for @strong{all}
-incovations of the secondary server, not just @samp{pserver} invocations.
-This may require a wrapper script for the @sc{cvs} executable
-on your server machine.
-@end enumerate
-
-
-@c ---------------------------------------------------------------------
-@node Read-only access
-@section Read-only repository access
-@cindex Read-only repository access
-@cindex readers (admin file)
-@cindex writers (admin file)
-
-        It is possible to grant read-only repository
-access to people using the password-authenticated
-server (@pxref{Password authenticated}).  (The
-other access methods do not have explicit support for
-read-only users because those methods all assume login
-access to the repository machine anyway, and therefore
-the user can do whatever local file permissions allow
-her to do.)
-
-        A user who has read-only access can do only
-those @sc{cvs} operations which do not modify the
-repository, except for certain ``administrative'' files
-(such as lock files and the history file).  It may be
-desirable to use this feature in conjunction with
-user-aliasing (@pxref{Password authentication server}).
-
-Unlike with previous versions of @sc{cvs}, read-only
-users should be able merely to read the repository, and
-not to execute programs on the server or otherwise gain
-unexpected levels of access.  Or to be more accurate,
-the @emph{known} holes have been plugged.  Because this
-feature is new and has not received a comprehensive
-security audit, you should use whatever level of
-caution seems warranted given your attitude concerning
-security.
-
-        There are two ways to specify read-only access
-for a user: by inclusion, and by exclusion.
-
-        "Inclusion" means listing that user
-specifically in the @file{$CVSROOT/CVSROOT/readers}
-file, which is simply a newline-separated list of
-users.  Here is a sample @file{readers} file:
-
-@example
-melissa
-splotnik
-jrandom
-@end example
-
-@noindent
-        (Don't forget the newline after the last user.)
-
-        "Exclusion" means explicitly listing everyone
-who has @emph{write} access---if the file
-
-@example
-$CVSROOT/CVSROOT/writers
-@end example
-
-@noindent
-exists, then only
-those users listed in it have write access, and
-everyone else has read-only access (of course, even the
-read-only users still need to be listed in the
-@sc{cvs} @file{passwd} file).  The
-@file{writers} file has the same format as the
-@file{readers} file.
-
-        Note: if your @sc{cvs} @file{passwd}
-file maps cvs users onto system users (@pxref{Password
-authentication server}), make sure you deny or grant
-read-only access using the @emph{cvs} usernames, not
-the system usernames.  That is, the @file{readers} and
-@file{writers} files contain cvs usernames, which may
-or may not be the same as system usernames.
-
-        Here is a complete description of the server's
-behavior in deciding whether to grant read-only or
-read-write access:
-
-        If @file{readers} exists, and this user is
-listed in it, then she gets read-only access.  Or if
-@file{writers} exists, and this user is NOT listed in
-it, then she also gets read-only access (this is true
-even if @file{readers} exists but she is not listed
-there).  Otherwise, she gets full read-write access.
-
-        Of course there is a conflict if the user is
-listed in both files.  This is resolved in the more
-conservative way, it being better to protect the
-repository too much than too little: such a user gets
-read-only access.
-
-@node Server temporary directory
-@section Temporary directories for the server
-@cindex Temporary directories, and server
-@cindex Server, temporary directories
-
-While running, the @sc{cvs} server creates temporary
-directories.  They are named
-
-@example
-cvs-serv@var{pid}
-@end example
-
-@noindent
-where @var{pid} is the process identification number of
-the server.
-They are located in the directory specified by 
-the @samp{-T} global option (@pxref{Global options}), 
-the @code{TMPDIR} environment variable (@pxref{Environment variables}), 
-or, failing that, @file{/tmp}.
-
-In most cases the server will remove the temporary
-directory when it is done, whether it finishes normally
-or abnormally.  However, there are a few cases in which
-the server does not or cannot remove the temporary
-directory, for example:
-
-@itemize @bullet
-@item
-If the server aborts due to an internal server error,
-it may preserve the directory to aid in debugging
-
-@item
-If the server is killed in a way that it has no way of
-cleaning up (most notably, @samp{kill -KILL} on unix).
-
-@item
-If the system shuts down without an orderly shutdown,
-which tells the server to clean up.
-@end itemize
-
-In cases such as this, you will need to manually remove
-the @file{cvs-serv@var{pid}} directories.  As long as
-there is no server running with process identification
-number @var{pid}, it is safe to do so.
-
-@c ---------------------------------------------------------------------
-@node Starting a new project
-@chapter Starting a project with CVS
-@cindex Starting a project with CVS
-@cindex Creating a project
-
-@comment --moduledb--
-Because renaming files and moving them between
-directories is somewhat inconvenient, the first thing
-you do when you start a new project should be to think
-through your file organization.  It is not impossible
-to rename or move files, but it does increase the
-potential for confusion and @sc{cvs} does have some
-quirks particularly in the area of renaming
-directories.  @xref{Moving files}.
-
-What to do next depends on the situation at hand.
-
-@menu
-* Setting up the files::        Getting the files into the repository
-* Defining the module::         How to make a module of the files
-@end menu
-@c -- File permissions!
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Setting up the files
-@section Setting up the files
-
-The first step is to create the files inside the repository.  This can
-be done in a couple of different ways.
-
-@c -- The contributed scripts
-@menu
-* From files::                  This method is useful with old projects
-                                where files already exists.
-* From other version control systems::  Old projects where you want to
-                                        preserve history from another system.
-* From scratch::                Creating a directory tree from scratch.
-@end menu
-
-@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
-@node From files
-@subsection Creating a directory tree from a number of files
-@cindex Importing files
-
-When you begin using @sc{cvs}, you will probably already have several
-projects that can be
-put under @sc{cvs} control.  In these cases the easiest way is to use the
-@code{import} command.  An example is probably the easiest way to
-explain how to use it.  If the files you want to install in
-@sc{cvs} reside in @file{@var{wdir}}, and you want them to appear in the
-repository as @file{$CVSROOT/yoyodyne/@var{rdir}}, you can do this:
-
-@example
-$ cd @var{wdir}
-$ cvs import -m "Imported sources" yoyodyne/@var{rdir} yoyo start
-@end example
-
-Unless you supply a log message with the @samp{-m}
-flag, @sc{cvs} starts an editor and prompts for a
-message.  The string @samp{yoyo} is a @dfn{vendor tag},
-and @samp{start} is a @dfn{release tag}.  They may fill
-no purpose in this context, but since @sc{cvs} requires
-them they must be present.  @xref{Tracking sources}, for
-more information about them.
-
-You can now verify that it worked, and remove your
-original source directory.
-@c FIXME: Need to say more about "verify that it
-@c worked".  What should the user look for in the output
-@c from "diff -r"?
-
-@example
-$ cd ..
-$ cvs checkout yoyodyne/@var{rdir}       # @r{Explanation below}
-$ diff -r @var{wdir} yoyodyne/@var{rdir}
-$ rm -r @var{wdir}
-@end example
-
-@noindent
-Erasing the original sources is a good idea, to make sure that you do
-not accidentally edit them in @var{wdir}, bypassing @sc{cvs}.
-Of course, it would be wise to make sure that you have
-a backup of the sources before you remove them.
-
-The @code{checkout} command can either take a module
-name as argument (as it has done in all previous
-examples) or a path name relative to @code{$CVSROOT},
-as it did in the example above.
-
-It is a good idea to check that the permissions
-@sc{cvs} sets on the directories inside @code{$CVSROOT}
-are reasonable, and that they belong to the proper
-groups.  @xref{File permissions}.
-
-If some of the files you want to import are binary, you
-may want to use the wrappers features to specify which
-files are binary and which are not.  @xref{Wrappers}.
-
-@c The node name is too long, but I am having trouble
-@c thinking of something more concise.
-@node From other version control systems
-@subsection Creating Files From Other Version Control Systems
-@cindex Importing files, from other version control systems
-
-If you have a project which you are maintaining with
-another version control system, such as @sc{rcs}, you
-may wish to put the files from that project into
-@sc{cvs}, and preserve the revision history of the
-files.
-
-@table @asis
-@cindex RCS, importing files from
-@item From RCS
-If you have been using @sc{rcs}, find the @sc{rcs}
-files---usually a file named @file{foo.c} will have its
-@sc{rcs} file in @file{RCS/foo.c,v} (but it could be
-other places; consult the @sc{rcs} documentation for
-details).  Then create the appropriate directories in
-@sc{cvs} if they do not already exist.  Then copy the
-files into the appropriate directories in the @sc{cvs}
-repository (the name in the repository must be the name
-of the source file with @samp{,v} added; the files go
-directly in the appropriate directory of the repository,
-not in an @file{RCS} subdirectory).  This is one of the
-few times when it is a good idea to access the @sc{cvs}
-repository directly, rather than using @sc{cvs}
-commands.  Then you are ready to check out a new
-working directory.
-@c Someday there probably should be a "cvs import -t
-@c rcs" or some such.  It could even create magic
-@c branches.  It could also do something about the case
-@c where the RCS file had a (non-magic) "0" branch.
-
-The @sc{rcs} file should not be locked when you move it
-into @sc{cvs}; if it is, @sc{cvs} will have trouble
-letting you operate on it.
-@c What is the easiest way to unlock your files if you
-@c have them locked?  Especially if you have a lot of them?
-@c This is a CVS bug/misfeature; importing RCS files
-@c should ignore whether they are locked and leave them in
-@c an unlocked state.  Yet another reason for a separate
-@c "import RCS file" command.
-
-@c How many is "many"? Or do they just import RCS files?
-@item From another version control system
-Many version control systems have the ability to export
-@sc{rcs} files in the standard format.  If yours does,
-export the @sc{rcs} files and then follow the above
-instructions.
-
-Failing that, probably your best bet is to write a
-script that will check out the files one revision at a
-time using the command line interface to the other
-system, and then check the revisions into @sc{cvs}.
-The @file{sccs2rcs} script mentioned below may be a
-useful example to follow.
-
-@cindex SCCS, importing files from
-@item From SCCS
-There is a script in the @file{contrib} directory of
-the @sc{cvs} source distribution called @file{sccs2rcs}
-which converts @sc{sccs} files to @sc{rcs} files.
-Note: you must run it on a machine which has both
-@sc{sccs} and @sc{rcs} installed, and like everything
-else in contrib it is unsupported (your mileage may
-vary).
-
-@cindex PVCS, importing files from
-@item From PVCS
-There is a script in the @file{contrib} directory of
-the @sc{cvs} source distribution called @file{pvcs_to_rcs}
-which converts @sc{pvcs} archives to @sc{rcs} files.
-You must run it on a machine which has both
-@sc{pvcs} and @sc{rcs} installed, and like everything
-else in contrib it is unsupported (your mileage may
-vary).  See the comments in the script for details.
-@end table
-@c CMZ and/or PATCHY were systems that were used in the
-@c high energy physics community (especially for
-@c CERNLIB).  CERN has replaced them with CVS, but the
-@c CAR format seems to live on as a way to submit
-@c changes.  There is a program car2cvs which converts
-@c but I'm not sure where one gets a copy.
-@c Not sure it is worth mentioning here, since it would
-@c appear to affect only one particular community.
-@c Best page for more information is:
-@c http://wwwcn1.cern.ch/asd/cvs/index.html
-@c See also:
-@c http://ecponion.cern.ch/ecpsa/cernlib.html
-
-@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
-@node From scratch
-@subsection Creating a directory tree from scratch
-
-@c Also/instead should be documenting
-@c $ cvs co -l .
-@c $ mkdir tc
-@c $ cvs add tc
-@c $ cd tc
-@c $ mkdir man
-@c $ cvs add man
-@c etc.
-@c Using import to create the directories only is
-@c probably a somewhat confusing concept.
-For a new project, the easiest thing to do is probably
-to create an empty directory structure, like this:
-
-@example
-$ mkdir tc
-$ mkdir tc/man
-$ mkdir tc/testing
-@end example
-
-After that, you use the @code{import} command to create
-the corresponding (empty) directory structure inside
-the repository:
-
-@example
-$ cd tc
-$ cvs import -m "Created directory structure" yoyodyne/@var{dir} yoyo start
-@end example
-
-This will add yoyodyne/@var{dir} as a directory under
-@code{$CVSROOT}.
-
-Use @code{checkout} to get the new project.  Then, use @code{add}
-to add files (and new directories) as needed.
-
-@example
-$ cd ..
-$ cvs co yoyodyne/@var{dir}
-@end example
-
-Check that the permissions @sc{cvs} sets on the
-directories inside @code{$CVSROOT} are reasonable.
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Defining the module
-@section Defining the module
-@cindex Defining a module
-@cindex Editing the modules file
-@cindex Module, defining
-@cindex Modules file, changing
-
-The next step is to define the module in the
-@file{modules} file.  This is not strictly necessary,
-but modules can be convenient in grouping together
-related files and directories.
-
-In simple cases these steps are sufficient to define a module.
-
-@enumerate
-@item
-Get a working copy of the modules file.
-
-@example
-$ cvs checkout CVSROOT/modules
-$ cd CVSROOT
-@end example
-
-@item
-Edit the file and insert a line that defines the module.  @xref{Intro
-administrative files}, for an introduction.  @xref{modules}, for a full
-description of the modules file.  You can use the
-following line to define the module @samp{tc}:
-
-@example
-tc   yoyodyne/tc
-@end example
-
-@item
-Commit your changes to the modules file.
-
-@example
-$ cvs commit -m "Added the tc module." modules
-@end example
-
-@item
-Release the modules module.
-
-@example
-$ cd ..
-$ cvs release -d CVSROOT
-@end example
-@end enumerate
-
-@c ---------------------------------------------------------------------
-@node Revisions
-@chapter Revisions
-
-For many uses of @sc{cvs}, one doesn't need to worry
-too much about revision numbers; @sc{cvs} assigns
-numbers such as @code{1.1}, @code{1.2}, and so on, and
-that is all one needs to know.  However, some people
-prefer to have more knowledge and control concerning
-how @sc{cvs} assigns revision numbers.
-
-If one wants to keep track of a set of revisions
-involving more than one file, such as which revisions
-went into a particular release, one uses a @dfn{tag},
-which is a symbolic revision which can be assigned to a
-numeric revision in each file.
-
-@menu
-* Revision numbers::            The meaning of a revision number
-* Versions revisions releases::  Terminology used in this manual
-* Assigning revisions::         Assigning revisions
-* Tags::                        Tags--Symbolic revisions
-* Tagging the working directory::  The cvs tag command
-* Tagging by date/tag::         The cvs rtag command
-* Modifying tags::              Adding, renaming, and deleting tags
-* Tagging add/remove::          Tags with adding and removing files
-* Sticky tags::                 Certain tags are persistent
-@end menu
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Revision numbers
-@section Revision numbers
-@cindex Revision numbers
-@cindex Revision tree
-@cindex Linear development
-@cindex Number, revision-
-@cindex Decimal revision number
-@cindex Branch number
-@cindex Number, branch
-
-Each version of a file has a unique @dfn{revision
-number}.  Revision numbers look like @samp{1.1},
-@samp{1.2}, @samp{1.3.2.2} or even @samp{1.3.2.2.4.5}.
-A revision number always has an even number of
-period-separated decimal integers.  By default revision
-1.1 is the first revision of a file.  Each successive
-revision is given a new number by increasing the
-rightmost number by one.  The following figure displays
-a few revisions, with newer revisions to the right.
-
-@example
-       +-----+    +-----+    +-----+    +-----+    +-----+
-       ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !
-       +-----+    +-----+    +-----+    +-----+    +-----+
-@end example
-
-It is also possible to end up with numbers containing
-more than one period, for example @samp{1.3.2.2}.  Such
-revisions represent revisions on branches
-(@pxref{Branching and merging}); such revision numbers
-are explained in detail in @ref{Branches and
-revisions}.
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Versions revisions releases
-@section Versions, revisions and releases
-@cindex Revisions, versions and releases
-@cindex Versions, revisions and releases
-@cindex Releases, revisions and versions
-
-A file can have several versions, as described above.
-Likewise, a software product can have several versions.
-A software product is often given a version number such
-as @samp{4.1.1}.
-
-Versions in the first sense are called @dfn{revisions}
-in this document, and versions in the second sense are
-called @dfn{releases}.  To avoid confusion, the word
-@dfn{version} is almost never used in this document.
-
-@node Assigning revisions
-@section Assigning revisions
-
-@c We avoid the "major revision" terminology.  It seems
-@c like jargon.  Hopefully "first number" is clear enough.
-@c
-@c Well, in the context of software release numbers,
-@c "major" and "minor" release or version numbers are
-@c documented in at least the GNU Coding Standards, but I'm
-@c still not sure I find that a valid reason to apply the
-@c terminology to RCS revision numbers.  "First", "Second",
-@c "subsequent", and so on is almost surely clearer,
-@c especially to a novice reader. -DRP
-By default, @sc{cvs} will assign numeric revisions by
-leaving the first number the same and incrementing the
-second number.  For example, @code{1.1}, @code{1.2},
-@code{1.3}, etc.
-
-When adding a new file, the second number will always
-be one and the first number will equal the highest
-first number of any file in that directory.  For
-example, the current directory contains files whose
-highest numbered revisions are @code{1.7}, @code{3.1},
-and @code{4.12}, then an added file will be given the
-numeric revision @code{4.1}.
-(When using client/server @sc{cvs},
-only files that are actually sent to the server are considered.)
-
-@c This is sort of redundant with something we said a
-@c while ago.  Somewhere we need a better way of
-@c introducing how the first number can be anything
-@c except "1", perhaps.  Also I don't think this
-@c presentation is clear on why we are discussing releases
-@c and first numbers of numeric revisions in the same
-@c breath.
-Normally there is no reason to care
-about the revision numbers---it is easier to treat them
-as internal numbers that @sc{cvs} maintains, and tags
-provide a better way to distinguish between things like
-release 1 versus release 2 of your product
-(@pxref{Tags}).  However, if you want to set the
-numeric revisions, the @samp{-r} option to @code{cvs
-commit} can do that.  The @samp{-r} option implies the
-@samp{-f} option, in the sense that it causes the
-files to be committed even if they are not modified.
-
-For example, to bring all your files up to
-revision 3.0 (including those that haven't changed),
-you might invoke:
-
-@example
-$ cvs commit -r 3.0
-@end example
-
-Note that the number you specify with @samp{-r} must be
-larger than any existing revision number.  That is, if
-revision 3.0 exists, you cannot @samp{cvs commit
--r 1.3}.  If you want to maintain several releases in
-parallel, you need to use a branch (@pxref{Branching and merging}).
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Tags
-@section Tags--Symbolic revisions
-@cindex Tags
-
-The revision numbers live a life of their own.  They
-need not have anything at all to do with the release
-numbers of your software product.  Depending
-on how you use @sc{cvs} the revision numbers might change several times
-between two releases.  As an example, some of the
-source files that make up @sc{rcs} 5.6 have the following
-revision numbers:
-@cindex RCS revision numbers
-
-@example
-ci.c            5.21
-co.c            5.9
-ident.c         5.3
-rcs.c           5.12
-rcsbase.h       5.11
-rcsdiff.c       5.10
-rcsedit.c       5.11
-rcsfcmp.c       5.9
-rcsgen.c        5.10
-rcslex.c        5.11
-rcsmap.c        5.2
-rcsutil.c       5.10
-@end example
-
-@cindex tag (subcommand), introduction
-@cindex Tags, symbolic name
-@cindex Symbolic name (tag)
-@cindex Name, symbolic (tag)
-@cindex HEAD, as reserved tag name
-@cindex BASE, as reserved tag name
-You can use the @code{tag} command to give a symbolic name to a
-certain revision of a file.  You can use the @samp{-v} flag to the
-@code{status} command to see all tags that a file has, and
-which revision numbers they represent.  Tag names must
-start with an uppercase or lowercase letter and can
-contain uppercase and lowercase letters, digits,
-@samp{-}, and @samp{_}.  The two tag names @code{BASE}
-and @code{HEAD} are reserved for use by @sc{cvs}.  It
-is expected that future names which are special to
-@sc{cvs} will be specially named, for example by
-starting with @samp{.}, rather than being named analogously to
-@code{BASE} and @code{HEAD}, to avoid conflicts with
-actual tag names.
-@c Including a character such as % or = has also been
-@c suggested as the naming convention for future
-@c special tag names.  Starting with . is nice because
-@c that is not a legal tag name as far as RCS is concerned.
-@c FIXME: CVS actually accepts quite a few characters
-@c in tag names, not just the ones documented above
-@c (see RCS_check_tag).  RCS
-@c defines legitimate tag names by listing illegal
-@c characters rather than legal ones.  CVS is said to lose its
-@c mind if you try to use "/" (try making such a tag sticky
-@c and using "cvs status" client/server--see remote
-@c protocol format for entries line for probable cause).
-@c TODO: The testsuite
-@c should test for whatever are documented above as
-@c officially-OK tag names, and CVS should at least reject
-@c characters that won't work, like "/".
-
-You'll want to choose some convention for naming tags,
-based on information such as the name of the program
-and the version number of the release.  For example,
-one might take the name of the program, immediately
-followed by the version number with @samp{.} changed to
-@samp{-}, so that @sc{cvs} 1.9 would be tagged with the name
-@code{cvs1-9}.  If you choose a consistent convention,
-then you won't constantly be guessing whether a tag is
-@code{cvs-1-9} or @code{cvs1_9} or what.  You might
-even want to consider enforcing your convention in the
-@file{taginfo} file (@pxref{taginfo}).
-@c Might be nice to say more about using taginfo this
-@c way, like giving an example, or pointing out any particular
-@c issues which arise.
-
-@cindex Adding a tag
-@cindex Tags, example
-The following example shows how you can add a tag to a
-file.  The commands must be issued inside your working
-directory.  That is, you should issue the
-command in the directory where @file{backend.c}
-resides.
-
-@example
-$ cvs tag rel-0-4 backend.c
-T backend.c
-$ cvs status -v backend.c
-===================================================================
-File: backend.c         Status: Up-to-date
-
-    Version:            1.4     Tue Dec  1 14:39:01 1992
-    RCS Version:        1.4     /u/cvsroot/yoyodyne/tc/backend.c,v
-    Sticky Tag:         (none)
-    Sticky Date:        (none)
-    Sticky Options:     (none)
-
-    Existing Tags:
-        rel-0-4                     (revision: 1.4)
-
-@end example
-
-For a complete summary of the syntax of @code{cvs tag},
-including the various options, see @ref{Invoking CVS}.
-
-There is seldom reason to tag a file in isolation.  A more common use is
-to tag all the files that constitute a module with the same tag at
-strategic points in the development life-cycle, such as when a release
-is made.
-
-@example
-$ cvs tag rel-1-0 .
-cvs tag: Tagging .
-T Makefile
-T backend.c
-T driver.c
-T frontend.c
-T parser.c
-@end example
-
-@noindent
-(When you give @sc{cvs} a directory as argument, it generally applies the
-operation to all the files in that directory, and (recursively), to any
-subdirectories that it may contain.  @xref{Recursive behavior}.)
-
-@cindex Retrieving an old revision using tags
-@cindex Tags, retrieving old revisions
-The @code{checkout} command has a flag, @samp{-r}, that lets you check out
-a certain revision of a module.  This flag makes it easy to
-retrieve the sources that make up release 1.0 of the module @samp{tc} at
-any time in the future:
-
-@example
-$ cvs checkout -r rel-1-0 tc
-@end example
-
-@noindent
-This is useful, for instance, if someone claims that there is a bug in
-that release, but you cannot find the bug in the current working copy.
-
-You can also check out a module as it was on any branch at any given date.
-@xref{checkout options}.  When specifying @samp{-r} or @samp{-D} to
-any of these commands, you will need beware of sticky
-tags; see @ref{Sticky tags}.
-
-When you tag more than one file with the same tag you
-can think about the tag as "a curve drawn through a
-matrix of filename vs. revision number."  Say we have 5
-files with the following revisions:
-
-@example
-@group
-        file1   file2   file3   file4   file5
-
-        1.1     1.1     1.1     1.1  /--1.1*      <-*-  TAG
-        1.2*-   1.2     1.2    -1.2*-
-        1.3  \- 1.3*-   1.3   / 1.3
-        1.4          \  1.4  /  1.4
-                      \-1.5*-   1.5
-                        1.6
-@end group
-@end example
-
-At some time in the past, the @code{*} versions were tagged.
-You can think of the tag as a handle attached to the curve
-drawn through the tagged revisions.  When you pull on
-the handle, you get all the tagged revisions.  Another
-way to look at it is that you "sight" through a set of
-revisions that is "flat" along the tagged revisions,
-like this:
-
-@example
-@group
-        file1   file2   file3   file4   file5
-
-                        1.1
-                        1.2
-                1.1     1.3                       _
-        1.1     1.2     1.4     1.1              /
-        1.2*----1.3*----1.5*----1.2*----1.1*    (--- <--- Look here
-        1.3             1.6     1.3              \_
-        1.4                     1.4
-                                1.5
-@end group
-@end example
-
-@node Tagging the working directory
-@section Specifying what to tag from the working directory
-
-@cindex tag (subcommand)
-The example in the previous section demonstrates one of
-the most common ways to choose which revisions to tag.
-Namely, running the @code{cvs tag} command without
-arguments causes @sc{cvs} to select the revisions which
-are checked out in the current working directory.  For
-example, if the copy of @file{backend.c} in working
-directory was checked out from revision 1.4, then
-@sc{cvs} will tag revision 1.4.  Note that the tag is
-applied immediately to revision 1.4 in the repository;
-tagging is not like modifying a file, or other
-operations in which one first modifies the working
-directory and then runs @code{cvs commit} to transfer
-that modification to the repository.
-
-One potentially surprising aspect of the fact that
-@code{cvs tag} operates on the repository is that you
-are tagging the checked-in revisions, which may differ
-from locally modified files in your working directory.
-If you want to avoid doing this by mistake, specify the
-@samp{-c} option to @code{cvs tag}.  If there are any
-locally modified files, @sc{cvs} will abort with an
-error before it tags any files:
-
-@example
-$ cvs tag -c rel-0-4
-cvs tag: backend.c is locally modified
-cvs [tag aborted]: correct the above errors first!
-@end example
-
-@node Tagging by date/tag
-@section Specifying what to tag by date or revision
-@cindex rtag (subcommand)
-
-The @code{cvs rtag} command tags the repository as of a
-certain date or time (or can be used to tag the latest
-revision).  @code{rtag} works directly on the
-repository contents (it requires no prior checkout and
-does not look for a working directory).
-
-The following options specify which date or revision to
-tag.  See @ref{Common options}, for a complete
-description of them.
-
-@table @code
-@item -D @var{date}
-Tag the most recent revision no later than @var{date}.
-
-@item -f
-Only useful with the @samp{-D} or @samp{-r}
-flags.  If no matching revision is found, use the most
-recent revision (instead of ignoring the file).
-
-@item -r @var{tag}[:@var{date}]
-Tag the revision already tagged with @var{tag} or, when @var{date} is specified
-and @var{tag} is a branch tag, the version from the branch @var{tag} as it
-existed on @var{date}.  See @ref{Common options}.
-@end table
-
-The @code{cvs tag} command also allows one to specify
-files by revision or date, using the same @samp{-r},
-@samp{-D}, and @samp{-f} options.  However, this
-feature is probably not what you want.  The reason is
-that @code{cvs tag} chooses which files to tag based on
-the files that exist in the working directory, rather
-than the files which existed as of the given tag/date.
-Therefore, you are generally better off using @code{cvs
-rtag}.  The exceptions might be cases like:
-
-@example
-cvs tag -r 1.4 stable backend.c
-@end example
-
-@node Modifying tags
-@section Deleting, moving, and renaming tags
-
-@c Also see:
-@c  "How do I move or rename a magic branch tag?"
-@c in the FAQ (I think the issues it talks about still
-@c apply, but this could use some sanity.sh work).
-
-Normally one does not modify tags.  They exist in order
-to record the history of the repository and so deleting
-them or changing their meaning would, generally, not be
-what you want.
-
-However, there might be cases in which one uses a tag
-temporarily or accidentally puts one in the wrong
-place.  Therefore, one might delete, move, or rename a
-tag.
-
-@noindent
-@strong{WARNING: the commands in this section are
-dangerous; they permanently discard historical
-information and it can be difficult or impossible to
-recover from errors.  If you are a @sc{cvs}
-administrator, you may consider restricting these
-commands with the @file{taginfo} file (@pxref{taginfo}).}
-
-@cindex Deleting tags
-@cindex Deleting branch tags
-@cindex Removing tags
-@cindex Removing branch tags
-@cindex Tags, deleting
-@cindex Branch tags, deleting
-To delete a tag, specify the @samp{-d} option to either
-@code{cvs tag} or @code{cvs rtag}.  For example:
-
-@example
-cvs rtag -d rel-0-4 tc
-@end example
-
-@noindent
-deletes the non-branch tag @code{rel-0-4} from the module @code{tc}.
-In the event that branch tags are encountered within the repository
-with the given name, a warning message will be issued and the branch 
-tag will not be deleted.  If you are absolutely certain you know what
-you are doing, the @code{-B} option may be specified to allow deletion
-of branch tags.  In that case, any non-branch tags encountered will
-trigger warnings and will not be deleted.
-
-@noindent
-@strong{WARNING: Moving branch tags is very dangerous!  If you think
-you need the @code{-B} option, think again and ask your @sc{cvs}
-administrator about it (if that isn't you).  There is almost certainly
-another way to accomplish what you want to accomplish.}
-
-@cindex Moving tags
-@cindex Moving branch tags
-@cindex Tags, moving
-@cindex Branch tags, moving
-When we say @dfn{move} a tag, we mean to make the same
-name point to different revisions.  For example, the
-@code{stable} tag may currently point to revision 1.4
-of @file{backend.c} and perhaps we want to make it
-point to revision 1.6.  To move a non-branch tag, specify the
-@samp{-F} option to either @code{cvs tag} or @code{cvs
-rtag}.  For example, the task just mentioned might be
-accomplished as:
-
-@example
-cvs tag -r 1.6 -F stable backend.c
-@end example
-
-@noindent
-If any branch tags are encountered in the repository 
-with the given name, a warning is issued and the branch
-tag is not disturbed.  If you are absolutely certain you
-wish to move the branch tag, the @code{-B} option may be specified.
-In that case, non-branch tags encountered with the given
-name are ignored with a warning message.
-
-@noindent
-@strong{WARNING: Moving branch tags is very dangerous!  If you think you
-need the @code{-B} option, think again and ask your @sc{cvs}
-administrator about it (if that isn't you).  There is almost certainly
-another way to accomplish what you want to accomplish.}
-
-@cindex Renaming tags
-@cindex Tags, renaming
-When we say @dfn{rename} a tag, we mean to make a
-different name point to the same revisions as the old
-tag.  For example, one may have misspelled the tag name
-and want to correct it (hopefully before others are
-relying on the old spelling).  To rename a tag, first
-create a new tag using the @samp{-r} option to
-@code{cvs rtag}, and then delete the old name.  (Caution:
-this method will not work with branch tags.) 
-This leaves the new tag on exactly the 
-same files as the old tag.  For example:
-
-@example
-cvs rtag -r old-name-0-4 rel-0-4 tc
-cvs rtag -d old-name-0-4 tc
-@end example
-
-@node Tagging add/remove
-@section Tagging and adding and removing files
-
-The subject of exactly how tagging interacts with
-adding and removing files is somewhat obscure; for the
-most part @sc{cvs} will keep track of whether files
-exist or not without too much fussing.  By default,
-tags are applied to only files which have a revision
-corresponding to what is being tagged.  Files which did
-not exist yet, or which were already removed, simply
-omit the tag, and @sc{cvs} knows to treat the absence
-of a tag as meaning that the file didn't exist as of
-that tag.
-
-However, this can lose a small amount of information.
-For example, suppose a file was added and then removed.
-Then, if the tag is missing for that file, there is no
-way to know whether the tag refers to the time before
-the file was added, or the time after it was removed.
-If you specify the @samp{-r} option to @code{cvs rtag},
-then @sc{cvs} tags the files which have been removed,
-and thereby avoids this problem.  For example, one
-might specify @code{-r HEAD} to tag the head.
-
-On the subject of adding and removing files, the
-@code{cvs rtag} command has a @samp{-a} option which
-means to clear the tag from removed files that would
-not otherwise be tagged.  For example, one might
-specify this option in conjunction with @samp{-F} when
-moving a tag.  If one moved a tag without @samp{-a},
-then the tag in the removed files might still refer to
-the old revision, rather than reflecting the fact that
-the file had been removed.  I don't think this is
-necessary if @samp{-r} is specified, as noted above.
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Sticky tags
-@section Sticky tags
-@cindex Sticky tags
-@cindex Tags, sticky
-
-@c A somewhat related issue is per-directory sticky
-@c tags (see comment at CVS/Tag in node Working
-@c directory storage); we probably want to say
-@c something like "you can set a sticky tag for only
-@c some files, but you don't want to" or some such.
-
-Sometimes a working copy's revision has extra data
-associated with it, for example it might be on a branch
-(@pxref{Branching and merging}), or restricted to
-versions prior to a certain date by @samp{checkout -D}
-or @samp{update -D}.  Because this data persists --
-that is, it applies to subsequent commands in the
-working copy -- we refer to it as @dfn{sticky}.
-
-Most of the time, stickiness is an obscure aspect of
-@sc{cvs} that you don't need to think about.  However,
-even if you don't want to use the feature, you may need
-to know @emph{something} about sticky tags (for
-example, how to avoid them!).
-
-You can use the @code{status} command to see if any
-sticky tags or dates are set:
-
-@example
-$ cvs status driver.c
-===================================================================
-File: driver.c          Status: Up-to-date
-
-    Version:            1.7.2.1 Sat Dec  5 19:35:03 1992
-    RCS Version:        1.7.2.1 /u/cvsroot/yoyodyne/tc/driver.c,v
-    Sticky Tag:         rel-1-0-patches (branch: 1.7.2)
-    Sticky Date:        (none)
-    Sticky Options:     (none)
-
-@end example
-
-@cindex Resetting sticky tags
-@cindex Sticky tags, resetting
-@cindex Deleting sticky tags
-The sticky tags will remain on your working files until
-you delete them with @samp{cvs update -A}.  The
-@samp{-A} option merges local changes into the version of the
-file from the head of the trunk, removing any sticky tags,
-dates, or options.  See @ref{update} for more on the operation
-of @code{cvs update}.
-
-@cindex Sticky date
-The most common use of sticky tags is to identify which
-branch one is working on, as described in
-@ref{Accessing branches}.  However, non-branch
-sticky tags have uses as well.  For example,
-suppose that you want to avoid updating your working
-directory, to isolate yourself from possibly
-destabilizing changes other people are making.  You
-can, of course, just refrain from running @code{cvs
-update}.  But if you want to avoid updating only a
-portion of a larger tree, then sticky tags can help.
-If you check out a certain revision (such as 1.4) it
-will become sticky.  Subsequent @code{cvs update}
-commands will
-not retrieve the latest revision until you reset the
-tag with @code{cvs update -A}.  Likewise, use of the
-@samp{-D} option to @code{update} or @code{checkout}
-sets a @dfn{sticky date}, which, similarly, causes that
-date to be used for future retrievals.
-
-People often want to retrieve an old version of
-a file without setting a sticky tag.  This can
-be done with the @samp{-p} option to @code{checkout} or
-@code{update}, which sends the contents of the file to
-standard output.  For example:
-@example
-$ cvs update -p -r 1.1 file1 >file1
-===================================================================
-Checking out file1
-RCS:  /tmp/cvs-sanity/cvsroot/first-dir/Attic/file1,v
-VERS: 1.1
-***************
-$
-@end example
-
-However, this isn't the easiest way, if you are asking
-how to undo a previous checkin (in this example, put
-@file{file1} back to the way it was as of revision
-1.1).  In that case you are better off using the
-@samp{-j} option to @code{update}; for further
-discussion see @ref{Merging two revisions}.
-
-@c ---------------------------------------------------------------------
-@node Branching and merging
-@chapter Branching and merging
-@cindex Branching
-@cindex Merging
-@cindex Copying changes
-@cindex Main trunk and branches
-@cindex Revision tree, making branches
-@cindex Branches, copying changes between
-@cindex Changes, copying between branches
-@cindex Modifications, copying between branches
-
-@sc{cvs} allows you to isolate changes onto a separate
-line of development, known as a @dfn{branch}.  When you
-change files on a branch, those changes do not appear
-on the main trunk or other branches.
-
-Later you can move changes from one branch to another
-branch (or the main trunk) by @dfn{merging}.  Merging
-involves first running @code{cvs update -j}, to merge
-the changes into the working directory.
-You can then commit that revision, and thus effectively
-copy the changes onto another branch.
-
-@menu
-* Branches motivation::         What branches are good for
-* Creating a branch::           Creating a branch
-* Accessing branches::          Checking out and updating branches
-* Branches and revisions::      Branches are reflected in revision numbers
-* Magic branch numbers::        Magic branch numbers
-* Merging a branch::            Merging an entire branch
-* Merging more than once::      Merging from a branch several times
-* Merging two revisions::       Merging differences between two revisions
-* Merging adds and removals::   What if files are added or removed?
-* Merging and keywords::        Avoiding conflicts due to keyword substitution
-@end menu
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Branches motivation
-@section What branches are good for
-@cindex Branches motivation
-@cindex What branches are good for
-@cindex Motivation for branches
-
-@c FIXME: this node mentions one way to use branches,
-@c but it is by no means the only way.  For example,
-@c the technique of committing a new feature on a branch,
-@c until it is ready for the main trunk.  The whole
-@c thing is generally speaking more akin to the
-@c "Revision management" node although it isn't clear to
-@c me whether policy matters should be centralized or
-@c distributed throughout the relevant sections.
-Suppose that release 1.0 of tc has been made.  You are continuing to
-develop tc, planning to create release 1.1 in a couple of months.  After a
-while your customers start to complain about a fatal bug.  You check
-out release 1.0 (@pxref{Tags}) and find the bug
-(which turns out to have a trivial fix).  However, the current revision
-of the sources are in a state of flux and are not expected to be stable
-for at least another month.  There is no way to make a
-bug fix release based on the newest sources.
-
-The thing to do in a situation like this is to create a @dfn{branch} on
-the revision trees for all the files that make up
-release 1.0 of tc.  You can then make
-modifications to the branch without disturbing the main trunk.  When the
-modifications are finished you can elect to either incorporate them on
-the main trunk, or leave them on the branch.
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Creating a branch
-@section Creating a branch
-@cindex Creating a branch
-@cindex Branch, creating a
-@cindex tag (subcommand), creating a branch using
-@cindex rtag (subcommand), creating a branch using
-
-You can create a branch with @code{tag -b}; for
-example, assuming you're in a working copy:
-
-@example
-$ cvs tag -b rel-1-0-patches
-@end example
-
-@c FIXME: we should be more explicit about the value of
-@c having a tag on the branchpoint.  For example
-@c "cvs tag rel-1-0-patches-branchpoint" before
-@c the "cvs tag -b".  This points out that
-@c rel-1-0-patches is a pretty awkward name for
-@c this example (more so than for the rtag example
-@c below).
-
-This splits off a branch based on the current revisions
-in the working copy, assigning that branch the name
-@samp{rel-1-0-patches}.
-
-It is important to understand that branches get created
-in the repository, not in the working copy.  Creating a
-branch based on current revisions, as the above example
-does, will @emph{not} automatically switch the working
-copy to be on the new branch.  For information on how
-to do that, see @ref{Accessing branches}.
-
-You can also create a branch without reference to any
-working copy, by using @code{rtag}:
-
-@example
-$ cvs rtag -b -r rel-1-0 rel-1-0-patches tc
-@end example
-
-@samp{-r rel-1-0} says that this branch should be
-rooted at the revision that
-corresponds to the tag @samp{rel-1-0}.  It need not
-be the most recent revision -- it's often useful to
-split a branch off an old revision (for example, when
-fixing a bug in a past release otherwise known to be
-stable).
-
-As with @samp{tag}, the @samp{-b} flag tells
-@code{rtag} to create a branch (rather than just a
-symbolic revision name).  Note that the numeric
-revision number that matches @samp{rel-1-0} will
-probably be different from file to file.
-
-So, the full effect of the command is to create a new
-branch -- named @samp{rel-1-0-patches} -- in module
-@samp{tc}, rooted in the revision tree at the point tagged
-by @samp{rel-1-0}.
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Accessing branches
-@section Accessing branches
-@cindex Check out a branch
-@cindex Retrieve a branch
-@cindex Access a branch
-@cindex Identifying a branch
-@cindex Branch, check out
-@cindex Branch, retrieving
-@cindex Branch, accessing
-@cindex Branch, identifying
-
-You can retrieve a branch in one of two ways: by
-checking it out fresh from the repository, or by
-switching an existing working copy over to the branch.
-
-To check out a branch from the repository, invoke
-@samp{checkout} with the @samp{-r} flag, followed by
-the tag name of the branch (@pxref{Creating a branch}):
-
-@example
-$ cvs checkout -r rel-1-0-patches tc
-@end example
-
-Or, if you already have a working copy, you can switch
-it to a given branch with @samp{update -r}:
-
-@example
-$ cvs update -r rel-1-0-patches tc
-@end example
-
-@noindent
-or equivalently:
-
-@example
-$ cd tc
-$ cvs update -r rel-1-0-patches
-@end example
-
-It does not matter if the working copy was originally
-on the main trunk or on some other branch -- the above
-command will switch it to the named branch.  And
-similarly to a regular @samp{update} command,
-@samp{update -r} merges any changes you have made,
-notifying you of conflicts where they occur.
-
-Once you have a working copy tied to a particular
-branch, it remains there until you tell it otherwise.
-This means that changes checked in from the working
-copy will add new revisions on that branch, while
-leaving the main trunk and other branches unaffected.
-
-@cindex Branches, sticky
-To find out what branch a working copy is on, you can
-use the @samp{status} command.  In its output, look for
-the field named @samp{Sticky tag} (@pxref{Sticky tags})
--- that's @sc{cvs}'s way of telling you the branch, if
-any, of the current working files:
-
-@example
-$ cvs status -v driver.c backend.c
-===================================================================
-File: driver.c          Status: Up-to-date
-
-    Version:            1.7     Sat Dec  5 18:25:54 1992
-    RCS Version:        1.7     /u/cvsroot/yoyodyne/tc/driver.c,v
-    Sticky Tag:         rel-1-0-patches (branch: 1.7.2)
-    Sticky Date:        (none)
-    Sticky Options:     (none)
-
-    Existing Tags:
-        rel-1-0-patches             (branch: 1.7.2)
-        rel-1-0                     (revision: 1.7)
-
-===================================================================
-File: backend.c         Status: Up-to-date
-
-    Version:            1.4     Tue Dec  1 14:39:01 1992
-    RCS Version:        1.4     /u/cvsroot/yoyodyne/tc/backend.c,v
-    Sticky Tag:         rel-1-0-patches (branch: 1.4.2)
-    Sticky Date:        (none)
-    Sticky Options:     (none)
-
-    Existing Tags:
-        rel-1-0-patches             (branch: 1.4.2)
-        rel-1-0                     (revision: 1.4)
-        rel-0-4                     (revision: 1.4)
-
-@end example
-
-Don't be confused by the fact that the branch numbers
-for each file are different (@samp{1.7.2} and
-@samp{1.4.2} respectively).  The branch tag is the
-same, @samp{rel-1-0-patches}, and the files are
-indeed on the same branch.  The numbers simply reflect
-the point in each file's revision history at which the
-branch was made.  In the above example, one can deduce
-that @samp{driver.c} had been through more changes than
-@samp{backend.c} before this branch was created.
-
-See @ref{Branches and revisions} for details about how
-branch numbers are constructed.
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Branches and revisions
-@section Branches and revisions
-@cindex Branch number
-@cindex Number, branch
-@cindex Revision numbers (branches)
-
-Ordinarily, a file's revision history is a linear
-series of increments (@pxref{Revision numbers}):
-
-@example
-       +-----+    +-----+    +-----+    +-----+    +-----+
-       ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !
-       +-----+    +-----+    +-----+    +-----+    +-----+
-@end example
-
-However, @sc{cvs} is not limited to linear development.  The
-@dfn{revision tree} can be split into @dfn{branches},
-where each branch is a self-maintained line of
-development.  Changes made on one branch can easily be
-moved back to the main trunk.
-
-Each branch has a @dfn{branch number}, consisting of an
-odd number of period-separated decimal integers.  The
-branch number is created by appending an integer to the
-revision number where the corresponding branch forked
-off.  Having branch numbers allows more than one branch
-to be forked off from a certain revision.
-
-@need 3500
-All revisions on a branch have revision numbers formed
-by appending an ordinal number to the branch number.
-The following figure illustrates branching with an
-example.
-
-@example
-@c This example used to have a 1.2.2.4 revision, which
-@c might help clarify that development can continue on
-@c 1.2.2.  Might be worth reinstating if it can be done
-@c without overfull hboxes.
-@group
-                                                      +-------------+
-                           Branch 1.2.2.3.2 ->        ! 1.2.2.3.2.1 !
-                                                    / +-------------+
-                                                   /
-                                                  /
-                 +---------+    +---------+    +---------+
-Branch 1.2.2 -> _! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 !
-               / +---------+    +---------+    +---------+
-              /
-             /
-+-----+    +-----+    +-----+    +-----+    +-----+
-! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !  <- The main trunk
-+-----+    +-----+    +-----+    +-----+    +-----+
-                !
-                !
-                !   +---------+    +---------+    +---------+
-Branch 1.2.4 -> +---! 1.2.4.1 !----! 1.2.4.2 !----! 1.2.4.3 !
-                    +---------+    +---------+    +---------+
-
-@end group
-@end example
-
-@c --   However, at least for me the figure is not enough.  I suggest more
-@c --   text to accompany it.  "A picture is worth a thousand words", so you
-@c --   have to make sure the reader notices the couple of hundred words
-@c --   *you* had in mind more than the others!
-
-@c --   Why an even number of segments?  This section implies that this is
-@c --   how the main trunk is distinguished from branch roots, but you never
-@c --   explicitly say that this is the purpose of the [by itself rather
-@c --   surprising] restriction to an even number of segments.
-
-The exact details of how the branch number is
-constructed is not something you normally need to be
-concerned about, but here is how it works: When
-@sc{cvs} creates a branch number it picks the first
-unused even integer, starting with 2.  So when you want
-to create a branch from revision 6.4 it will be
-numbered 6.4.2.  All branch numbers ending in a zero
-(such as 6.4.0) are used internally by @sc{cvs}
-(@pxref{Magic branch numbers}).  The branch 1.1.1 has a
-special meaning.  @xref{Tracking sources}.
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Magic branch numbers
-@section Magic branch numbers
-
-@c Want xref to here from "log"?
-
-This section describes a @sc{cvs} feature called
-@dfn{magic branches}.  For most purposes, you need not
-worry about magic branches; @sc{cvs} handles them for
-you.  However, they are visible to you in certain
-circumstances, so it may be useful to have some idea of
-how it works.
-
-Externally, branch numbers consist of an odd number of
-dot-separated decimal integers.  @xref{Revision
-numbers}.  That is not the whole truth, however.  For
-efficiency reasons @sc{cvs} sometimes inserts an extra 0
-in the second rightmost position (1.2.4 becomes
-1.2.0.4, 8.9.10.11.12 becomes 8.9.10.11.0.12 and so
-on).
-
-@sc{cvs} does a pretty good job at hiding these so
-called magic branches, but in a few places the hiding
-is incomplete:
-
-@itemize @bullet
-@ignore
-@c This is in ignore as I'm taking their word for it,
-@c that this was fixed
-@c a long time ago.  But before deleting this
-@c entirely, I'd rather verify it (and add a test
-@c case to the testsuite).
-@item
-The magic branch can appear in the output from
-@code{cvs status} in vanilla @sc{cvs} 1.3.  This is
-fixed in @sc{cvs} 1.3-s2.
-
-@end ignore
-@item
-The magic branch number appears in the output from
-@code{cvs log}.
-@c What output should appear instead?
-
-@item
-You cannot specify a symbolic branch name to @code{cvs
-admin}.
-
-@end itemize
-
-@c Can CVS do this automatically the first time
-@c you check something in to that branch?  Should
-@c it?
-You can use the @code{admin} command to reassign a
-symbolic name to a branch the way @sc{rcs} expects it
-to be.  If @code{R4patches} is assigned to the branch
-1.4.2 (magic branch number 1.4.0.2) in file
-@file{numbers.c} you can do this:
-
-@example
-$ cvs admin -NR4patches:1.4.2 numbers.c
-@end example
-
-It only works if at least one revision is already
-committed on the branch.  Be very careful so that you
-do not assign the tag to the wrong number.  (There is
-no way to see how the tag was assigned yesterday).
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Merging a branch
-@section Merging an entire branch
-@cindex Merging a branch
-@cindex -j (merging branches)
-
-You can merge changes made on a branch into your working copy by giving
-the @samp{-j @var{branchname}} flag to the @code{update} subcommand.  With one
-@samp{-j @var{branchname}} option it merges the changes made between the
-greatest common ancestor (GCA) of the branch and the destination revision (in
-the simple case below the GCA is the point where the branch forked) and the
-newest revision on that branch into your working copy.
-
-@cindex Join
-The @samp{-j} stands for ``join''.
-
-@cindex Branch merge example
-@cindex Example, branch merge
-@cindex Merge, branch example
-Consider this revision tree:
-
-@example
-+-----+    +-----+    +-----+    +-----+
-! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !      <- The main trunk
-+-----+    +-----+    +-----+    +-----+
-                !
-                !
-                !   +---------+    +---------+
-Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !
-                    +---------+    +---------+
-@end example
-
-@noindent
-The branch 1.2.2 has been given the tag (symbolic name) @samp{R1fix}.  The
-following example assumes that the module @samp{mod} contains only one
-file, @file{m.c}.
-
-@example
-$ cvs checkout mod               # @r{Retrieve the latest revision, 1.4}
-
-$ cvs update -j R1fix m.c        # @r{Merge all changes made on the branch,}
-                                 # @r{i.e. the changes between revision 1.2}
-                                 # @r{and 1.2.2.2, into your working copy}
-                                 # @r{of the file.}
-
-$ cvs commit -m "Included R1fix" # @r{Create revision 1.5.}
-@end example
-
-A conflict can result from a merge operation.  If that
-happens, you should resolve it before committing the
-new revision.  @xref{Conflicts example}.
-
-If your source files contain keywords (@pxref{Keyword substitution}),
-you might be getting more conflicts than strictly necessary.  See
-@ref{Merging and keywords}, for information on how to avoid this.
-
-The @code{checkout} command also supports the @samp{-j @var{branchname}} flag.  The
-same effect as above could be achieved with this:
-
-@example
-$ cvs checkout -j R1fix mod
-$ cvs commit -m "Included R1fix"
-@end example
-
-It should be noted that @code{update -j @var{tagname}} will also work but may
-not produce the desired result.  @xref{Merging adds and removals}, for more.
-
-@node Merging more than once
-@section Merging from a branch several times
-
-Continuing our example, the revision tree now looks
-like this:
-
-@example
-+-----+    +-----+    +-----+    +-----+    +-----+
-! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !   <- The main trunk
-+-----+    +-----+    +-----+    +-----+    +-----+
-                !                           *
-                !                          *
-                !   +---------+    +---------+
-Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !
-                    +---------+    +---------+
-@end example
-
-@noindent
-where the starred line represents the merge from the
-@samp{R1fix} branch to the main trunk, as just
-discussed.
-
-Now suppose that development continues on the
-@samp{R1fix} branch:
-
-@example
-+-----+    +-----+    +-----+    +-----+    +-----+
-! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !   <- The main trunk
-+-----+    +-----+    +-----+    +-----+    +-----+
-                !                           *
-                !                          *
-                !   +---------+    +---------+    +---------+
-Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 !
-                    +---------+    +---------+    +---------+
-@end example
-
-@noindent
-and then you want to merge those new changes onto the
-main trunk.  If you just use the @code{cvs update -j
-R1fix m.c} command again, @sc{cvs} will attempt to
-merge again the changes which you have already merged,
-which can have undesirable side effects.
-
-So instead you need to specify that you only want to
-merge the changes on the branch which have not yet been
-merged into the trunk.  To do that you specify two
-@samp{-j} options, and @sc{cvs} merges the changes from
-the first revision to the second revision.  For
-example, in this case the simplest way would be
-
-@example
-cvs update -j 1.2.2.2 -j R1fix m.c    # @r{Merge changes from 1.2.2.2 to the}
-                                      # @r{head of the R1fix branch}
-@end example
-
-The problem with this is that you need to specify the
-1.2.2.2 revision manually.  A slightly better approach
-might be to use the date the last merge was done:
-
-@example
-cvs update -j R1fix:yesterday -j R1fix m.c
-@end example
-
-Better yet, tag the R1fix branch after every merge into
-the trunk, and then use that tag for subsequent merges:
-
-@example
-cvs update -j merged_from_R1fix_to_trunk -j R1fix m.c
-@end example
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Merging two revisions
-@section Merging differences between any two revisions
-@cindex Merging two revisions
-@cindex Revisions, merging differences between
-@cindex Differences, merging
-
-With two @samp{-j @var{revision}} flags, the @code{update}
-(and @code{checkout}) command can merge the differences
-between any two revisions into your working file.
-
-@cindex Undoing a change
-@cindex Removing a change
-@example
-$ cvs update -j 1.5 -j 1.3 backend.c
-@end example
-
-@noindent
-will undo all changes made between revision
-1.3 and 1.5.  Note the order of the revisions!
-
-If you try to use this option when operating on
-multiple files, remember that the numeric revisions will
-probably be very different between the various files.
-You almost always use symbolic
-tags rather than revision numbers when operating on
-multiple files.
-
-@cindex Restoring old version of removed file
-@cindex Resurrecting old version of dead file
-Specifying two @samp{-j} options can also undo file
-removals or additions.  For example, suppose you have
-a file
-named @file{file1} which existed as revision 1.1, and
-you then removed it (thus adding a dead revision 1.2).
-Now suppose you want to add it again, with the same
-contents it had previously.  Here is how to do it:
-
-@example
-$ cvs update -j 1.2 -j 1.1 file1
-U file1
-$ cvs commit -m test
-Checking in file1;
-/tmp/cvs-sanity/cvsroot/first-dir/file1,v  <--  file1
-new revision: 1.3; previous revision: 1.2
-done
-$
-@end example
-
-@node Merging adds and removals
-@section Merging can add or remove files
-
-If the changes which you are merging involve removing
-or adding some files, @code{update -j} will reflect
-such additions or removals.
-
-@c FIXME: This example needs a lot more explanation.
-@c We also need other examples for some of the other
-@c cases (not all--there are too many--as long as we present a
-@c coherent general principle).
-For example:
-@example
-cvs update -A
-touch a b c
-cvs add a b c ; cvs ci -m "added" a b c
-cvs tag -b branchtag
-cvs update -r branchtag
-touch d ; cvs add d
-rm a ; cvs rm a
-cvs ci -m "added d, removed a"
-cvs update -A
-cvs update -jbranchtag
-@end example
-
-After these commands are executed and a @samp{cvs commit} is done,
-file @file{a} will be removed and file @file{d} added in the main branch.
-@c (which was determined by trying it)
-
-Note that using a single static tag (@samp{-j @var{tagname}})
-rather than a dynamic tag (@samp{-j @var{branchname}}) to merge
-changes from a branch will usually not remove files which were removed on the
-branch since @sc{cvs} does not automatically add static tags to dead revisions.
-The exception to this rule occurs when
-a static tag has been attached to a dead revision manually.  Use the branch tag
-to merge all changes from the branch or use two static tags as merge endpoints
-to be sure that all intended changes are propagated in the merge.
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Merging and keywords
-@section Merging and keywords
-@cindex Merging, and keyword substitution
-@cindex Keyword substitution, and merging
-@cindex -j (merging branches), and keyword substitution
-@cindex -kk, to avoid conflicts during a merge
-
-If you merge files containing keywords (@pxref{Keyword
-substitution}), you will normally get numerous
-conflicts during the merge, because the keywords are
-expanded differently in the revisions which you are
-merging.
-
-Therefore, you will often want to specify the
-@samp{-kk} (@pxref{Substitution modes}) switch to the
-merge command line.  By substituting just the name of
-the keyword, not the expanded value of that keyword,
-this option ensures that the revisions which you are
-merging will be the same as each other, and avoid
-spurious conflicts.
-
-For example, suppose you have a file like this:
-
-@example
-       +---------+
-      _! 1.1.2.1 !   <-  br1
-     / +---------+
-    /
-   /
-+-----+    +-----+
-! 1.1 !----! 1.2 !
-+-----+    +-----+
-@end example
-
-@noindent
-and your working directory is currently on the trunk
-(revision 1.2).  Then you might get the following
-results from a merge:
-
-@example
-$ cat file1
-key $@splitrcskeyword{Revision}: 1.2 $
-. . .
-$ cvs update -j br1
-U file1
-RCS file: /cvsroot/first-dir/file1,v
-retrieving revision 1.1
-retrieving revision 1.1.2.1
-Merging differences between 1.1 and 1.1.2.1 into file1
-rcsmerge: warning: conflicts during merge
-$ cat file1
-@asis{}<<<<<<< file1
-key $@splitrcskeyword{Revision}: 1.2 $
-@asis{}=======
-key $@splitrcskeyword{Revision}: 1.1.2.1 $
-@asis{}>>>>>>> 1.1.2.1
-. . .
-@end example
-
-What happened was that the merge tried to merge the
-differences between 1.1 and 1.1.2.1 into your working
-directory.  So, since the keyword changed from
-@code{Revision: 1.1} to @code{Revision: 1.1.2.1},
-@sc{cvs} tried to merge that change into your working
-directory, which conflicted with the fact that your
-working directory had contained @code{Revision: 1.2}.
-
-Here is what happens if you had used @samp{-kk}:
-
-@example
-$ cat file1
-key $@splitrcskeyword{Revision}: 1.2 $
-. . .
-$ cvs update -kk -j br1
-U file1
-RCS file: /cvsroot/first-dir/file1,v
-retrieving revision 1.1
-retrieving revision 1.1.2.1
-Merging differences between 1.1 and 1.1.2.1 into file1
-$ cat file1
-key $@splitrcskeyword{Revision}$
-. . .
-@end example
-
-What is going on here is that revision 1.1 and 1.1.2.1
-both expand as plain @code{Revision}, and therefore
-merging the changes between them into the working
-directory need not change anything.  Therefore, there
-is no conflict.
-
-@strong{WARNING: In versions of @sc{cvs} prior to 1.12.2, there was a
-major problem with using @samp{-kk} on merges.  Namely, @samp{-kk}
-overrode any default keyword expansion mode set in the archive file in
-the repository.  This could, unfortunately for some users, cause data
-corruption in binary files (with a default keyword expansion mode set
-to @samp{-kb}).  Therefore, when a repository contained binary files,
-conflicts had to be dealt with manually rather than using @samp{-kk} in
-a merge command.}
-
-In @sc{cvs} version 1.12.2 and later, the keyword expansion mode
-provided on the command line to any @sc{cvs} command no longer
-overrides the @samp{-kb} keyword expansion mode setting for binary
-files, though it will still override other default keyword expansion
-modes.  You can now safely merge using @samp{-kk} to avoid spurious conflicts
-on lines containing RCS keywords, even when your repository contains
-binary files.
-
-@c ---------------------------------------------------------------------
-@node Recursive behavior
-@chapter Recursive behavior
-@cindex Recursive (directory descending)
-@cindex Directory, descending
-@cindex Descending directories
-@cindex Subdirectories
-
-Almost all of the subcommands of @sc{cvs} work
-recursively when you specify a directory as an
-argument.  For instance, consider this directory
-structure:
-
-@example
-      @code{$HOME}
-        |
-        +--@t{tc}
-        |   |
-            +--@t{CVS}
-            |      (internal @sc{cvs} files)
-            +--@t{Makefile}
-            +--@t{backend.c}
-            +--@t{driver.c}
-            +--@t{frontend.c}
-            +--@t{parser.c}
-            +--@t{man}
-            |    |
-            |    +--@t{CVS}
-            |    |  (internal @sc{cvs} files)
-            |    +--@t{tc.1}
-            |
-            +--@t{testing}
-                 |
-                 +--@t{CVS}
-                 |  (internal @sc{cvs} files)
-                 +--@t{testpgm.t}
-                 +--@t{test2.t}
-@end example
-
-@noindent
-If @file{tc} is the current working directory, the
-following is true:
-
-@itemize @bullet
-@item
-@samp{cvs update testing} is equivalent to
-
-@example
-cvs update testing/testpgm.t testing/test2.t
-@end example
-
-@item
-@samp{cvs update testing man} updates all files in the
-subdirectories
-
-@item
-@samp{cvs update .} or just @samp{cvs update} updates
-all files in the @code{tc} directory
-@end itemize
-
-If no arguments are given to @code{update} it will
-update all files in the current working directory and
-all its subdirectories.  In other words, @file{.} is a
-default argument to @code{update}.  This is also true
-for most of the @sc{cvs} subcommands, not only the
-@code{update} command.
-
-The recursive behavior of the @sc{cvs} subcommands can be
-turned off with the @samp{-l} option.
-Conversely, the @samp{-R} option can be used to force recursion if
-@samp{-l} is specified in @file{~/.cvsrc} (@pxref{~/.cvsrc}).
-
-@example
-$ cvs update -l         # @r{Don't update files in subdirectories}
-@end example
-
-@c ---------------------------------------------------------------------
-@node Adding and removing
-@chapter Adding, removing, and renaming files and directories
-
-In the course of a project, one will often add new
-files.  Likewise with removing or renaming, or with
-directories.  The general concept to keep in mind in
-all these cases is that instead of making an
-irreversible change you want @sc{cvs} to record the
-fact that a change has taken place, just as with
-modifying an existing file.  The exact mechanisms to do
-this in @sc{cvs} vary depending on the situation.
-
-@menu
-* Adding files::                Adding files
-* Removing files::              Removing files
-* Removing directories::        Removing directories
-* Moving files::                Moving and renaming files
-* Moving directories::          Moving and renaming directories
-@end menu
-
-@node Adding files
-@section Adding files to a directory
-@cindex Adding files
-
-To add a new file to a directory, follow these steps.
-
-@itemize @bullet
-@item
-You must have a working copy of the directory.
-@xref{Getting the source}.
-
-@item
-Create the new file inside your working copy of the directory.
-
-@item
-Use @samp{cvs add @var{filename}} to tell @sc{cvs} that you
-want to version control the file.  If the file contains
-binary data, specify @samp{-kb} (@pxref{Binary files}).
-
-@item
-Use @samp{cvs commit @var{filename}} to actually check
-in the file into the repository.  Other developers
-cannot see the file until you perform this step.
-@end itemize
-
-You can also use the @code{add} command to add a new
-directory.
-@c FIXCVS and/or FIXME: Adding a directory doesn't
-@c require the commit step.  This probably can be
-@c considered a CVS bug, but it is possible we should
-@c warn people since this behavior probably won't be
-@c changing right away.
-
-Unlike most other commands, the @code{add} command is
-not recursive.  You have to expcicitly name files and
-directories that you wish to add to the repository.
-However, each directory will need to be added
-separately before you will be able to add new files
-to those directories.
-
-@example
-$ mkdir -p foo/bar
-$ cp ~/myfile foo/bar/myfile
-$ cvs add foo foo/bar
-$ cvs add foo/bar/myfile
-@end example
-
-@cindex add (subcommand)
-@deffn Command {cvs add} [@code{-k} kflag] [@code{-m} message] files @dots{}
-
-Schedule @var{files} to be added to the repository.
-The files or directories specified with @code{add} must
-already exist in the current directory.  To add a whole
-new directory hierarchy to the source repository (for
-example, files received from a third-party vendor), use
-the @code{import} command instead.  @xref{import}.
-
-The added files are not placed in the source repository
-until you use @code{commit} to make the change
-permanent.  Doing an @code{add} on a file that was
-removed with the @code{remove} command will undo the
-effect of the @code{remove}, unless a @code{commit}
-command intervened.  @xref{Removing files}, for an
-example.
-
-The @samp{-k} option specifies the default way that
-this file will be checked out; for more information see
-@ref{Substitution modes}.
-
-@c As noted in BUGS, -m is broken client/server (Nov
-@c 96).  Also see testsuite log2-* tests.
-The @samp{-m} option specifies a description for the
-file.  This description appears in the history log (if
-it is enabled, @pxref{history file}).  It will also be
-saved in the version history inside the repository when
-the file is committed.  The @code{log} command displays
-this description.  The description can be changed using
-@samp{admin -t}.  @xref{admin}.  If you omit the
-@samp{-m @var{description}} flag, an empty string will
-be used.  You will not be prompted for a description.
-@end deffn
-
-For example, the following commands add the file
-@file{backend.c} to the repository:
-
-@c This example used to specify
-@c     -m "Optimizer and code generation passes."
-@c to the cvs add command, but that doesn't work
-@c client/server (see log2 in sanity.sh).  Should fix CVS,
-@c but also seems strange to document things which
-@c don't work...
-@example
-$ cvs add backend.c
-$ cvs commit -m "Early version. Not yet compilable." backend.c
-@end example
-
-When you add a file it is added only on the branch
-which you are working on (@pxref{Branching and merging}).  You can
-later merge the additions to another branch if you want
-(@pxref{Merging adds and removals}).
-@c Should we mention that earlier versions of CVS
-@c lacked this feature (1.3) or implemented it in a buggy
-@c way (well, 1.8 had many bugs in cvs update -j)?
-@c Should we mention the bug/limitation regarding a
-@c file being a regular file on one branch and a directory
-@c on another?
-@c FIXME: This needs an example, or several, here or
-@c elsewhere, for it to make much sense.
-@c Somewhere we need to discuss the aspects of death
-@c support which don't involve branching, I guess.
-@c Like the ability to re-create a release from a tag.
-
-@c ---------------------------------------------------------------------
-@node Removing files
-@section Removing files
-@cindex Removing files
-@cindex Deleting files
-
-@c FIXME: this node wants to be split into several
-@c smaller nodes.  Could make these children of
-@c "Adding and removing", probably (death support could
-@c be its own section, for example, as could the
-@c various bits about undoing mistakes in adding and
-@c removing).
-Directories change.  New files are added, and old files
-disappear.  Still, you want to be able to retrieve an
-exact copy of old releases.
-
-Here is what you can do to remove a file,
-but remain able to retrieve old revisions:
-
-@itemize @bullet
-@c FIXME: should probably be saying something about
-@c having a working directory in the first place.
-@item
-Make sure that you have not made any uncommitted
-modifications to the file.  @xref{Viewing differences},
-for one way to do that.  You can also use the
-@code{status} or @code{update} command.  If you remove
-the file without committing your changes, you will of
-course not be able to retrieve the file as it was
-immediately before you deleted it.
-
-@item
-Remove the file from your working copy of the directory.
-You can for instance use @code{rm}.
-
-@item
-Use @samp{cvs remove @var{filename}} to tell @sc{cvs} that
-you really want to delete the file.
-
-@item
-Use @samp{cvs commit @var{filename}} to actually
-perform the removal of the file from the repository.
-@end itemize
-
-@c FIXME: Somehow this should be linked in with a more
-@c general discussion of death support.  I don't know
-@c whether we want to use the term "death support" or
-@c not (we can perhaps get by without it), but we do
-@c need to discuss the "dead" state in "cvs log" and
-@c related subjects.  The current discussion is
-@c scattered around, and not xref'd to each other.
-@c FIXME: I think this paragraph wants to be moved
-@c later down, at least after the first example.
-When you commit the removal of the file, @sc{cvs}
-records the fact that the file no longer exists.  It is
-possible for a file to exist on only some branches and
-not on others, or to re-add another file with the same
-name later.  @sc{cvs} will correctly create or not create
-the file, based on the @samp{-r} and @samp{-D} options
-specified to @code{checkout} or @code{update}.
-
-@c FIXME: This style seems to clash with how we
-@c document things in general.
-@cindex Remove (subcommand)
-@deffn Command {cvs remove} [options] files @dots{}
-
-Schedule file(s) to be removed from the repository
-(files which have not already been removed from the
-working directory are not processed).  This command
-does not actually remove the file from the repository
-until you commit the removal.  For a full list of
-options, see @ref{Invoking CVS}.
-@end deffn
-
-Here is an example of removing several files:
-
-@example
-$ cd test
-$ rm *.c
-$ cvs remove
-cvs remove: Removing .
-cvs remove: scheduling a.c for removal
-cvs remove: scheduling b.c for removal
-cvs remove: use 'cvs commit' to remove these files permanently
-$ cvs ci -m "Removed unneeded files"
-cvs commit: Examining .
-cvs commit: Committing .
-@end example
-
-As a convenience you can remove the file and @code{cvs
-remove} it in one step, by specifying the @samp{-f}
-option.  For example, the above example could also be
-done like this:
-
-@example
-$ cd test
-$ cvs remove -f *.c
-cvs remove: scheduling a.c for removal
-cvs remove: scheduling b.c for removal
-cvs remove: use 'cvs commit' to remove these files permanently
-$ cvs ci -m "Removed unneeded files"
-cvs commit: Examining .
-cvs commit: Committing .
-@end example
-
-If you execute @code{remove} for a file, and then
-change your mind before you commit, you can undo the
-@code{remove} with an @code{add} command.
-@ignore
-@c is this worth saying or not?  Somehow it seems
-@c confusing to me.
-Of course,
-since you have removed your copy of file in the working
-directory, @sc{cvs} does not necessarily bring back the
-contents of the file from right before you executed
-@code{remove}; instead it gets the file from the
-repository again.
-@end ignore
-
-@c FIXME: what if you change your mind after you commit
-@c it?  (answer is also "cvs add" but we don't say that...).
-@c We need some index entries for thinks like "undoing
-@c removal" too.
-
-@example
-$ ls
-CVS   ja.h  oj.c
-$ rm oj.c
-$ cvs remove oj.c
-cvs remove: scheduling oj.c for removal
-cvs remove: use 'cvs commit' to remove this file permanently
-$ cvs add oj.c
-U oj.c
-cvs add: oj.c, version 1.1.1.1, resurrected
-@end example
-
-If you realize your mistake before you run the
-@code{remove} command you can use @code{update} to
-resurrect the file:
-
-@example
-$ rm oj.c
-$ cvs update oj.c
-cvs update: warning: oj.c was lost
-U oj.c
-@end example
-
-When you remove a file it is removed only on the branch
-which you are working on (@pxref{Branching and merging}).  You can
-later merge the removals to another branch if you want
-(@pxref{Merging adds and removals}).
-
-@node Removing directories
-@section Removing directories
-@cindex Removing directories
-@cindex Directories, removing
-
-In concept, removing directories is somewhat similar to
-removing files---you want the directory to not exist in
-your current working directories, but you also want to
-be able to retrieve old releases in which the directory
-existed.
-
-The way that you remove a directory is to remove all
-the files in it.  You don't remove the directory
-itself; there is no way to do that.
-Instead you specify the @samp{-P} option to
-@code{cvs update} or @code{cvs checkout},
-which will cause @sc{cvs} to remove empty
-directories from working directories.
-(Note that @code{cvs export} always removes empty directories.)
-Probably the
-best way to do this is to always specify @samp{-P}; if
-you want an empty directory then put a dummy file (for
-example @file{.keepme}) in it to prevent @samp{-P} from
-removing it.
-
-@c I'd try to give a rationale for this, but I'm not
-@c sure there is a particularly convincing one.  What
-@c we would _like_ is for CVS to do a better job of version
-@c controlling whether directories exist, to eliminate the
-@c need for -P and so that a file can be a directory in
-@c one revision and a regular file in another.
-Note that @samp{-P} is implied by the @samp{-r} or @samp{-D}
-options of @code{checkout}.  This way,
-@sc{cvs} will be able to correctly create the directory
-or not depending on whether the particular version you
-are checking out contains any files in that directory.
-
-@c ---------------------------------------------------------------------
-@node Moving files
-@section Moving and renaming files
-@cindex Moving files
-@cindex Renaming files
-@cindex Files, moving
-
-Moving files to a different directory or renaming them
-is not difficult, but some of the ways in which this
-works may be non-obvious.  (Moving or renaming a
-directory is even harder.  @xref{Moving directories}.).
-
-The examples below assume that the file @var{old} is renamed to
-@var{new}.
-
-@menu
-* Outside::                     The normal way to Rename
-* Inside::                      A tricky, alternative way
-* Rename by copying::           Another tricky, alternative way
-@end menu
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Outside
-@subsection The Normal way to Rename
-
-@c More rename issues.  Not sure whether these are
-@c worth documenting; I'm putting them here because
-@c it seems to be as good a place as any to try to
-@c set down the issues.
-@c * "cvs annotate" will annotate either the new
-@c file or the old file; it cannot annotate _each
-@c line_ based on whether it was last changed in the
-@c new or old file.  Unlike "cvs log", where the
-@c consequences of having to select either the new
-@c or old name seem fairly benign, this may be a
-@c real advantage to having CVS know about renames
-@c other than as a deletion and an addition.
-
-The normal way to move a file is to copy @var{old} to
-@var{new}, and then issue the normal @sc{cvs} commands
-to remove @var{old} from the repository, and add
-@var{new} to it.
-@c The following sentence is not true: one must cd into
-@c the directory to run "cvs add".
-@c  (Both @var{old} and @var{new} could
-@c contain relative paths, for example @file{foo/bar.c}).
-
-@example
-$ mv @var{old} @var{new}
-$ cvs remove @var{old}
-$ cvs add @var{new}
-$ cvs commit -m "Renamed @var{old} to @var{new}" @var{old} @var{new}
-@end example
-
-This is the simplest way to move a file, it is not
-error-prone, and it preserves the history of what was
-done.  Note that to access the history of the file you
-must specify the old or the new name, depending on what
-portion of the history you are accessing.  For example,
-@code{cvs log @var{old}} will give the log up until the
-time of the rename.
-
-When @var{new} is committed its revision numbers will
-start again, usually at 1.1, so if that bothers you,
-use the @samp{-r @var{tag}} option to commit.  For more
-information see @ref{Assigning revisions}.
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Inside
-@subsection Moving the history file
-
-This method is more dangerous, since it involves moving
-files inside the repository.  Read this entire section
-before trying it out!
-
-@example
-$ cd $CVSROOT/@var{dir}
-$ mv @var{old},v @var{new},v
-@end example
-
-@noindent
-Advantages:
-
-@itemize @bullet
-@item
-The log of changes is maintained intact.
-
-@item
-The revision numbers are not affected.
-@end itemize
-
-@noindent
-Disadvantages:
-
-@itemize @bullet
-@item
-Old releases cannot easily be fetched from the
-repository.  (The file will show up as @var{new} even
-in revisions from the time before it was renamed).
-
-@item
-There is no log information of when the file was renamed.
-
-@item
-Nasty things might happen if someone accesses the history file
-while you are moving it.  Make sure no one else runs any of the @sc{cvs}
-commands while you move it.
-@end itemize
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Rename by copying
-@subsection Copying the history file
-
-This way also involves direct modifications to the
-repository.  It is safe, but not without drawbacks.
-
-@example
-# @r{Copy the @sc{rcs} file inside the repository}
-$ cd $CVSROOT/@var{dir}
-$ cp @var{old},v @var{new},v
-# @r{Remove the old file}
-$ cd ~/@var{dir}
-$ rm @var{old}
-$ cvs remove @var{old}
-$ cvs commit @var{old}
-# @r{Remove all tags from @var{new}}
-$ cvs update @var{new}
-$ cvs log @var{new}             # @r{Remember the non-branch tag names}
-$ cvs tag -d @var{tag1} @var{new}
-$ cvs tag -d @var{tag2} @var{new}
-@dots{}
-@end example
-
-By removing the tags you will be able to check out old
-revisions.
-
-@noindent
-Advantages:
-
-@itemize @bullet
-@item
-@c FIXME: Is this true about -D now that we have death
-@c support?  See 5B.3 in the FAQ.
-Checking out old revisions works correctly, as long as
-you use @samp{-r @var{tag}} and not @samp{-D @var{date}}
-to retrieve the revisions.
-
-@item
-The log of changes is maintained intact.
-
-@item
-The revision numbers are not affected.
-@end itemize
-
-@noindent
-Disadvantages:
-
-@itemize @bullet
-@item
-You cannot easily see the history of the file across the rename.
-
-@ignore
-@c Is this true?  I don't see how the revision numbers
-@c _could_ start over, when new,v is just old,v with
-@c the tags deleted.
-@c If there is some need to reinstate this text,
-@c it is "usually 1.1", not "1.0" and it needs an
-@c xref to Assigning revisions
-@item
-Unless you use the @samp{-r @var{tag}} (@pxref{commit
-options}) flag when @var{new} is committed its revision
-numbers will start at 1.0 again.
-@end ignore
-@end itemize
-
-@c ---------------------------------------------------------------------
-@node Moving directories
-@section Moving and renaming directories
-@cindex Moving directories
-@cindex Renaming directories
-@cindex Directories, moving
-
-The normal way to rename or move a directory is to
-rename or move each file within it as described in
-@ref{Outside}.  Then check out with the @samp{-P}
-option, as described in @ref{Removing directories}.
-
-If you really want to hack the repository to rename or
-delete a directory in the repository, you can do it
-like this:
-
-@enumerate
-@item
-Inform everyone who has a checked out copy of the directory that the
-directory will be renamed.  They should commit all their changes in all their
-copies of the project containing the directory to be removed, and remove
-all their working copies of said project, before you take the steps below.
-
-@item
-Rename the directory inside the repository.
-
-@example
-$ cd $CVSROOT/@var{parent-dir}
-$ mv @var{old-dir} @var{new-dir}
-@end example
-
-@item
-Fix the @sc{cvs} administrative files, if necessary (for
-instance if you renamed an entire module).
-
-@item
-Tell everyone that they can check out again and continue
-working.
-
-@end enumerate
-
-If someone had a working copy the @sc{cvs} commands will
-cease to work for him, until he removes the directory
-that disappeared inside the repository.
-
-It is almost always better to move the files in the
-directory instead of moving the directory.  If you move the
-directory you are unlikely to be able to retrieve old
-releases correctly, since they probably depend on the
-name of the directories.
-
-@c ---------------------------------------------------------------------
-@node History browsing
-@chapter History browsing
-@cindex History browsing
-@cindex Traceability
-@cindex Isolation
-
-@ignore
-@c This is too long for an introduction (goal is
-@c one 20x80 character screen), and also mixes up a
-@c variety of issues (parallel development, history,
-@c maybe even touches on process control).
-
-@c -- @quote{To lose ones history is to lose ones soul.}
-@c -- ///
-@c -- ///Those who cannot remember the past are condemned to repeat it.
-@c -- ///               -- George Santayana
-@c -- ///
-
-@sc{cvs} tries to make it easy for a group of people to work
-together.  This is done in two ways:
-
-@itemize @bullet
-@item
-Isolation---You have your own working copy of the
-source.  You are not affected by modifications made by
-others until you decide to incorporate those changes
-(via the @code{update} command---@pxref{update}).
-
-@item
-Traceability---When something has changed, you can
-always see @emph{exactly} what changed.
-@end itemize
-
-There are several features of @sc{cvs} that together lead
-to traceability:
-
-@itemize @bullet
-@item
-Each revision of a file has an accompanying log
-message.
-
-@item
-All commits are optionally logged to a central history
-database.
-
-@item
-Logging information can be sent to a user-defined
-program (@pxref{loginfo}).
-@end itemize
-
-@c -- More text here.
-
-This chapter should talk about the history file, the
-@code{log} command, the usefulness of ChangeLogs
-even when you run @sc{cvs}, and things like that.
-
-@end ignore
-
-@c kind of lame, in a lot of ways the above text inside
-@c the @ignore motivates this chapter better
-Once you have used @sc{cvs} to store a version control
-history---what files have changed when, how, and by
-whom, there are a variety of mechanisms for looking
-through the history.
-
-@c FIXME: should also be talking about how you look at
-@c old revisions (e.g. "cvs update -p -r 1.2 foo.c").
-@menu
-* log messages::                Log messages
-* history database::            The history database
-* user-defined logging::        User-defined logging
-@end menu
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node log messages
-@section Log messages
-
-@c FIXME: @xref to place where we talk about how to
-@c specify message to commit.
-Whenever you commit a file you specify a log message.
-
-@c FIXME: bring the information here, and get rid of or
-@c greatly shrink the "log" node.
-To look through the log messages which have been
-specified for every revision which has been committed,
-use the @code{cvs log} command (@pxref{log}).
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node history database
-@section The history database
-
-@c FIXME: bring the information from the history file
-@c and history nodes here.  Rewrite it to be motivated
-@c better (start out by clearly explaining what gets
-@c logged in history, for example).
-You can use the history file (@pxref{history file}) to
-log various @sc{cvs} actions.  To retrieve the
-information from the history file, use the @code{cvs
-history} command (@pxref{history}).
-
-Note: you can control what is logged to this file by using the
-@samp{LogHistory} keyword in the @file{CVSROOT/config} file
-(@pxref{config}).
-
-@c
-@c The history database has many problems:
-@c * It is very unclear what field means what.  This
-@c could be improved greatly by better documentation,
-@c but there are still non-orthogonalities (for
-@c example, tag does not record the "repository"
-@c field but most records do).
-@c * Confusion about files, directories, and modules.
-@c Some commands record one, some record others.
-@c * File removal is not logged.  There is an 'R'
-@c record type documented, but CVS never uses it.
-@c * Tags are only logged for the "cvs rtag" command,
-@c not "cvs tag".  The fix for this is not completely
-@c clear (see above about modules vs. files).
-@c * Are there other cases of operations that are not
-@c logged?  One would hope for all changes to the
-@c repository to be logged somehow (particularly
-@c operations like tagging, "cvs admin -k", and other
-@c operations which do not record a history that one
-@c can get with "cvs log").  Operations on the working
-@c directory, like export, get, and release, are a
-@c second category also covered by the current "cvs
-@c history".
-@c * The history file does not record the options given
-@c to a command.  The most serious manifestation of
-@c this is perhaps that it doesn't record whether a command
-@c was recursive.  It is not clear to me whether one
-@c wants to log at a level very close to the command
-@c line, as a sort of way of logging each command
-@c (more or less), or whether one wants
-@c to log more at the level of what was changed (or
-@c something in between), but either way the current
-@c information has pretty big gaps.
-@c * Further details about a tag--like whether it is a
-@c branch tag or, if a non-branch tag, which branch it
-@c is on.  One can find out this information about the
-@c tag as it exists _now_, but if the tag has been
-@c moved, one doesn't know what it was like at the time
-@c the history record was written.
-@c * Whether operating on a particular tag, date, or
-@c options was implicit (sticky) or explicit.
-@c
-@c Another item, only somewhat related to the above, is a
-@c way to control what is logged in the history file.
-@c This is probably the only good way to handle
-@c different people having different ideas about
-@c information/space tradeoffs.
-@c
-@c It isn't really clear that it makes sense to try to
-@c patch up the history file format as it exists now to
-@c include all that stuff.  It might be better to
-@c design a whole new CVSROOT/nhistory file and "cvs
-@c nhistory" command, or some such, or in some other
-@c way trying to come up with a clean break from the
-@c past, which can address the above concerns.  Another
-@c open question is how/whether this relates to
-@c taginfo/loginfo/etc.
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node user-defined logging
-@section User-defined logging
-
-@c FIXME: probably should centralize this information
-@c here, at least to some extent.  Maybe by moving the
-@c loginfo, etc., nodes here and replacing
-@c the "user-defined logging" node with one node for
-@c each method.
-You can customize @sc{cvs} to log various kinds of
-actions, in whatever manner you choose.  These
-mechanisms operate by executing a script at various
-times.  The script might append a message to a file
-listing the information and the programmer who created
-it, or send mail to a group of developers, or, perhaps,
-post a message to a particular newsgroup.  To log
-commits, use the @file{loginfo} file (@pxref{loginfo}), and
-to log tagging operations, use the @file{taginfo} file
-(@pxref{taginfo}).
-
-@c FIXME: What is difference between doing it in the
-@c modules file and using loginfo/taginfo?  Why should
-@c user use one or the other?
-To log commits, checkouts, exports, and tags,
-respectively, you can also use the @samp{-i},
-@samp{-o}, @samp{-e}, and @samp{-t} options in the
-modules file.  For a more flexible way of giving
-notifications to various users, which requires less in
-the way of keeping centralized scripts up to date, use
-the @code{cvs watch add} command (@pxref{Getting
-Notified}); this command is useful even if you are not
-using @code{cvs watch on}.
-
-@c ---------------------------------------------------------------------
-@node Binary files
-@chapter Handling binary files
-@cindex Binary files
-
-The most common use for @sc{cvs} is to store text
-files.  With text files, @sc{cvs} can merge revisions,
-display the differences between revisions in a
-human-visible fashion, and other such operations.
-However, if you are willing to give up a few of these
-abilities, @sc{cvs} can store binary files.  For
-example, one might store a web site in @sc{cvs}
-including both text files and binary images.
-
-@menu
-* Binary why::     More details on issues with binary files
-* Binary howto::   How to store them
-@end menu
-
-@node Binary why
-@section The issues with binary files
-
-While the need to manage binary files may seem obvious
-if the files that you customarily work with are binary,
-putting them into version control does present some
-additional issues.
-
-One basic function of version control is to show the
-differences between two revisions.  For example, if
-someone else checked in a new version of a file, you
-may wish to look at what they changed and determine
-whether their changes are good.  For text files,
-@sc{cvs} provides this functionality via the @code{cvs
-diff} command.  For binary files, it may be possible to
-extract the two revisions and then compare them with a
-tool external to @sc{cvs} (for example, word processing
-software often has such a feature).  If there is no
-such tool, one must track changes via other mechanisms,
-such as urging people to write good log messages, and
-hoping that the changes they actually made were the
-changes that they intended to make.
-
-Another ability of a version control system is the
-ability to merge two revisions.  For @sc{cvs} this
-happens in two contexts.  The first is when users make
-changes in separate working directories
-(@pxref{Multiple developers}).  The second is when one
-merges explicitly with the @samp{update -j} command
-(@pxref{Branching and merging}).
-
-In the case of text
-files, @sc{cvs} can merge changes made independently,
-and signal a conflict if the changes conflict.  With
-binary files, the best that @sc{cvs} can do is present
-the two different copies of the file, and leave it to
-the user to resolve the conflict.  The user may choose
-one copy or the other, or may run an external merge
-tool which knows about that particular file format, if
-one exists.
-Note that having the user merge relies primarily on the
-user to not accidentally omit some changes, and thus is
-potentially error prone.
-
-If this process is thought to be undesirable, the best
-choice may be to avoid merging.  To avoid the merges
-that result from separate working directories, see the
-discussion of reserved checkouts (file locking) in
-@ref{Multiple developers}.  To avoid the merges
-resulting from branches, restrict use of branches.
-
-@node Binary howto
-@section How to store binary files
-
-There are two issues with using @sc{cvs} to store
-binary files.  The first is that @sc{cvs} by default
-converts line endings between the canonical form in
-which they are stored in the repository (linefeed
-only), and the form appropriate to the operating system
-in use on the client (for example, carriage return
-followed by line feed for Windows NT).
-
-The second is that a binary file might happen to
-contain data which looks like a keyword (@pxref{Keyword
-substitution}), so keyword expansion must be turned
-off.
-
-@c FIXME: the third is that one can't do merges with
-@c binary files.  xref to Multiple Developers and the
-@c reserved checkout issues.
-
-The @samp{-kb} option available with some @sc{cvs}
-commands insures that neither line ending conversion
-nor keyword expansion will be done.
-
-Here is an example of how you can create a new file
-using the @samp{-kb} flag:
-
-@example
-$ echo '$@splitrcskeyword{Id}$' > kotest
-$ cvs add -kb -m"A test file" kotest
-$ cvs ci -m"First checkin; contains a keyword" kotest
-@end example
-
-If a file accidentally gets added without @samp{-kb},
-one can use the @code{cvs admin} command to recover.
-For example:
-
-@example
-$ echo '$@splitrcskeyword{Id}$' > kotest
-$ cvs add -m"A test file" kotest
-$ cvs ci -m"First checkin; contains a keyword" kotest
-$ cvs admin -kb kotest
-$ cvs update -A kotest
-# @r{For non-unix systems:}
-# @r{Copy in a good copy of the file from outside CVS}
-$ cvs commit -m "make it binary" kotest
-@end example
-
-@c Trying to describe this for both unix and non-unix
-@c in the same description is very confusing.  Might
-@c want to split the two, or just ditch the unix "shortcut"
-@c (unixheads don't do much with binary files, anyway).
-@c This used to say "(Try the above example, and do a
-@c @code{cat kotest} after every command)".  But that
-@c only really makes sense for the unix case.
-When you check in the file @file{kotest} the file is
-not preserved as a binary file, because you did not
-check it in as a binary file.  The @code{cvs
-admin -kb} command sets the default keyword
-substitution method for this file, but it does not
-alter the working copy of the file that you have.  If you need to
-cope with line endings (that is, you are using
-@sc{cvs} on a non-unix system), then you need to
-check in a new copy of the file, as shown by the
-@code{cvs commit} command above.
-On unix, the @code{cvs update -A} command suffices.
-@c FIXME: should also describe what the *other users*
-@c need to do, if they have checked out copies which
-@c have been corrupted by lack of -kb.  I think maybe
-@c "cvs update -kb" or "cvs
-@c update -A" would suffice, although the user who
-@c reported this suggested removing the file, manually
-@c removing it from CVS/Entries, and then "cvs update"
-(Note that you can use @code{cvs log} to determine the default keyword
-substitution method for a file and @code{cvs status} to determine
-the keyword substitution method for a working copy.)
-
-However, in using @code{cvs admin -k} to change the
-keyword expansion, be aware that the keyword expansion
-mode is not version controlled.  This means that, for
-example, that if you have a text file in old releases,
-and a binary file with the same name in new releases,
-@sc{cvs} provides no way to check out the file in text
-or binary mode depending on what version you are
-checking out.  There is no good workaround for this
-problem.
-
-You can also set a default for whether @code{cvs add}
-and @code{cvs import} treat a file as binary based on
-its name; for example you could say that files who
-names end in @samp{.exe} are binary.  @xref{Wrappers}.
-There is currently no way to have @sc{cvs} detect
-whether a file is binary based on its contents.  The
-main difficulty with designing such a feature is that
-it is not clear how to distinguish between binary and
-non-binary files, and the rules to apply would vary
-considerably with the operating system.
-@c For example, it would be good on MS-DOS-family OSes
-@c for anything containing ^Z to be binary.  Having
-@c characters with the 8th bit set imply binary is almost
-@c surely a bad idea in the context of ISO-8859-* and
-@c other such character sets.  On VMS or the Mac, we
-@c could use the OS's file typing.  This is a
-@c commonly-desired feature, and something of this sort
-@c may make sense.  But there are a lot of pitfalls here.
-@c
-@c Another, probably better, way to tell is to read the
-@c file in text mode, write it to a temp file in text
-@c mode, and then do a binary mode compare of the two
-@c files.  If they differ, it is a binary file.  This
-@c might have problems on VMS (or some other system
-@c with several different text modes), but in general
-@c should be relatively portable.  The only other
-@c downside I can think of is that it would be fairly
-@c slow, but that is perhaps a small price to pay for
-@c not having your files corrupted.  Another issue is
-@c what happens if you import a text file with bare
-@c linefeeds on Windows.  Such files will show up on
-@c Windows sometimes (I think some native windows
-@c programs even write them, on occasion).  Perhaps it
-@c is reasonable to treat such files as binary; after
-@c all it is something of a presumption to assume that
-@c the user would want the linefeeds converted to CRLF.
-
-@c ---------------------------------------------------------------------
-@node Multiple developers
-@chapter Multiple developers
-@cindex Multiple developers
-@cindex Team of developers
-@cindex File locking
-@cindex Locking files
-@cindex Working copy
-@cindex Reserved checkouts
-@cindex Unreserved checkouts
-@cindex RCS-style locking
-
-When more than one person works on a software project
-things often get complicated.  Often, two people try to
-edit the same file simultaneously.  One solution, known
-as @dfn{file locking} or @dfn{reserved checkouts}, is
-to allow only one person to edit each file at a time.
-This is the only solution with some version control
-systems, including @sc{rcs} and @sc{sccs}.  Currently
-the usual way to get reserved checkouts with @sc{cvs}
-is the @code{cvs admin -l} command (@pxref{admin
-options}).  This is not as nicely integrated into
-@sc{cvs} as the watch features, described below, but it
-seems that most people with a need for reserved
-checkouts find it adequate.
-@c Or "find it better than worrying about implementing
-@c nicely integrated reserved checkouts" or ...?
-
-As of @sc{cvs} version 1.12.10, another technique for getting most of the
-effect of reserved checkouts is to enable advisory locks.  To enable advisory
-locks, have all developers put "edit -c", "commit -c" in their
-.cvsrc file, and turn on watches in the repository.  This
-prevents them from doing a @code{cvs edit} if anyone is
-already editting the file.  It also may
-be possible to use plain watches together with suitable
-procedures (not enforced by software), to avoid having
-two people edit at the same time.
-
-@c Our unreserved checkout model might not
-@c be quite the same as others.  For example, I
-@c think that some systems will tend to create a branch
-@c in the case where CVS prints "up-to-date check failed".
-@c It isn't clear to me whether we should try to
-@c explore these subtleties; it could easily just
-@c confuse people.
-The default model with @sc{cvs} is known as
-@dfn{unreserved checkouts}.  In this model, developers
-can edit their own @dfn{working copy} of a file
-simultaneously.  The first person that commits his
-changes has no automatic way of knowing that another
-has started to edit it.  Others will get an error
-message when they try to commit the file.  They must
-then use @sc{cvs} commands to bring their working copy
-up to date with the repository revision.  This process
-is almost automatic.
-
-@c FIXME? should probably use the word "watch" here, to
-@c tie this into the text below and above.
-@sc{cvs} also supports mechanisms which facilitate
-various kinds of communication, without actually
-enforcing rules like reserved checkouts do.
-
-The rest of this chapter describes how these various
-models work, and some of the issues involved in
-choosing between them.
-
-@ignore
-Here is a draft reserved checkout design or discussion
-of the issues.  This seems like as good a place as any
-for this.
-
-Might want a cvs lock/cvs unlock--in which the names
-differ from edit/unedit because the network must be up
-for these to work.  unedit gives an error if there is a
-reserved checkout in place (so that people don't
-accidentally leave locks around); unlock gives an error
-if one is not in place (this is more arguable; perhaps
-it should act like unedit in that case).
-
-On the other hand, might want it so that emacs,
-scripts, etc., can get ready to edit a file without
-having to know which model is in use.  In that case we
-would have a "cvs watch lock" (or .cvsrc?) (that is,
-three settings, "on", "off", and "lock").  Having cvs
-watch lock set would cause a get to record in the CVS
-directory which model is in use, and cause "cvs edit"
-to change behaviors.  We'd want a way to query which
-setting is in effect (this would be handy even if it is
-only "on" or "off" as presently).  If lock is in
-effect, then commit would require a lock before
-allowing a checkin; chmod wouldn't suffice (might be
-debatable--see chmod comment below, in watches--but it
-is the way people expect RCS to work and I can't think
-of any significant downside.  On the other hand, maybe
-it isn't worth bothering, because people who are used
-to RCS wouldn't think to use chmod anyway).
-
-Implementation: use file attributes or use RCS
-locking.  The former avoids more dependence on RCS
-behaviors we will need to re-implement as we librarify
-RCS, and makes it easier to import/export RCS files (in
-that context, want to ignore the locker field).  But
-note that RCS locks are per-branch, which is the
-correct behavior (this is also an issue for the "watch
-on" features; they should be per-branch too).
-
-Here are a few more random notes about implementation
-details, assuming "cvs watch lock" and
-
-CVS/Watched file?  Or try to fit this into CVS/Entries somehow?
-Cases: (1) file is checked out (unreserved or with watch on) by old
-version of @sc{cvs}, now we do something with new one, (2) file is checked
-out by new version, now we do something with old one.
-
-Remote protocol would have a "Watched" analogous to "Mode".  Of course
-it would apply to all Updated-like requests.  How do we keep this
-setting up to date?  I guess that there wants to be a Watched request,
-and the server would send a new one if it isn't up to date? (Ugh--hard
-to implement and slows down "cvs -q update"--is there an easier way?)
-
-"cvs edit"--checks CVS/Watched, and if watch lock, then sends
-"edit-lock" request.  Which comes back with a Checked-in with
-appropriate Watched (off, on, lock, locked, or some such?), or error
-message if already locked.
-
-"cvs commit"--only will commit if off/on/locked.  lock is not OK.
-
-Doc:
-note that "cvs edit" must be connected to network if watch lock is in
-effect.
-
-Talk about what to do if someone has locked a file and you want to
-edit that file.  (breaking locks, or lack thereof).
-
-
-One other idea (which could work along with the
-existing "cvs admin -l" reserved checkouts, as well as
-the above):
-
-"cvs editors" could show who has the file locked, if
-someone does.
-
-@end ignore
-
-@menu
-* File status::                 A file can be in several states
-* Updating a file::             Bringing a file up-to-date
-* Conflicts example::           An informative example
-* Informing others::            To cooperate you must inform
-* Concurrency::                 Simultaneous repository access
-* Watches::                     Mechanisms to track who is editing files
-* Choosing a model::            Reserved or unreserved checkouts?
-@end menu
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node File status
-@section File status
-@cindex File status
-@cindex Status of a file
-
-@c Shouldn't this start with an example or something,
-@c introducing the unreserved checkout model?  Before we
-@c dive into listing states?
-Based on what operations you have performed on a
-checked out file, and what operations others have
-performed to that file in the repository, one can
-classify a file in a number of states.  The states, as
-reported by the @code{status} command, are:
-
-@c The order of items is chosen to group logically
-@c similar outputs together.
-@c People who want alphabetical can use the index...
-@table @asis
-@cindex Up-to-date
-@item Up-to-date
-The file is identical with the latest revision in the
-repository for the branch in use.
-@c FIXME: should we clarify "in use"?  The answer is
-@c sticky tags, and trying to distinguish branch sticky
-@c tags from non-branch sticky tags seems rather awkward
-@c here.
-@c FIXME: What happens with non-branch sticky tags?  Is
-@c a stuck file "Up-to-date" or "Needs checkout" or what?
-
-@item Locally Modified
-@cindex Locally Modified
-You have edited the file, and not yet committed your changes.
-
-@item Locally Added
-@cindex Locally Added
-You have added the file with @code{add}, and not yet
-committed your changes.
-@c There are many cases involving the file being
-@c added/removed/modified in the working directory, and
-@c added/removed/modified in the repository, which we
-@c don't try to describe here.  I'm not sure that "cvs
-@c status" produces a non-confusing output in most of
-@c those cases.
-
-@item Locally Removed
-@cindex Locally Removed
-You have removed the file with @code{remove}, and not yet
-committed your changes.
-
-@item Needs Checkout
-@cindex Needs Checkout
-Someone else has committed a newer revision to the
-repository.  The name is slightly misleading; you will
-ordinarily use @code{update} rather than
-@code{checkout} to get that newer revision.
-
-@item Needs Patch
-@cindex Needs Patch
-@c See also newb-123j0 in sanity.sh (although that case
-@c should probably be changed rather than documented).
-Like Needs Checkout, but the @sc{cvs} server will send
-a patch rather than the entire file.  Sending a patch or
-sending an entire file accomplishes the same thing.
-
-@item Needs Merge
-@cindex Needs Merge
-Someone else has committed a newer revision to the repository, and you
-have also made modifications to the file.
-
-@item Unresolved Conflict
-@cindex Unresolved Conflict
-@c FIXCVS - This file status needs to be changed to some more informative
-@c text that distinguishes it more clearly from each of the Locally Added,
-@c File had conflicts on merge, and Unknown status types, but an exact and
-@c succinct wording escapes me at the moment.
-A file with the same name as this new file has been added to the repository
-from a second workspace.  This file will need to be moved out of the way
-to allow an @code{update} to complete.
-
-@item File had conflicts on merge
-@cindex File had conflicts on merge
-@c is it worth saying that this message was "Unresolved
-@c Conflict" in CVS 1.9 and earlier?  I'm inclined to
-@c think that is unnecessarily confusing to new users.
-This is like Locally Modified, except that a previous
-@code{update} command gave a conflict.  If you have not
-already done so, you need to
-resolve the conflict as described in @ref{Conflicts example}.
-
-@item Unknown
-@cindex Unknown
-@sc{cvs} doesn't know anything about this file.  For
-example, you have created a new file and have not run
-@code{add}.
-@c
-@c "Entry Invalid" and "Classify Error" are also in the
-@c status.c.  The latter definitely indicates a CVS bug
-@c (should it be worded more like "internal error" so
-@c people submit bug reports if they see it?).  The former
-@c I'm not as sure; I haven't tracked down whether/when it
-@c appears in "cvs status" output.
-
-@end table
-
-To help clarify the file status, @code{status} also
-reports the @code{Working revision} which is the
-revision that the file in the working directory derives
-from, and the @code{Repository revision} which is the
-latest revision in the repository for the branch in
-use.
-The @samp{Commit Identifier} reflects the unique commitid
-of the @code{commit}.
-@c FIXME: should we clarify "in use"?  The answer is
-@c sticky tags, and trying to distinguish branch sticky
-@c tags from non-branch sticky tags seems rather awkward
-@c here.
-@c FIXME: What happens with non-branch sticky tags?
-@c What is the Repository Revision there?  See the
-@c comment at vn_rcs in cvs.h, which is kind of
-@c confused--we really need to document better what this
-@c field contains.
-@c Q: Should we document "New file!" and other such
-@c outputs or are they self-explanatory?
-@c FIXME: what about the date to the right of "Working
-@c revision"?  It doesn't appear with client/server and
-@c seems unnecessary (redundant with "ls -l") so
-@c perhaps it should be removed for non-client/server too?
-@c FIXME: Need some examples.
-@c FIXME: Working revision can also be something like
-@c "-1.3" for a locally removed file.  Not at all
-@c self-explanatory (and it is possible that CVS should
-@c be changed rather than documenting this).
-
-@c Would be nice to have an @example showing output
-@c from cvs status, with comments showing the xref
-@c where each part of the output is described.  This
-@c might fit in nicely if it is desirable to split this
-@c node in two; one to introduce "cvs status" and one
-@c to list each of the states.
-The options to @code{status} are listed in
-@ref{Invoking CVS}.  For information on its @code{Sticky tag}
-and @code{Sticky date} output, see @ref{Sticky tags}.
-For information on its @code{Sticky options} output,
-see the @samp{-k} option in @ref{update options}.
-
-You can think of the @code{status} and @code{update}
-commands as somewhat complementary.  You use
-@code{update} to bring your files up to date, and you
-can use @code{status} to give you some idea of what an
-@code{update} would do (of course, the state of the
-repository might change before you actually run
-@code{update}).  In fact, if you want a command to
-display file status in a more brief format than is
-displayed by the @code{status} command, you can invoke
-
-@cindex update, to display file status
-@example
-$ cvs -n -q update
-@end example
-
-The @samp{-n} option means to not actually do the
-update, but merely to display statuses; the @samp{-q}
-option avoids printing the name of each directory.  For
-more information on the @code{update} command, and
-these options, see @ref{Invoking CVS}.
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Updating a file
-@section Bringing a file up to date
-@cindex Bringing a file up to date
-@cindex Updating a file
-@cindex Merging a file
-@cindex Update, introduction
-
-When you want to update or merge a file, use the @code{cvs update -d}
-command.  For files that are not up to date this is roughly equivalent
-to a @code{checkout} command: the newest revision of the file is
-extracted from the repository and put in your working directory.  The
-@code{-d} option, not necessary with @code{checkout}, tells @sc{cvs}
-that you wish it to create directories added by other developers.
-
-Your modifications to a file are never lost when you
-use @code{update}.  If no newer revision exists,
-running @code{update} has no effect.  If you have
-edited the file, and a newer revision is available,
-@sc{cvs} will merge all changes into your working copy.
-
-For instance, imagine that you checked out revision 1.4 and started
-editing it.  In the meantime someone else committed revision 1.5, and
-shortly after that revision 1.6.  If you run @code{update} on the file
-now, @sc{cvs} will incorporate all changes between revision 1.4 and 1.6 into
-your file.
-
-@cindex Overlap
-If any of the changes between 1.4 and 1.6 were made too
-close to any of the changes you have made, an
-@dfn{overlap} occurs.  In such cases a warning is
-printed, and the resulting file includes both
-versions of the lines that overlap, delimited by
-special markers.
-@xref{update}, for a complete description of the
-@code{update} command.
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Conflicts example
-@section Conflicts example
-@cindex Merge, an example
-@cindex Example of merge
-@cindex driver.c (merge example)
-
-Suppose revision 1.4 of @file{driver.c} contains this:
-
-@example
-#include <stdio.h>
-
-void main()
-@{
-    parse();
-    if (nerr == 0)
-        gencode();
-    else
-        fprintf(stderr, "No code generated.\n");
-    exit(nerr == 0 ? 0 : 1);
-@}
-@end example
-
-@noindent
-Revision 1.6 of @file{driver.c} contains this:
-
-@example
-#include <stdio.h>
-
-int main(int argc,
-         char **argv)
-@{
-    parse();
-    if (argc != 1)
-    @{
-        fprintf(stderr, "tc: No args expected.\n");
-        exit(1);
-    @}
-    if (nerr == 0)
-        gencode();
-    else
-        fprintf(stderr, "No code generated.\n");
-    exit(!!nerr);
-@}
-@end example
-
-@noindent
-Your working copy of @file{driver.c}, based on revision
-1.4, contains this before you run @samp{cvs update}:
-@c -- Really include "cvs"?
-
-@example
-#include <stdlib.h>
-#include <stdio.h>
-
-void main()
-@{
-    init_scanner();
-    parse();
-    if (nerr == 0)
-        gencode();
-    else
-        fprintf(stderr, "No code generated.\n");
-    exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
-@}
-@end example
-
-@noindent
-You run @samp{cvs update}:
-@c -- Really include "cvs"?
-
-@example
-$ cvs update driver.c
-RCS file: /usr/local/cvsroot/yoyodyne/tc/driver.c,v
-retrieving revision 1.4
-retrieving revision 1.6
-Merging differences between 1.4 and 1.6 into driver.c
-rcsmerge warning: overlaps during merge
-cvs update: conflicts found in driver.c
-C driver.c
-@end example
-
-@noindent
-@cindex Conflicts (merge example)
-@sc{cvs} tells you that there were some conflicts.
-Your original working file is saved unmodified in
-@file{.#driver.c.1.4}.  The new version of
-@file{driver.c} contains this:
-
-@example
-#include <stdlib.h>
-#include <stdio.h>
-
-int main(int argc,
-         char **argv)
-@{
-    init_scanner();
-    parse();
-    if (argc != 1)
-    @{
-        fprintf(stderr, "tc: No args expected.\n");
-        exit(1);
-    @}
-    if (nerr == 0)
-        gencode();
-    else
-        fprintf(stderr, "No code generated.\n");
-@asis{}<<<<<<< driver.c
-    exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
-@asis{}=======
-    exit(!!nerr);
-@asis{}>>>>>>> 1.6
-@}
-@end example
-
-@noindent
-@cindex Markers, conflict
-@cindex Conflict markers
-@cindex <<<<<<<
-@cindex >>>>>>>
-@cindex =======
-
-Note how all non-overlapping modifications are incorporated in your working
-copy, and that the overlapping section is clearly marked with
-@samp{<<<<<<<}, @samp{=======} and @samp{>>>>>>>}.
-
-@cindex Resolving a conflict
-@cindex Conflict resolution
-You resolve the conflict by editing the file, removing the markers and
-the erroneous line.  Suppose you end up with this file:
-@c -- Add xref to the pcl-cvs manual when it talks
-@c -- about this.
-@example
-#include <stdlib.h>
-#include <stdio.h>
-
-int main(int argc,
-         char **argv)
-@{
-    init_scanner();
-    parse();
-    if (argc != 1)
-    @{
-        fprintf(stderr, "tc: No args expected.\n");
-        exit(1);
-    @}
-    if (nerr == 0)
-        gencode();
-    else
-        fprintf(stderr, "No code generated.\n");
-    exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
-@}
-@end example
-
-@noindent
-You can now go ahead and commit this as revision 1.7.
-
-@example
-$ cvs commit -m "Initialize scanner. Use symbolic exit values." driver.c
-Checking in driver.c;
-/usr/local/cvsroot/yoyodyne/tc/driver.c,v  <--  driver.c
-new revision: 1.7; previous revision: 1.6
-done
-@end example
-
-For your protection, @sc{cvs} will refuse to check in a
-file if a conflict occurred and you have not resolved
-the conflict.  Currently to resolve a conflict, you
-must change the timestamp on the file.  In previous
-versions of @sc{cvs}, you also needed to
-insure that the file contains no conflict markers.
-Because
-your file may legitimately contain conflict markers (that
-is, occurrences of @samp{>>>>>>> } at the start of a
-line that don't mark a conflict), the current
-version of @sc{cvs} will print a warning and proceed to
-check in the file.
-@c The old behavior was really icky; the only way out
-@c was to start hacking on
-@c the @code{CVS/Entries} file or other such workarounds.
-@c
-@c If the timestamp thing isn't considered nice enough,
-@c maybe there should be a "cvs resolved" command
-@c which clears the conflict indication.  For a nice user
-@c interface, this should be invoked by an interactive
-@c merge tool like emerge rather than by the user
-@c directly--such a tool can verify that the user has
-@c really dealt with each conflict.
-
-@cindex emerge
-If you use release 1.04 or later of pcl-cvs (a @sc{gnu}
-Emacs front-end for @sc{cvs}) you can use an Emacs
-package called emerge to help you resolve conflicts.
-See the documentation for pcl-cvs.
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Informing others
-@section Informing others about commits
-@cindex Informing others
-@cindex Spreading information
-@cindex Mail, automatic mail on commit
-
-It is often useful to inform others when you commit a
-new revision of a file.  The @samp{-i} option of the
-@file{modules} file, or the @file{loginfo} file, can be
-used to automate this process.  @xref{modules}.
-@xref{loginfo}.  You can use these features of @sc{cvs}
-to, for instance, instruct @sc{cvs} to mail a
-message to all developers, or post a message to a local
-newsgroup.
-@c -- More text would be nice here.
-
-@node Concurrency
-@section Several developers simultaneously attempting to run CVS
-
-@cindex Locks, cvs, introduction
-@c For a discussion of *why* CVS creates locks, see
-@c the comment at the start of src/lock.c
-If several developers try to run @sc{cvs} at the same
-time, one may get the following message:
-
-@example
-[11:43:23] waiting for bach's lock in /usr/local/cvsroot/foo
-@end example
-
-@cindex #cvs.rfl, removing
-@cindex #cvs.wfl, removing
-@cindex #cvs.lock, removing
-@sc{cvs} will try again every 30 seconds, and either
-continue with the operation or print the message again,
-if it still needs to wait.  If a lock seems to stick
-around for an undue amount of time, find the person
-holding the lock and ask them about the cvs command
-they are running.  If they aren't running a cvs
-command, look in the repository directory mentioned in
-the message and remove files which they own whose names
-start with @file{#cvs.rfl},
-@file{#cvs.wfl}, or @file{#cvs.lock}.
-
-Note that these locks are to protect @sc{cvs}'s
-internal data structures and have no relationship to
-the word @dfn{lock} in the sense used by
-@sc{rcs}---which refers to reserved checkouts
-(@pxref{Multiple developers}).
-
-Any number of people can be reading from a given
-repository at a time; only when someone is writing do
-the locks prevent other people from reading or writing.
-
-@cindex Atomic transactions, lack of
-@cindex Transactions, atomic, lack of
-@c the following talks about what one might call commit/update
-@c atomicity.
-@c Probably also should say something about
-@c commit/commit atomicity, that is, "An update will
-@c not get partial versions of more than one commit".
-@c CVS currently has this property and I guess we can
-@c make it a documented feature.
-@c For example one person commits
-@c a/one.c and b/four.c and another commits a/two.c and
-@c b/three.c.  Then an update cannot get the new a/one.c
-@c and a/two.c and the old b/four.c and b/three.c.
-One might hope for the following property:
-
-@quotation
-If someone commits some changes in one cvs command,
-then an update by someone else will either get all the
-changes, or none of them.
-@end quotation
-
-@noindent
-but @sc{cvs} does @emph{not} have this property.  For
-example, given the files
-
-@example
-a/one.c
-a/two.c
-b/three.c
-b/four.c
-@end example
-
-@noindent
-if someone runs
-
-@example
-cvs ci a/two.c b/three.c
-@end example
-
-@noindent
-and someone else runs @code{cvs update} at the same
-time, the person running @code{update} might get only
-the change to @file{b/three.c} and not the change to
-@file{a/two.c}.
-
-@node Watches
-@section Mechanisms to track who is editing files
-@cindex Watches
-
-For many groups, use of @sc{cvs} in its default mode is
-perfectly satisfactory.  Users may sometimes go to
-check in a modification only to find that another
-modification has intervened, but they deal with it and
-proceed with their check in.  Other groups prefer to be
-able to know who is editing what files, so that if two
-people try to edit the same file they can choose to
-talk about who is doing what when rather than be
-surprised at check in time.  The features in this
-section allow such coordination, while retaining the
-ability of two developers to edit the same file at the
-same time.
-
-@c Some people might ask why CVS does not enforce the
-@c rule on chmod, by requiring a cvs edit before a cvs
-@c commit.  The main reason is that it could always be
-@c circumvented--one could edit the file, and
-@c then when ready to check it in, do the cvs edit and put
-@c in the new contents and do the cvs commit.  One
-@c implementation note: if we _do_ want to have cvs commit
-@c require a cvs edit, we should store the state on
-@c whether the cvs edit has occurred in the working
-@c directory, rather than having the server try to keep
-@c track of what working directories exist.
-@c FIXME: should the above discussion be part of the
-@c manual proper, somewhere, not just in a comment?
-For maximum benefit developers should use @code{cvs
-edit} (not @code{chmod}) to make files read-write to
-edit them, and @code{cvs release} (not @code{rm}) to
-discard a working directory which is no longer in use,
-but @sc{cvs} is not able to enforce this behavior.
-
-If a development team wants stronger enforcement of
-watches and all team members are using a @sc{cvs} client version 1.12.10 or
-greater to access a @sc{cvs} server version 1.12.10 or greater, they can
-enable advisory locks.  To enable advisory locks, have all developers
-put "edit -c" and "commit -c" into all .cvsrc files,
-and make files default to read only by turning on watches
-or putting "cvs -r" into all .cvsrc files.
-This prevents multiple people from editting a file at
-the same time (unless explicitly overriden with @samp{-f}).
-
-@c I'm a little dissatisfied with this presentation,
-@c because "watch on"/"edit"/"editors" are one set of
-@c functionality, and "watch add"/"watchers" is another
-@c which is somewhat orthogonal even though they interact in
-@c various ways.  But I think it might be
-@c confusing to describe them separately (e.g. "watch
-@c add" with loginfo).  I don't know.
-
-@menu
-* Setting a watch::             Telling CVS to watch certain files
-* Getting Notified::            Telling CVS to notify you
-* Editing files::               How to edit a file which is being watched
-* Watch information::           Information about who is watching and editing
-* Watches Compatibility::       Watches interact poorly with CVS 1.6 or earlier
-@end menu
-
-@node Setting a watch
-@subsection Telling CVS to watch certain files
-
-To enable the watch features, you first specify that
-certain files are to be watched.
-
-@cindex watch on (subcommand)
-@deffn Command {cvs watch on} [@code{-lR}] [@var{files}]@dots{}
-
-@cindex Read-only files, and watches
-Specify that developers should run @code{cvs edit}
-before editing @var{files}.  @sc{cvs} will create working
-copies of @var{files} read-only, to remind developers
-to run the @code{cvs edit} command before working on
-them.
-
-If @var{files} includes the name of a directory, @sc{cvs}
-arranges to watch all files added to the corresponding
-repository directory, and sets a default for files
-added in the future; this allows the user to set
-notification policies on a per-directory basis.  The
-contents of the directory are processed recursively,
-unless the @code{-l} option is given.
-The @code{-R} option can be used to force recursion if the @code{-l}
-option is set in @file{~/.cvsrc} (@pxref{~/.cvsrc}).
-
-If @var{files} is omitted, it defaults to the current directory.
-
-@cindex watch off (subcommand)
-@end deffn
-
-@deffn Command {cvs watch off} [@code{-lR}] [@var{files}]@dots{}
-
-Do not create @var{files} read-only on checkout; thus,
-developers will not be reminded to use @code{cvs edit}
-and @code{cvs unedit}.
-@ignore
-@sc{cvs} will check out @var{files}
-read-write as usual, unless other permissions override
-due to the @code{PreservePermissions} option being
-enabled in the @file{config} administrative file
-(@pxref{Special Files}, @pxref{config})
-@end ignore
-
-The @var{files} and options are processed as for @code{cvs
-watch on}.
-
-@end deffn
-
-@node Getting Notified
-@subsection Telling CVS to notify you
-
-You can tell @sc{cvs} that you want to receive
-notifications about various actions taken on a file.
-You can do this without using @code{cvs watch on} for
-the file, but generally you will want to use @code{cvs
-watch on}, to remind developers to use the @code{cvs edit}
-command.
-
-@cindex watch add (subcommand)
-@deffn Command {cvs watch add} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{}
-
-Add the current user to the list of people to receive notification of
-work done on @var{files}.
-
-The @code{-a} option specifies what kinds of events @sc{cvs} should notify
-the user about.  @var{action} is one of the following:
-
-@table @code
-
-@item edit
-Another user has applied the @code{cvs edit} command (described
-below) to a watched file.
-
-@item commit
-Another user has committed changes to one of the named @var{files}.
-
-@item unedit
-Another user has abandoned editing a file (other than by committing changes).
-They can do this in several ways, by:
-
-@itemize @bullet
-
-@item
-applying the @code{cvs unedit} command (described below) to the file
-
-@item
-applying the @code{cvs release} command (@pxref{release}) to the file's parent directory
-(or recursively to a directory more than one level up)
-
-@item
-deleting the file and allowing @code{cvs update} to recreate it
-
-@end itemize
-
-@item all
-All of the above.
-
-@item none
-None of the above.  (This is useful with @code{cvs edit},
-described below.)
-
-@end table
-
-The @code{-a} option may appear more than once, or not at all.  If
-omitted, the action defaults to @code{all}.
-
-The @var{files} and options are processed as for
-@code{cvs watch on}.
-
-@end deffn
-
-
-@cindex watch remove (subcommand)
-@deffn Command {cvs watch remove} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{}
-
-Remove a notification request established using @code{cvs watch add};
-the arguments are the same.  If the @code{-a} option is present, only
-watches for the specified actions are removed.
-
-@end deffn
-
-@cindex notify (admin file)
-When the conditions exist for notification, @sc{cvs}
-calls the @file{notify} administrative file.  Edit
-@file{notify} as one edits the other administrative
-files (@pxref{Intro administrative files}).  This
-file follows the usual conventions for administrative
-files (@pxref{syntax}), where each line is a regular
-expression followed by a command to execute.  The
-command should contain a single occurrence of @samp{%s}
-which will be replaced by the user to notify; the rest
-of the information regarding the notification will be
-supplied to the command on standard input.  The
-standard thing to put in the @code{notify} file is the
-single line:
-
-@example
-ALL mail %s -s "CVS notification"
-@end example
-
-@noindent
-This causes users to be notified by electronic mail.
-@c FIXME: should it be this hard to set up this
-@c behavior (and the result when one fails to do so,
-@c silent failure to notify, so non-obvious)?  Should
-@c CVS give a warning if no line in notify matches (and
-@c document the use of "DEFAULT :" for the case where
-@c skipping the notification is indeed desired)?
-
-@cindex users (admin file)
-Note that if you set this up in the straightforward
-way, users receive notifications on the server machine.
-One could of course write a @file{notify} script which
-directed notifications elsewhere, but to make this
-easy, @sc{cvs} allows you to associate a notification
-address for each user.  To do so create a file
-@file{users} in @file{CVSROOT} with a line for each
-user in the format @var{user}:@var{value}.  Then
-instead of passing the name of the user to be notified
-to @file{notify}, @sc{cvs} will pass the @var{value}
-(normally an email address on some other machine).
-
-@sc{cvs} does not notify you for your own changes.
-Currently this check is done based on whether the user
-name of the person taking the action which triggers
-notification matches the user name of the person
-getting notification.  In fact, in general, the watches
-features only track one edit by each user.  It probably
-would be more useful if watches tracked each working
-directory separately, so this behavior might be worth
-changing.
-@c "behavior might be worth changing" is an effort to
-@c point to future directions while also not promising
-@c that "they" (as in "why don't they fix CVS to....")
-@c will do this.
-@c one implementation issue is identifying whether a
-@c working directory is same or different.  Comparing
-@c pathnames/hostnames is hopeless, but having the server
-@c supply a serial number which the client stores in the
-@c CVS directory as a magic cookie should work.
-
-@node Editing files
-@subsection How to edit a file which is being watched
-
-@cindex Checkout, as term for getting ready to edit
-Since a file which is being watched is checked out
-read-only, you cannot simply edit it.  To make it
-read-write, and inform others that you are planning to
-edit it, use the @code{cvs edit} command.  Some systems
-call this a @dfn{checkout}, but @sc{cvs} uses that term
-for obtaining a copy of the sources (@pxref{Getting the
-source}), an operation which those systems call a
-@dfn{get} or a @dfn{fetch}.
-@c Issue to think about: should we transition CVS
-@c towards the "get" terminology?  "cvs get" is already a
-@c synonym for "cvs checkout" and that section of the
-@c manual refers to "Getting the source".  If this is
-@c done, needs to be done gingerly (for example, we should
-@c still accept "checkout" in .cvsrc files indefinitely
-@c even if the CVS's messages are changed from "cvs checkout: "
-@c to "cvs get: ").
-@c There is a concern about whether "get" is not as
-@c good for novices because it is a more general term
-@c than "checkout" (and thus arguably harder to assign
-@c a technical meaning for).
-
-@cindex edit (subcommand)
-@deffn Command {cvs edit} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{}
-
-Prepare to edit the working files @var{files}.  @sc{cvs} makes the
-@var{files} read-write, and notifies users who have requested
-@code{edit} notification for any of @var{files}.
-
-The @code{cvs edit} command accepts the same options as the
-@code{cvs watch add} command, and establishes a temporary watch for the
-user on @var{files}; @sc{cvs} will remove the watch when @var{files} are
-@code{unedit}ed or @code{commit}ted.  If the user does not wish to
-receive notifications, she should specify @code{-a none}.
-
-The @var{files} and the options are processed as for the @code{cvs
-watch} commands.
-
-There are two additional options that @code{cvs edit} understands as of
-@sc{cvs} client and server versions 1.12.10 but @code{cvs watch} does not.
-The first is @code{-c}, which causes @code{cvs edit} to fail if anyone else
-is editting the file.  This is probably only useful when @samp{edit -c} and
-@samp{commit -c} are specified in all developers' @file{.cvsrc} files.  This
-behavior may be overriden this via the @code{-f} option, which overrides
-@code{-c} and allows multiple edits to succeed.
-
-@ignore
-@strong{Caution: If the @code{PreservePermissions}
-option is enabled in the repository (@pxref{config}),
-@sc{cvs} will not change the permissions on any of the
-@var{files}.  The reason for this change is to ensure
-that using @samp{cvs edit} does not interfere with the
-ability to store file permissions in the @sc{cvs}
-repository.}
-@end ignore
-
-@end deffn
-
-Normally when you are done with a set of changes, you
-use the @code{cvs commit} command, which checks in your
-changes and returns the watched files to their usual
-read-only state.  But if you instead decide to abandon
-your changes, or not to make any changes, you can use
-the @code{cvs unedit} command.
-
-@cindex unedit (subcommand)
-@cindex Abandoning work
-@cindex Reverting to repository version
-@deffn Command {cvs unedit} [@code{-lR}] [@var{files}]@dots{}
-
-Abandon work on the working files @var{files}, and revert them to the
-repository versions on which they are based.  @sc{cvs} makes those
-@var{files} read-only for which users have requested notification using
-@code{cvs watch on}.  @sc{cvs} notifies users who have requested @code{unedit}
-notification for any of @var{files}.
-
-The @var{files} and options are processed as for the
-@code{cvs watch} commands.
-
-If watches are not in use, the @code{unedit} command
-probably does not work, and the way to revert to the
-repository version is with the command @code{cvs update -C file}
-(@pxref{update}).
-The meaning is
-not precisely the same; the latter may also
-bring in some changes which have been made in the
-repository since the last time you updated.
-@c It would be a useful enhancement to CVS to make
-@c unedit work in the non-watch case as well.
-@end deffn
-
-When using client/server @sc{cvs}, you can use the
-@code{cvs edit} and @code{cvs unedit} commands even if
-@sc{cvs} is unable to successfully communicate with the
-server; the notifications will be sent upon the next
-successful @sc{cvs} command.
-
-@node Watch information
-@subsection Information about who is watching and editing
-
-@cindex watchers (subcommand)
-@deffn Command {cvs watchers} [@code{-lR}] [@var{files}]@dots{}
-
-List the users currently watching changes to @var{files}.  The report
-includes the files being watched, and the mail address of each watcher.
-
-The @var{files} and options are processed as for the
-@code{cvs watch} commands.
-
-@end deffn
-
-
-@cindex editors (subcommand)
-@deffn Command {cvs editors} [@code{-lR}] [@var{files}]@dots{}
-
-List the users currently working on @var{files}.  The report
-includes the mail address of each user, the time when the user began
-working with the file, and the host and path of the working directory
-containing the file.
-
-The @var{files} and options are processed as for the
-@code{cvs watch} commands.
-
-@end deffn
-
-@node Watches Compatibility
-@subsection Using watches with old versions of CVS
-
-@cindex CVS 1.6, and watches
-If you use the watch features on a repository, it
-creates @file{CVS} directories in the repository and
-stores the information about watches in that directory.
-If you attempt to use @sc{cvs} 1.6 or earlier with the
-repository, you get an error message such as the
-following (all on one line):
-
-@example
-cvs update: cannot open CVS/Entries for reading:
-No such file or directory
-@end example
-
-@noindent
-and your operation will likely be aborted.  To use the
-watch features, you must upgrade all copies of @sc{cvs}
-which use that repository in local or server mode.  If
-you cannot upgrade, use the @code{watch off} and
-@code{watch remove} commands to remove all watches, and
-that will restore the repository to a state which
-@sc{cvs} 1.6 can cope with.
-
-@node Choosing a model
-@section Choosing between reserved or unreserved checkouts
-@cindex Choosing, reserved or unreserved checkouts
-
-Reserved and unreserved checkouts each have pros and
-cons.  Let it be said that a lot of this is a matter of
-opinion or what works given different groups' working
-styles, but here is a brief description of some of the
-issues.  There are many ways to organize a team of
-developers.  @sc{cvs} does not try to enforce a certain
-organization.  It is a tool that can be used in several
-ways.
-
-Reserved checkouts can be very counter-productive.  If
-two persons want to edit different parts of a file,
-there may be no reason to prevent either of them from
-doing so.  Also, it is common for someone to take out a
-lock on a file, because they are planning to edit it,
-but then forget to release the lock.
-
-@c "many groups"?  specifics?  cites to papers on this?
-@c some way to weasel-word it a bit more so we don't
-@c need facts :-)?
-People, especially people who are familiar with
-reserved checkouts, often wonder how often conflicts
-occur if unreserved checkouts are used, and how
-difficult they are to resolve.  The experience with
-many groups is that they occur rarely and usually are
-relatively straightforward to resolve.
-
-The rarity of serious conflicts may be surprising, until one realizes
-that they occur only when two developers disagree on the proper design
-for a given section of code; such a disagreement suggests that the
-team has not been communicating properly in the first place.  In order
-to collaborate under @emph{any} source management regimen, developers
-must agree on the general design of the system; given this agreement,
-overlapping changes are usually straightforward to merge.
-
-In some cases unreserved checkouts are clearly
-inappropriate.  If no merge tool exists for the kind of
-file you are managing (for example word processor files
-or files edited by Computer Aided Design programs), and
-it is not desirable to change to a program which uses a
-mergeable data format, then resolving conflicts is
-going to be unpleasant enough that you generally will
-be better off to simply avoid the conflicts instead, by
-using reserved checkouts.
-
-The watches features described above in @ref{Watches}
-can be considered to be an intermediate model between
-reserved checkouts and unreserved checkouts.  When you
-go to edit a file, it is possible to find out who else
-is editing it.  And rather than having the system
-simply forbid both people editing the file, it can tell
-you what the situation is and let you figure out
-whether it is a problem in that particular case or not.
-Therefore, for some groups watches can be
-considered the best of both the reserved checkout and unreserved
-checkout worlds.
-
-As of @sc{cvs} client and server versions 1.12.10, you may also enable
-advisory locks by putting @samp{edit -c} and @samp{commit -c} in all
-developers' @file{.cvsrc} files.  After this is done, @code{cvs edit}
-will fail if there are any other editors, and @code{cvs commit} will
-fail if the committer has not registered to edit the file via @code{cvs edit}.
-This is most effective in conjunction with files checked out read-only by
-default, which may be enabled by turning on watches in the repository or by
-putting @samp{cvs -r} in all @file{.cvsrc} files.
-
-
-@c ---------------------------------------------------------------------
-@node Revision management
-@chapter Revision management
-@cindex Revision management
-
-@c -- This chapter could be expanded a lot.
-@c -- Experiences are very welcome!
-
-If you have read this far, you probably have a pretty
-good grasp on what @sc{cvs} can do for you.  This
-chapter talks a little about things that you still have
-to decide.
-
-If you are doing development on your own using @sc{cvs}
-you could probably skip this chapter.  The questions
-this chapter takes up become more important when more
-than one person is working in a repository.
-
-@menu
-* When to commit::              Some discussion on the subject
-@end menu
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node When to commit
-@section When to commit?
-@cindex When to commit
-@cindex Committing, when to
-@cindex Policy
-
-Your group should decide which policy to use regarding
-commits.  Several policies are possible, and as your
-experience with @sc{cvs} grows you will probably find
-out what works for you.
-
-If you commit files too quickly you might commit files
-that do not even compile.  If your partner updates his
-working sources to include your buggy file, he will be
-unable to compile the code.  On the other hand, other
-persons will not be able to benefit from the
-improvements you make to the code if you commit very
-seldom, and conflicts will probably be more common.
-
-It is common to only commit files after making sure
-that they can be compiled.  Some sites require that the
-files pass a test suite.  Policies like this can be
-enforced using the commitinfo file
-(@pxref{commitinfo}), but you should think twice before
-you enforce such a convention.  By making the
-development environment too controlled it might become
-too regimented and thus counter-productive to the real
-goal, which is to get software written.
-
-@c ---------------------------------------------------------------------
-@node Keyword substitution
-@chapter Keyword substitution
-@cindex Keyword substitution
-@cindex Keyword expansion
-@cindex Identifying files
-
-@comment   Be careful when editing this chapter.
-@comment   Remember that this file is kept under
-@comment   version control, so we must not accidentally
-@comment   include a valid keyword in the running text.
-
-As long as you edit source files inside a working
-directory you can always find out the state of
-your files via @samp{cvs status} and @samp{cvs log}.
-But as soon as you export the files from your
-development environment it becomes harder to identify
-which revisions they are.
-
-@sc{cvs} can use a mechanism known as @dfn{keyword
-substitution} (or @dfn{keyword expansion}) to help
-identifying the files.  Embedded strings of the form
-@code{$@var{keyword}$} and
-@code{$@var{keyword}:@dots{}$} in a file are replaced
-with strings of the form
-@code{$@var{keyword}:@var{value}$} whenever you obtain
-a new revision of the file.
-
-@menu
-* Keyword list::                   Keywords
-* Using keywords::                 Using keywords
-* Avoiding substitution::          Avoiding substitution
-* Substitution modes::             Substitution modes
-* Configuring keyword expansion::  Configuring keyword expansion
-* Log keyword::                    Problems with the $@splitrcskeyword{Log}$ keyword.
-@end menu
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Keyword list
-@section Keyword List
-@cindex Keyword List
-
-@c FIXME: need some kind of example here I think,
-@c perhaps in a
-@c "Keyword intro" node.  The intro in the "Keyword
-@c substitution" node itself seems OK, but to launch
-@c into a list of the keywords somehow seems too abrupt.
-
-This is a list of the keywords:
-
-@table @code
-@cindex Author keyword
-@item $@splitrcskeyword{Author}$
-The login name of the user who checked in the revision.
-
-@cindex CVSHeader keyword
-@item $@splitrcskeyword{CVSHeader}$
-A standard header (similar to $@splitrcskeyword{Header}$, but with
-the CVS root stripped off). It contains the relative
-pathname of the @sc{rcs} file to the CVS root, the
-revision number, the date (UTC), the author, the state,
-and the locker (if locked). Files will normally never
-be locked when you use @sc{cvs}.
-
-Note that this keyword has only been recently
-introduced to @sc{cvs} and may cause problems with
-existing installations if $@splitrcskeyword{CVSHeader}$ is already
-in the files for a different purpose. This keyword may
-be excluded using the @code{KeywordExpand=eCVSHeader}
-in the @file{CVSROOT/config} file. 
-See @ref{Configuring keyword expansion} for more details.
-
-@cindex Date keyword
-@item $@splitrcskeyword{Date}$
-The date and time (UTC) the revision was checked in.
-
-@cindex Header keyword
-@item $@splitrcskeyword{Header}$
-A standard header containing the full pathname of the
-@sc{rcs} file, the revision number, the date (UTC), the
-author, the state, and the locker (if locked).  Files
-will normally never be locked when you use @sc{cvs}.
-
-@cindex Id keyword
-@item $@splitrcskeyword{Id}$
-Same as @code{$@splitrcskeyword{Header}$}, except that the @sc{rcs}
-filename is without a path.
-
-@cindex Name keyword
-@item $@splitrcskeyword{Name}$
-Tag name used to check out this file.  The keyword is
-expanded only if one checks out with an explicit tag
-name.  For example, when running the command @code{cvs
-co -r first}, the keyword expands to @samp{Name: first}.
-
-@cindex Locker keyword
-@item $@splitrcskeyword{Locker}$
-The login name of the user who locked the revision
-(empty if not locked, which is the normal case unless
-@code{cvs admin -l} is in use).
-
-@cindex Log keyword
-@cindex MaxCommentLeaderLength
-@cindex UseArchiveCommentLeader
-@cindex Log keyword, configuring substitution behavior
-@item $@splitrcskeyword{Log}$
-The log message supplied during commit, preceded by a
-header containing the @sc{rcs} filename, the revision
-number, the author, and the date (UTC).  Existing log
-messages are @emph{not} replaced.  Instead, the new log
-message is inserted after @code{$@splitrcskeyword{Log}:@dots{}$}.
-By default, each new line is prefixed with the same string which
-precedes the @code{$@splitrcskeyword{Log}$} keyword, unless it exceeds the
-@code{MaxCommentLeaderLength} set in @file{CVSROOT/config}.
-
-For example, if the file contains:
-
-@example
-  /* Here is what people have been up to:
-   *
-   * $@splitrcskeyword{Log}: frob.c,v $
-   * Revision 1.1  1997/01/03 14:23:51  joe
-   * Add the superfrobnicate option
-   *
-   */
-@end example
-
-@noindent
-then additional lines which are added when expanding
-the @code{$@splitrcskeyword{Log}$} keyword will be preceded by @samp{   * }.
-Unlike previous versions of @sc{cvs} and @sc{rcs}, the
-@dfn{comment leader} from the @sc{rcs} file is not used.
-The @code{$@splitrcskeyword{Log}$} keyword is useful for
-accumulating a complete change log in a source file,
-but for several reasons it can be problematic.
-
-If the prefix of the @code{$@splitrcskeyword{Log}$} keyword turns out to be
-longer than @code{MaxCommentLeaderLength}, CVS will skip expansion of this
-keyword unless @code{UseArchiveCommentLeader} is also set in
-@file{CVSROOT/config} and a @samp{comment leader} is set in the RCS archive
-file, in which case the comment leader will be used instead.  For more on
-setting the comment leader in the RCS archive file, @xref{admin}.  For more
-on configuring the default @code{$@splitrcskeyword{Log}$} substitution
-behavior, @xref{config}.
-
-@xref{Log keyword}.
-
-@cindex RCSfile keyword
-@item $@splitrcskeyword{RCSfile}$
-The name of the RCS file without a path.
-
-@cindex Revision keyword
-@item $@splitrcskeyword{Revision}$
-The revision number assigned to the revision.
-
-@cindex Source keyword
-@item $@splitrcskeyword{Source}$
-The full pathname of the RCS file.
-
-@cindex State keyword
-@item $@splitrcskeyword{State}$
-The state assigned to the revision.  States can be
-assigned with @code{cvs admin -s}---see @ref{admin options}.
-
-@cindex Local keyword
-@item Local keyword
-The @code{LocalKeyword} option in the @file{CVSROOT/config} file
-may be used to specify a local keyword which is to be
-used as an alias for one of the keywords: $@splitrcskeyword{Id}$,
-$@splitrcskeyword{Header}$, or $@splitrcskeyword{CVSHeader}$. For
-example, if the @file{CVSROOT/config} file contains
-a line with @code{LocalKeyword=MYBSD=CVSHeader}, then a
-file with the local keyword $@splitrcskeyword{MYBSD}$ will be
-expanded as if it were a $@splitrcskeyword{CVSHeader}$ keyword. If
-the src/frob.c file contained this keyword, it might
-look something like this:
-
-@example
-  /*
-   * $@splitrcskeyword{MYBSD}: src/frob.c,v 1.1 2003/05/04 09:27:45 john Exp $ 
-   */
-@end example
-
-Many repositories make use of a such a ``local
-keyword'' feature. An old patch to @sc{cvs} provided
-the @code{LocalKeyword} feature using a @code{tag=}
-option and called this the ``custom tag'' or ``local
-tag'' feature. It was used in conjunction with the
-what they called the @code{tagexpand=} option. In
-@sc{cvs} this other option is known as the
-@code{KeywordExpand} option. 
-See @ref{Configuring keyword expansion} for more
-details.
-
-Examples from popular projects include:
-$@splitrcskeyword{FreeBSD}$, $@splitrcskeyword{NetBSD}$,
-$@splitrcskeyword{OpenBSD}$, $@splitrcskeyword{XFree86}$,
-$@splitrcskeyword{Xorg}$.
-
-The advantage of this is that you can include your
-local version information in a file using this local
-keyword without disrupting the upstream version
-information (which may be a different local keyword or
-a standard keyword). Allowing bug reports and the like
-to more properly identify the source of the original
-bug to the third-party and reducing the number of
-conflicts that arise during an import of a new version.
-
-All keyword expansion except the local keyword may be
-disabled using the @code{KeywordExpand} option in
-the @file{CVSROOT/config} file---see 
-@ref{Configuring keyword expansion} for more details.
-
-@end table
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Using keywords
-@section Using keywords
-
-To include a keyword string you simply include the
-relevant text string, such as @code{$@splitrcskeyword{Id}$}, inside the
-file, and commit the file.  @sc{cvs} will automatically (Or,
-more accurately, as part of the update run that
-automatically happens after a commit.)
-expand the string as part of the commit operation.
-
-It is common to embed the @code{$@splitrcskeyword{Id}$} string in
-the source files so that it gets passed through to
-generated files.  For example, if you are managing
-computer program source code, you might include a
-variable which is initialized to contain that string.
-Or some C compilers may provide a @code{#pragma ident}
-directive.  Or a document management system might
-provide a way to pass a string through to generated
-files.
-
-@c Would be nice to give an example, but doing this in
-@c portable C is not possible and the problem with
-@c picking any one language (VMS HELP files, Ada,
-@c troff, whatever) is that people use CVS for all
-@c kinds of files.
-
-@cindex Ident (shell command)
-The @code{ident} command (which is part of the @sc{rcs}
-package) can be used to extract keywords and their
-values from a file.  This can be handy for text files,
-but it is even more useful for extracting keywords from
-binary files.
-
-@example
-$ ident samp.c
-samp.c:
-     $@splitrcskeyword{Id}: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $
-$ gcc samp.c
-$ ident a.out
-a.out:
-     $@splitrcskeyword{Id}: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $
-@end example
-
-@cindex What (shell command)
-S@sc{ccs} is another popular revision control system.
-It has a command, @code{what}, which is very similar to
-@code{ident} and used for the same purpose.  Many sites
-without @sc{rcs} have @sc{sccs}.  Since @code{what}
-looks for the character sequence @code{@@(#)} it is
-easy to include keywords that are detected by either
-command.  Simply prefix the keyword with the
-magic @sc{sccs} phrase, like this:
-
-@example
-static char *id="@@(#) $@splitrcskeyword{Id}: ab.c,v 1.5 1993/10/19 14:57:32 ceder Exp $";
-@end example
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Avoiding substitution
-@section Avoiding substitution
-
-Keyword substitution has its disadvantages.  Sometimes
-you might want the literal text string
-@samp{$@splitrcskeyword{Author}$} to appear inside a file without
-@sc{cvs} interpreting it as a keyword and expanding it
-into something like @samp{$@splitrcskeyword{Author}: ceder $}.
-
-There is unfortunately no way to selectively turn off
-keyword substitution.  You can use @samp{-ko}
-(@pxref{Substitution modes}) to turn off keyword
-substitution entirely.
-
-In many cases you can avoid using keywords in
-the source, even though they appear in the final
-product.  For example, the source for this manual
-contains @samp{$@@asis@{@}Author$} whenever the text
-@samp{$@splitrcskeyword{Author}$} should appear.  In @code{nroff}
-and @code{troff} you can embed the null-character
-@code{\&} inside the keyword for a similar effect.
-
-It is also possible to specify an explicit list of
-keywords to include or exclude using the
-@code{KeywordExpand} option in the
-@file{CVSROOT/config} file--see @ref{Configuring keyword expansion}
-for more details. This feature is intended primarily
-for use with the @code{LocalKeyword} option--see
-@ref{Keyword list}.
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Substitution modes
-@section Substitution modes
-@cindex Keyword substitution, changing modes
-@cindex -k (keyword substitution)
-@cindex Kflag
-
-@c FIXME: This could be made more coherent, by expanding it
-@c with more examples or something.
-Each file has a stored default substitution mode, and
-each working directory copy of a file also has a
-substitution mode.  The former is set by the @samp{-k}
-option to @code{cvs add} and @code{cvs admin}; the
-latter is set by the @samp{-k} or @samp{-A} options to @code{cvs
-checkout} or @code{cvs update}.
-@code{cvs diff} and @code{cvs rdiff} also
-have @samp{-k} options.
-For some examples,
-see @ref{Binary files}, and @ref{Merging and keywords}.
-@c The fact that -A is overloaded to mean both reset
-@c sticky options and reset sticky tags/dates is
-@c somewhat questionable.  Perhaps there should be
-@c separate options to reset sticky options (e.g. -k
-@c A") and tags/dates (someone suggested -r HEAD could
-@c do this instead of setting a sticky tag of "HEAD"
-@c as in the status quo but I haven't thought much
-@c about that idea.  Of course -r .reset or something
-@c could be coined if this needs to be a new option).
-@c On the other hand, having -A mean "get things back
-@c into the state after a fresh checkout" has a certain
-@c appeal, and maybe there is no sufficient reason for
-@c creeping featurism in this area.
-
-The modes available are:
-
-@table @samp
-@item -kkv
-Generate keyword strings using the default form, e.g.
-@code{$@splitrcskeyword{Revision}: 5.7 $} for the @code{Revision}
-keyword.
-
-@item -kkvl
-Like @samp{-kkv}, except that a locker's name is always
-inserted if the given revision is currently locked.
-The locker's name is only relevant if @code{cvs admin
--l} is in use.
-
-@item -kk
-Generate only keyword names in keyword strings; omit
-their values.  For example, for the @code{Revision}
-keyword, generate the string @code{$@splitrcskeyword{Revision}$}
-instead of @code{$@splitrcskeyword{Revision}: 5.7 $}.  This option
-is useful to ignore differences due to keyword
-substitution when comparing different revisions of a
-file (@pxref{Merging and keywords}).
-
-@item -ko
-Generate the old keyword string, present in the working
-file just before it was checked in.  For example, for
-the @code{Revision} keyword, generate the string
-@code{$@splitrcskeyword{Revision}: 1.1 $} instead of
-@code{$@splitrcskeyword{Revision}: 5.7 $} if that is how the
-string appeared when the file was checked in.
-
-@item -kb
-Like @samp{-ko}, but also inhibit conversion of line
-endings between the canonical form in which they are
-stored in the repository (linefeed only), and the form
-appropriate to the operating system in use on the
-client.  For systems, like unix, which use linefeed
-only to terminate lines, this is very similar to
-@samp{-ko}.  For more information on binary files, see
-@ref{Binary files}.  In @sc{cvs} version 1.12.2 and later
-@samp{-kb}, as set by @code{cvs add}, @code{cvs admin}, or
-@code{cvs import} may not be overridden by a @samp{-k} option
-specified on the command line.
-
-@item -kv
-Generate only keyword values for keyword strings.  For
-example, for the @code{Revision} keyword, generate the string
-@code{5.7} instead of @code{$@splitrcskeyword{Revision}: 5.7 $}.
-This can help generate files in programming languages
-where it is hard to strip keyword delimiters like
-@code{$@splitrcskeyword{Revision}: $} from a string.  However,
-further keyword substitution cannot be performed once
-the keyword names are removed, so this option should be
-used with care.
-
-One often would like to use @samp{-kv} with @code{cvs
-export}---@pxref{export}.  But be aware that doesn't
-handle an export containing binary files correctly.
-
-@end table
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Configuring keyword expansion
-@section Configuring Keyword Expansion
-@cindex Configuring keyword expansion
-
-In a repository that includes third-party software on
-vendor branches, it is sometimes helpful to configure
-CVS to use a local keyword instead of the standard
-$@splitrcskeyword{Id}$ or $@splitrcskeyword{Header}$ keywords. Examples from
-real projects include $@splitrcskeyword{Xorg}$, $@splitrcskeyword{XFree86}$,
-$@splitrcskeyword{FreeBSD}$, $@splitrcskeyword{NetBSD}$,
-$@splitrcskeyword{OpenBSD}$, and even $@splitrcskeyword{dotat}$.
-The advantage of this is that
-you can include your local version information in a
-file using this local keyword (sometimes called a
-``custom tag'' or a ``local tag'') without disrupting
-the upstream version information (which may be a
-different local keyword or a standard keyword). In
-these cases, it is typically desirable to disable the
-expansion of all keywords except the configured local
-keyword.
-
-The @code{KeywordExpand} option in the
-@file{CVSROOT/config} file is intended to allow for the
-either the explicit exclusion of a keyword or list of
-keywords, or for the explicit inclusion of a keyword or
-a list of keywords. This list may include the
-@code{LocalKeyword} that has been configured.
-
-The @code{KeywordExpand} option is followed by
-@code{=} and the next character may either be @code{i}
-to start an inclusion list or @code{e} to start an
-exclusion list. If the following lines were added to
-the @file{CVSROOT/config} file:
-
-@example
-        # Add a "MyBSD" keyword and restrict keyword
-        # expansion
-        LocalKeyword=MyBSD=CVSHeader
-        KeywordExpand=iMyBSD
-@end example
-
-then only the $@splitrcskeyword{MyBSD}$ keyword would be expanded.
-A list may be used. The this example:
-
-@example
-        # Add a "MyBSD" keyword and restrict keyword
-        # expansion to the MyBSD, Name and Date keywords.
-        LocalKeyword=MyBSD=CVSHeader
-        KeywordExpand=iMyBSD,Name,Date
-@end example
-
-would allow $@splitrcskeyword{MyBSD}$, $@splitrcskeyword{Name}$, and
-$@splitrcskeyword{Date}$ to be expanded.
-
-It is also possible to configure an exclusion list
-using the following:
-
-@example
-        # Do not expand the non-RCS keyword CVSHeader
-        KeywordExpand=eCVSHeader
-@end example
-
-This allows @sc{cvs} to ignore the recently introduced
-$@splitrcskeyword{CVSHeader}$ keyword and retain all of the
-others. The exclusion entry could also contain the
-standard RCS keyword list, but this could be confusing
-to users that expect RCS keywords to be expanded, so
-care should be taken to properly set user expectations
-for a repository that is configured in that manner.
-
-If there is a desire to not have any RCS keywords
-expanded and not use the @code{-ko} flags everywhere,
-an administrator may disable all keyword expansion
-using the @file{CVSROOT/config} line:
-
-@example
-       # Do not expand any RCS keywords
-       KeywordExpand=i
-@end example
-
-this could be confusing to users that expect RCS
-keywords like $@splitrcskeyword{Id}$ to be expanded properly,
-so care should be taken to properly set user
-expectations for a repository so configured.
-
-It should be noted that a patch to provide both the
-@code{KeywordExpand} and @code{LocalKeyword} features
-has been around a long time. However, that patch
-implemented these features using @code{tag=} and
-@code{tagexpand=} keywords and those keywords are NOT
-recognized.
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Log keyword
-@section Problems with the $@splitrcskeyword{Log}$ keyword.
-
-The @code{$@splitrcskeyword{Log}$} keyword is somewhat
-controversial.  As long as you are working on your
-development system the information is easily accessible
-even if you do not use the @code{$@splitrcskeyword{Log}$}
-keyword---just do a @code{cvs log}.  Once you export
-the file the history information might be useless
-anyhow.
-
-A more serious concern is that @sc{cvs} is not good at
-handling @code{$@splitrcskeyword{Log}$} entries when a branch is
-merged onto the main trunk.  Conflicts often result
-from the merging operation.
-@c Might want to check whether the CVS implementation
-@c of RCS_merge has this problem the same way rcsmerge
-@c does.  I would assume so....
-
-People also tend to "fix" the log entries in the file
-(correcting spelling mistakes and maybe even factual
-errors).  If that is done the information from
-@code{cvs log} will not be consistent with the
-information inside the file.  This may or may not be a
-problem in real life.
-
-It has been suggested that the @code{$@splitrcskeyword{Log}$}
-keyword should be inserted @emph{last} in the file, and
-not in the files header, if it is to be used at all.
-That way the long list of change messages will not
-interfere with everyday source file browsing.
-
-@c ---------------------------------------------------------------------
-@node Tracking sources
-@chapter Tracking third-party sources
-@cindex Third-party sources
-@cindex Tracking sources
-
-@c FIXME: Need discussion of added and removed files.
-@c FIXME: This doesn't really adequately introduce the
-@c concepts of "vendor" and "you".  They don't *have*
-@c to be separate organizations or separate people.
-@c We want a description which is somewhat more based on
-@c the technical issues of which sources go where, but
-@c also with enough examples of how this relates to
-@c relationships like customer-supplier, developer-QA,
-@c maintainer-contributor, or whatever, to make it
-@c seem concrete.
-If you modify a program to better fit your site, you
-probably want to include your modifications when the next
-release of the program arrives.  @sc{cvs} can help you with
-this task.
-
-@cindex Vendor
-@cindex Vendor branch
-@cindex Branch, vendor-
-In the terminology used in @sc{cvs}, the supplier of the
-program is called a @dfn{vendor}.  The unmodified
-distribution from the vendor is checked in on its own
-branch, the @dfn{vendor branch}.  @sc{cvs} reserves branch
-1.1.1 for this use.
-
-When you modify the source and commit it, your revision
-will end up on the main trunk.  When a new release is
-made by the vendor, you commit it on the vendor branch
-and copy the modifications onto the main trunk.
-
-Use the @code{import} command to create and update
-the vendor branch.  When you import a new file,
-(usually) the vendor branch is made the `head' revision, so
-anyone that checks out a copy of the file gets that
-revision.  When a local modification is committed it is
-placed on the main trunk, and made the `head'
-revision.
-
-@menu
-* First import::                Importing for the first time
-* Update imports::              Updating with the import command
-* Reverting local changes::     Reverting to the latest vendor release
-* Binary files in imports::     Binary files require special handling
-* Keywords in imports::         Keyword substitution might be undesirable
-* Multiple vendor branches::    What if you get sources from several places?
-@end menu
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node First import
-@section Importing for the first time
-@cindex Importing modules
-
-@c Should mention naming conventions for vendor tags,
-@c release tags, and perhaps directory names.
-Use the @code{import} command to check in the sources
-for the first time.  When you use the @code{import}
-command to track third-party sources, the @dfn{vendor
-tag} and @dfn{release tags} are useful.  The
-@dfn{vendor tag} is a symbolic name for the branch
-(which is always 1.1.1, unless you use the @samp{-b
-@var{branch}} flag---see @ref{Multiple vendor branches}.).  The
-@dfn{release tags} are symbolic names for a particular
-release, such as @samp{FSF_0_04}.
-
-@c I'm not completely sure this belongs here.  But
-@c we need to say it _somewhere_ reasonably obvious; it
-@c is a common misconception among people first learning CVS
-Note that @code{import} does @emph{not} change the
-directory in which you invoke it.  In particular, it
-does not set up that directory as a @sc{cvs} working
-directory; if you want to work with the sources import
-them first and then check them out into a different
-directory (@pxref{Getting the source}).
-
-@cindex wdiff (import example)
-Suppose you have the sources to a program called
-@code{wdiff} in a directory @file{wdiff-0.04},
-and are going to make private modifications that you
-want to be able to use even when new releases are made
-in the future.  You start by importing the source to
-your repository:
-
-@example
-$ cd wdiff-0.04
-$ cvs import -m "Import of FSF v. 0.04" fsf/wdiff FSF_DIST WDIFF_0_04
-@end example
-
-The vendor tag is named @samp{FSF_DIST} in the above
-example, and the only release tag assigned is
-@samp{WDIFF_0_04}.
-@c FIXME: Need to say where fsf/wdiff comes from.
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Update imports
-@section Updating with the import command
-
-When a new release of the source arrives, you import it into the
-repository with the same @code{import} command that you used to set up
-the repository in the first place.  The only difference is that you
-specify a different release tag this time:
-
-@example
-$ tar xfz wdiff-0.05.tar.gz
-$ cd wdiff-0.05
-$ cvs import -m "Import of FSF v. 0.05" fsf/wdiff FSF_DIST WDIFF_0_05
-@end example
-
-@strong{WARNING: If you use a release tag that already exists in one of the
-repository archives, files removed by an import may not be detected.}
-
-For files that have not been modified locally, the newly created
-revision becomes the head revision.  If you have made local
-changes, @code{import} will warn you that you must merge the changes
-into the main trunk, and tell you to use @samp{checkout -j} to do so:
-
-@c FIXME: why "wdiff" here and "fsf/wdiff" in the
-@c "import"?  I think the assumption is that one has
-@c "wdiff fsf/wdiff" or some such in modules, but it
-@c would be better to not use modules in this example.
-@example
-$ cvs checkout -jFSF_DIST:yesterday -jFSF_DIST wdiff
-@end example
-
-@noindent
-The above command will check out the latest revision of
-@samp{wdiff}, merging the changes made on the vendor branch @samp{FSF_DIST}
-since yesterday into the working copy.  If any conflicts arise during
-the merge they should be resolved in the normal way (@pxref{Conflicts
-example}).  Then, the modified files may be committed.
-
-However, it is much better to use the two release tags rather than using
-a date on the branch as suggested above:
-
-@example
-$ cvs checkout -jWDIFF_0_04 -jWDIFF_0_05 wdiff
-@end example
-
-@noindent
-The reason this is better is that
-using a date, as suggested above, assumes that you do
-not import more than one release of a product per day.
-More importantly, using the release tags allows @sc{cvs} to detect files
-that were removed between the two vendor releases and mark them for
-removal.  Since @code{import} has no way to detect removed files, you
-should do a merge like this even if @code{import} doesn't tell you to.
-
-@node Reverting local changes
-@section Reverting to the latest vendor release
-
-You can also revert local changes completely and return
-to the latest vendor release by changing the `head'
-revision back to the vendor branch on all files.  For
-example, if you have a checked-out copy of the sources
-in @file{~/work.d/wdiff}, and you want to revert to the
-vendor's version for all the files in that directory,
-you would type:
-
-@example
-$ cd ~/work.d/wdiff
-$ cvs admin -bFSF_DIST .
-@end example
-
-@noindent
-You must specify the @samp{-bFSF_DIST} without any space
-after the @samp{-b}.  @xref{admin options}.
-
-@node Binary files in imports
-@section How to handle binary files with cvs import
-
-Use the @samp{-k} wrapper option to tell import which
-files are binary.  @xref{Wrappers}.
-
-@node Keywords in imports
-@section How to handle keyword substitution with cvs import
-
-The sources which you are importing may contain
-keywords (@pxref{Keyword substitution}).  For example,
-the vendor may use @sc{cvs} or some other system
-which uses similar keyword expansion syntax.  If you
-just import the files in the default fashion, then
-the keyword expansions supplied by the vendor will
-be replaced by keyword expansions supplied by your
-own copy of @sc{cvs}.  It may be more convenient to
-maintain the expansions supplied by the vendor, so
-that this information can supply information about
-the sources that you imported from the vendor.
-
-To maintain the keyword expansions supplied by the
-vendor, supply the @samp{-ko} option to @code{cvs
-import} the first time you import the file.
-This will turn off keyword expansion
-for that file entirely, so if you want to be more
-selective you'll have to think about what you want
-and use the @samp{-k} option to @code{cvs update} or
-@code{cvs admin} as appropriate.
-@c Supplying -ko to import if the file already existed
-@c has no effect.  Not clear to me whether it should
-@c or not.
-
-@node Multiple vendor branches
-@section Multiple vendor branches
-
-All the examples so far assume that there is only one
-vendor from which you are getting sources.  In some
-situations you might get sources from a variety of
-places.  For example, suppose that you are dealing with
-a project where many different people and teams are
-modifying the software.  There are a variety of ways to
-handle this, but in some cases you have a bunch of
-source trees lying around and what you want to do more
-than anything else is just to all put them in @sc{cvs} so
-that you at least have them in one place.
-
-For handling situations in which there may be more than
-one vendor, you may specify the @samp{-b} option to
-@code{cvs import}.  It takes as an argument the vendor
-branch to import to.  The default is @samp{-b 1.1.1}.
-
-For example, suppose that there are two teams, the red
-team and the blue team, that are sending you sources.
-You want to import the red team's efforts to branch
-1.1.1 and use the vendor tag RED.  You want to import
-the blue team's efforts to branch 1.1.3 and use the
-vendor tag BLUE.  So the commands you might use are:
-
-@example
-$ cvs import dir RED RED_1-0
-$ cvs import -b 1.1.3 dir BLUE BLUE_1-5
-@end example
-
-Note that if your vendor tag does not match your
-@samp{-b} option, @sc{cvs} will not detect this case!  For
-example,
-
-@example
-$ cvs import -b 1.1.3 dir RED RED_1-0
-@end example
-
-@noindent
-Be careful; this kind of mismatch is sure to sow
-confusion or worse.  I can't think of a useful purpose
-for the ability to specify a mismatch here, but if you
-discover such a use, don't.  @sc{cvs} is likely to make this
-an error in some future release.
-
-@c Probably should say more about the semantics of
-@c multiple branches.  What about the default branch?
-@c What about joining (perhaps not as useful with
-@c multiple branches, or perhaps it is.  Either way
-@c should be mentioned).
-
-@c I'm not sure about the best location for this.  In
-@c one sense, it might belong right after we've introduced
-@c CVS's basic version control model, because people need
-@c to figure out builds right away.  The current location
-@c is based on the theory that it kind of akin to the
-@c "Revision management" section.
-@node Builds
-@chapter How your build system interacts with CVS
-@cindex Builds
-@cindex make
-
-As mentioned in the introduction, @sc{cvs} does not
-contain software for building your software from source
-code.  This section describes how various aspects of
-your build system might interact with @sc{cvs}.
-
-@c Is there a way to discuss this without reference to
-@c tools other than CVS?  I'm not sure there is; I
-@c wouldn't think that people who learn CVS first would
-@c even have this concern.
-One common question, especially from people who are
-accustomed to @sc{rcs}, is how to make their build get
-an up to date copy of the sources.  The answer to this
-with @sc{cvs} is two-fold.  First of all, since
-@sc{cvs} itself can recurse through directories, there
-is no need to modify your @file{Makefile} (or whatever
-configuration file your build tool uses) to make sure
-each file is up to date.  Instead, just use two
-commands, first @code{cvs -q update} and then
-@code{make} or whatever the command is to invoke your
-build tool.  Secondly, you do not necessarily
-@emph{want} to get a copy of a change someone else made
-until you have finished your own work.  One suggested
-approach is to first update your sources, then
-implement, build and
-test the change you were thinking of, and then commit
-your sources (updating first if necessary).  By
-periodically (in between changes, using the approach
-just described) updating your entire tree, you ensure
-that your sources are sufficiently up to date.
-
-@cindex Bill of materials
-One common need is to record which versions of which
-source files went into a particular build.  This kind
-of functionality is sometimes called @dfn{bill of
-materials} or something similar.  The best way to do
-this with @sc{cvs} is to use the @code{tag} command to
-record which versions went into a given build
-(@pxref{Tags}).
-
-Using @sc{cvs} in the most straightforward manner
-possible, each developer will have a copy of the entire
-source tree which is used in a particular build.  If
-the source tree is small, or if developers are
-geographically dispersed, this is the preferred
-solution.  In fact one approach for larger projects is
-to break a project down into smaller
-@c I say subsystem instead of module because they may or
-@c may not use the modules file.
-separately-compiled subsystems, and arrange a way of
-releasing them internally so that each developer need
-check out only those subsystems which they are
-actively working on.
-
-Another approach is to set up a structure which allows
-developers to have their own copies of some files, and
-for other files to access source files from a central
-location.  Many people have come up with some such a
-@c two such people are paul@sander.cupertino.ca.us (for
-@c a previous employer)
-@c and gunnar.tornblom@se.abb.com (spicm and related tools),
-@c but as far as I know
-@c no one has nicely packaged or released such a system (or
-@c instructions for constructing one).
-system using features such as the symbolic link feature
-found in many operating systems, or the @code{VPATH}
-feature found in many versions of @code{make}.  One build
-tool which is designed to help with this kind of thing
-is Odin (see
-@code{ftp://ftp.cs.colorado.edu/pub/distribs/odin}).
-@c Should we be saying more about Odin?  Or how you use
-@c it with CVS?  Also, the Prime Time Freeware for Unix
-@c disk (see http://www.ptf.com/) has Odin (with a nice
-@c paragraph summarizing it on the web), so that might be a
-@c semi-"official" place to point people.
-@c
-@c Of course, many non-CVS systems have this kind of
-@c functionality, for example OSF's ODE
-@c (http://www.osf.org/ode/) or mk
-@c (http://www.grin.net/~pzi/mk-3.18.4.docs/mk_toc.html
-@c He has changed providers in the past; a search engine search
-@c for "Peter Ziobrzynski" probably won't get too many
-@c spurious hits :-).  A more stable URL might be
-@c ftp://ftp.uu.net/pub/cmvc/mk).  But I'm not sure
-@c there is any point in mentioning them here unless they
-@c can work with CVS.
-
-@c ---------------------------------------------------------------------
-@node Special Files
-@chapter Special Files
-
-@cindex Special files
-@cindex Device nodes
-@cindex Ownership, saving in CVS
-@cindex Permissions, saving in CVS
-@cindex Hard links
-@cindex Symbolic links
-
-In normal circumstances, @sc{cvs} works only with regular
-files.  Every file in a project is assumed to be
-persistent; it must be possible to open, read and close
-them; and so on.  @sc{cvs} also ignores file permissions and
-ownerships, leaving such issues to be resolved by the
-developer at installation time.  In other words, it is
-not possible to "check in" a device into a repository;
-if the device file cannot be opened, @sc{cvs} will refuse to
-handle it.  Files also lose their ownerships and
-permissions during repository transactions.
-
-@ignore
-If the configuration variable @code{PreservePermissions}
-(@pxref{config}) is set in the repository, @sc{cvs} will
-save the following file characteristics in the
-repository:
-
-@itemize @bullet
-@item user and group ownership
-@item permissions
-@item major and minor device numbers
-@item symbolic links
-@item hard link structure
-@end itemize
-
-Using the @code{PreservePermissions} option affects the
-behavior of @sc{cvs} in several ways.  First, some of the
-new operations supported by @sc{cvs} are not accessible to
-all users.  In particular, file ownership and special
-file characteristics may only be changed by the
-superuser.  When the @code{PreservePermissions}
-configuration variable is set, therefore, users will
-have to be `root' in order to perform @sc{cvs} operations.
-
-When @code{PreservePermissions} is in use, some @sc{cvs}
-operations (such as @samp{cvs status}) will not
-recognize a file's hard link structure, and so will
-emit spurious warnings about mismatching hard links.
-The reason is that @sc{cvs}'s internal structure does not
-make it easy for these operations to collect all the
-necessary data about hard links, so they check for file
-conflicts with inaccurate data.
-
-A more subtle difference is that @sc{cvs} considers a file
-to have changed only if its contents have changed
-(specifically, if the modification time of the working
-file does not match that of the repository's file).
-Therefore, if only the permissions, ownership or hard
-linkage have changed, or if a device's major or minor
-numbers have changed, @sc{cvs} will not notice.  In order to
-commit such a change to the repository, you must force
-the commit with @samp{cvs commit -f}.  This also means
-that if a file's permissions have changed and the
-repository file is newer than the working copy,
-performing @samp{cvs update} will silently change the
-permissions on the working copy.
-
-Changing hard links in a @sc{cvs} repository is particularly
-delicate.  Suppose that file @file{foo} is linked to
-file @file{old}, but is later relinked to file
-@file{new}.  You can wind up in the unusual situation
-where, although @file{foo}, @file{old} and @file{new}
-have all had their underlying link patterns changed,
-only @file{foo} and @file{new} have been modified, so
-@file{old} is not considered a candidate for checking
-in.  It can be very easy to produce inconsistent
-results this way.  Therefore, we recommend that when it
-is important to save hard links in a repository, the
-prudent course of action is to @code{touch} any file
-whose linkage or status has changed since the last
-checkin.  Indeed, it may be wise to @code{touch *}
-before each commit in a directory with complex hard
-link structures.
-
-It is worth noting that only regular files may
-be merged, for reasons that hopefully are obvious.  If
-@samp{cvs update} or @samp{cvs checkout -j} attempts to
-merge a symbolic link with a regular file, or two
-device files for different kinds of devices, @sc{cvs} will
-report a conflict and refuse to perform the merge.  At
-the same time, @samp{cvs diff} will not report any
-differences between these files, since no meaningful
-textual comparisons can be made on files which contain
-no text.
-
-The @code{PreservePermissions} features do not work
-with client/server @sc{cvs}.  Another limitation is
-that hard links must be to other files within the same
-directory; hard links across directories are not
-supported.
-@end ignore
-
-@c ---------------------------------------------------------------------
-@c ----- START MAN 1 -----
-@node CVS commands
-@appendix Guide to CVS commands
-
-This appendix describes the overall structure of
-@sc{cvs} commands, and describes some commands in
-detail (others are described elsewhere; for a quick
-reference to @sc{cvs} commands, @pxref{Invoking CVS}).
-@c The idea is that we want to move the commands which
-@c are described here into the main body of the manual,
-@c in the process reorganizing the manual to be
-@c organized around what the user wants to do, not
-@c organized around CVS commands.
-@c
-@c Note that many users do expect a manual which is
-@c organized by command.  At least some users do.
-@c One good addition to the "organized by command"
-@c section (if any) would be "see also" links.
-@c The awk manual might be a good example; it has a
-@c reference manual which is more verbose than Invoking
-@c CVS but probably somewhat less verbose than CVS
-@c Commands.
-
-@menu
-* Structure::                   Overall structure of CVS commands
-* Exit status::                 Indicating CVS's success or failure
-* ~/.cvsrc::                    Default options with the ~/.cvsrc file
-* Global options::              Options you give to the left of cvs_command
-* Common options::              Options you give to the right of cvs_command
-* Date input formats::         Acceptable formats for date specifications
-* admin::                       Administration
-* annotate::                    What revision modified each line of a file?
-* checkout::                    Checkout sources for editing
-* commit::                      Check files into the repository
-* diff::                        Show differences between revisions
-* export::                      Export sources from CVS, similar to checkout
-* history::                     Show status of files and users
-* import::                      Import sources into CVS, using vendor branches
-* log::                         Show log messages for files
-* ls & rls::                    List files in the repository
-* rdiff::                       'patch' format diffs between releases
-* release::                     Indicate that a directory is no longer in use
-* server & pserver::            Act as a server for a client on stdin/stdout
-* update::                      Bring work tree in sync with repository
-@end menu
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Structure
-@appendixsec Overall structure of CVS commands
-@cindex Structure
-@cindex CVS command structure
-@cindex Command structure
-@cindex Format of CVS commands
-
-The overall format of all @sc{cvs} commands is:
-
-@example
-cvs [ cvs_options ] cvs_command [ command_options ] [ command_args ]
-@end example
-
-@table @code
-@item cvs
-The name of the @sc{cvs} program.
-
-@item cvs_options
-Some options that affect all sub-commands of @sc{cvs}.  These are
-described below.
-
-@item cvs_command
-One of several different sub-commands.  Some of the commands have
-aliases that can be used instead; those aliases are noted in the
-reference manual for that command.  There are only two situations
-where you may omit @samp{cvs_command}: @samp{cvs -H} elicits a
-list of available commands, and @samp{cvs -v} displays version
-information on @sc{cvs} itself.
-
-@item command_options
-Options that are specific for the command.
-
-@item command_args
-Arguments to the commands.
-@end table
-
-There is unfortunately some confusion between
-@code{cvs_options} and @code{command_options}.
-When given as a @code{cvs_option}, some options only
-affect some of the commands.  When given as a
-@code{command_option} it may have a different meaning, and
-be accepted by more commands.  In other words, do not
-take the above categorization too seriously.  Look at
-the documentation instead.
-
-@node Exit status
-@appendixsec CVS's exit status
-@cindex Exit status, of CVS
-
-@sc{cvs} can indicate to the calling environment whether it
-succeeded or failed by setting its @dfn{exit status}.
-The exact way of testing the exit status will vary from
-one operating system to another.  For example in a unix
-shell script the @samp{$?} variable will be 0 if the
-last command returned a successful exit status, or
-greater than 0 if the exit status indicated failure.
-
-If @sc{cvs} is successful, it returns a successful status;
-if there is an error, it prints an error message and
-returns a failure status.  The one exception to this is
-the @code{cvs diff} command.  It will return a
-successful status if it found no differences, or a
-failure status if there were differences or if there
-was an error.  Because this behavior provides no good
-way to detect errors, in the future it is possible that
-@code{cvs diff} will be changed to behave like the
-other @sc{cvs} commands.
-@c It might seem like checking whether cvs -q diff
-@c produces empty or non-empty output can tell whether
-@c there were differences or not.  But it seems like
-@c there are cases with output but no differences
-@c (testsuite basica-8b).  It is not clear to me how
-@c useful it is for a script to be able to check
-@c whether there were differences.
-@c FIXCVS? In previous versions of CVS, cvs diff
-@c returned 0 for no differences, 1 for differences, or
-@c 2 for errors.  Is this behavior worth trying to
-@c bring back (but what does it mean for VMS?)?
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node ~/.cvsrc
-@appendixsec Default options and the ~/.cvsrc file
-@cindex .cvsrc file
-@cindex Option defaults
-
-There are some @code{command_options} that are used so
-often that you might have set up an alias or some other
-means to make sure you always specify that option.  One
-example (the one that drove the implementation of the
-@file{.cvsrc} support, actually) is that many people find the
-default output of the @samp{diff} command to be very
-hard to read, and that either context diffs or unidiffs
-are much easier to understand.
-
-The @file{~/.cvsrc} file is a way that you can add
-default options to @code{cvs_commands} within cvs,
-instead of relying on aliases or other shell scripts.
-
-The format of the @file{~/.cvsrc} file is simple.  The
-file is searched for a line that begins with the same
-name as the @code{cvs_command} being executed.  If a
-match is found, then the remainder of the line is split
-up (at whitespace characters) into separate options and
-added to the command arguments @emph{before} any
-options from the command line.
-
-If a command has two names (e.g., @code{checkout} and
-@code{co}), the official name, not necessarily the one
-used on the command line, will be used to match against
-the file.  So if this is the contents of the user's
-@file{~/.cvsrc} file:
-
-@example
-log -N
-diff -uN
-rdiff -u
-update -Pd
-checkout -P
-release -d
-@end example
-
-@noindent
-the command @samp{cvs checkout foo} would have the
-@samp{-P} option added to the arguments, as well as
-@samp{cvs co foo}.
-
-With the example file above, the output from @samp{cvs
-diff foobar} will be in unidiff format.  @samp{cvs diff
--c foobar} will provide context diffs, as usual.
-Getting "old" format diffs would be slightly more
-complicated, because @code{diff} doesn't have an option
-to specify use of the "old" format, so you would need
-@samp{cvs -f diff foobar}.
-
-In place of the command name you can use @code{cvs} to
-specify global options (@pxref{Global options}).  For
-example the following line in @file{.cvsrc}
-
-@example
-cvs -z6
-@end example
-
-@noindent
-causes @sc{cvs} to use compression level 6.
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Global options
-@appendixsec Global options
-@cindex Options, global
-@cindex Global options
-@cindex Left-hand options
-
-The available @samp{cvs_options} (that are given to the
-left of @samp{cvs_command}) are:
-
-@table @code
-@item --allow-root=@var{rootdir}
-May be invoked multiple times to specify one legal @sc{cvsroot} directory with
-each invocation.  Also causes CVS to preparse the configuration file for each
-specified root, which can be useful when configuring write proxies,  See
-@ref{Password authentication server} & @ref{Write proxies}.
-
-@cindex Authentication, stream
-@cindex Stream authentication
-@item -a
-Authenticate all communication between the client and
-the server.  Only has an effect on the @sc{cvs} client.
-As of this writing, this is only implemented when using
-a GSSAPI connection (@pxref{GSSAPI authenticated}).
-Authentication prevents certain sorts of attacks
-involving hijacking the active @sc{tcp} connection.
-Enabling authentication does not enable encryption.
-
-@cindex RCSBIN, overriding
-@cindex Overriding RCSBIN
-@item -b @var{bindir}
-In @sc{cvs} 1.9.18 and older, this specified that
-@sc{rcs} programs are in the @var{bindir} directory.
-Current versions of @sc{cvs} do not run @sc{rcs}
-programs; for compatibility this option is accepted,
-but it does nothing.
-
-@cindex TMPDIR, environment variable
-@cindex temporary file directory, set via command line
-@cindex temporary file directory, set via environment variable
-@cindex temporary file directory, set via config
-@cindex temporary files, location of
-@item -T @var{tempdir}
-Use @var{tempdir} as the directory where temporary files are
-located.
-
-The @sc{cvs} client and server store temporary files in a temporary directory.
-The path to this temporary directory is set via, in order of precedence:
-
-@itemize @bullet
-@item
-The argument to the global @samp{-T} option.
-
-@item
-The value set for @code{TmpDir} in the config file (server only -
-@pxref{config}).
-
-@item
-The contents of the @code{$TMPDIR} environment variable (@code{%TMPDIR%} on
-Windows - @pxref{Environment variables}).
-
-@item
-/tmp
-
-@end itemize
-
-Temporary directories should always be specified as an absolute pathname.
-When running a CVS client, @samp{-T} affects only the local process;
-specifying @samp{-T} for the client has no effect on the server and
-vice versa.
-
-@cindex CVSROOT, overriding
-@cindex Overriding CVSROOT
-@item -d @var{cvs_root_directory}
-Use @var{cvs_root_directory} as the root directory
-pathname of the repository.  Overrides the setting of
-the @code{$CVSROOT} environment variable.  @xref{Repository}.
-
-@cindex EDITOR, overriding
-@cindex Overriding EDITOR
-@item -e @var{editor}
-Use @var{editor} to enter revision log information.  Overrides the
-setting of the @code{$CVSEDITOR} and @code{$EDITOR}
-environment variables.  For more information, see
-@ref{Committing your changes}.
-
-@item -f
-Do not read the @file{~/.cvsrc} file.  This
-option is most often used because of the
-non-orthogonality of the @sc{cvs} option set.  For
-example, the @samp{cvs log} option @samp{-N} (turn off
-display of tag names) does not have a corresponding
-option to turn the display on.  So if you have
-@samp{-N} in the @file{~/.cvsrc} entry for @samp{log},
-you may need to use @samp{-f} to show the tag names.
-
-@item -H
-@itemx --help
-Display usage information about the specified @samp{cvs_command}
-(but do not actually execute the command).  If you don't specify
-a command name, @samp{cvs -H} displays overall help for
-@sc{cvs}, including a list of other help options.
-@c It seems to me it is better to document it this way
-@c rather than trying to update this documentation
-@c every time that we add a --help-foo option.  But
-@c perhaps that is confusing...
-
-@cindex Read-only repository mode
-@item -R
-Turns on read-only repository mode.  This allows one to check out from a
-read-only repository, such as within an anoncvs server, or from a @sc{cd-rom}
-repository.
-
-Same effect as if the @code{CVSREADONLYFS} environment
-variable is set. Using @samp{-R} can also considerably
-speed up checkouts over NFS.
-
-@cindex Read-only mode
-@item -n
-Do not change any files.  Attempt to execute the
-@samp{cvs_command}, but only to issue reports; do not remove,
-update, or merge any existing files, or create any new files.
-
-Note that @sc{cvs} will not necessarily produce exactly
-the same output as without @samp{-n}.  In some cases
-the output will be the same, but in other cases
-@sc{cvs} will skip some of the processing that would
-have been required to produce the exact same output.
-
-@item -Q
-Cause the command to be really quiet; the command will only
-generate output for serious problems.
-
-@item -q
-Cause the command to be somewhat quiet; informational messages,
-such as reports of recursion through subdirectories, are
-suppressed.
-
-@cindex Read-only files, and -r
-@item -r
-Make new working files read-only.  Same effect
-as if the @code{$CVSREAD} environment variable is set
-(@pxref{Environment variables}).  The default is to
-make working files writable, unless watches are on
-(@pxref{Watches}).
-
-@item -s @var{variable}=@var{value}
-Set a user variable (@pxref{Variables}).
-
-@cindex Trace
-@item -t
-Trace program execution; display messages showing the steps of
-@sc{cvs} activity.  Particularly useful with @samp{-n} to explore the
-potential impact of an unfamiliar command.
-
-@item -v
-@item --version
-Display version and copyright information for @sc{cvs}.
-
-@cindex CVSREAD, overriding
-@cindex Overriding CVSREAD
-@item -w
-Make new working files read-write.  Overrides the
-setting of the @code{$CVSREAD} environment variable.
-Files are created read-write by default, unless @code{$CVSREAD} is
-set or @samp{-r} is given.
-@c Note that -w only overrides -r and CVSREAD; it has
-@c no effect on files which are readonly because of
-@c "cvs watch on".  My guess is that is the way it
-@c should be (or should "cvs -w get" on a watched file
-@c be the same as a get and a cvs edit?), but I'm not
-@c completely sure whether to document it this way.
-
-@item -x
-@cindex Encryption
-Encrypt all communication between the client and the
-server.  Only has an effect on the @sc{cvs} client.  As
-of this writing, this is only implemented when using a
-GSSAPI connection (@pxref{GSSAPI authenticated}) or a
-Kerberos connection (@pxref{Kerberos authenticated}).
-Enabling encryption implies that message traffic is
-also authenticated.  Encryption support is not
-available by default; it must be enabled using a
-special configure option, @file{--enable-encryption},
-when you build @sc{cvs}.
-
-@item -z @var{level}
-@cindex Compression
-@cindex Gzip
-Request compression @var{level} for network traffic.
-@sc{cvs} interprets @var{level} identically to the @code{gzip} program.
-Valid levels are 1 (high speed, low compression) to
-9 (low speed, high compression), or 0 to disable
-compression (the default).  Data sent to the server will
-be compressed at the requested level and the client will request
-the server use the same compression level for data returned.  The
-server will use the closest level allowed by the server administrator to
-compress returned data.  This option only has an effect when passed to
-the @sc{cvs} client.
-@end table
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node Common options
-@appendixsec Common command options
-@cindex Common options
-@cindex Right-hand options
-
-This section describes the @samp{command_options} that
-are available across several @sc{cvs} commands.  These
-options are always given to the right of
-@samp{cvs_command}. Not all
-commands support all of these options; each option is
-only supported for commands where it makes sense.
-However, when a command has one of these options you
-can almost always count on the same behavior of the
-option as in other commands.  (Other command options,
-which are listed with the individual commands, may have
-different behavior from one @sc{cvs} command to the other).
-
-@strong{Note: the @samp{history} command is an exception; it supports
-many options that conflict even with these standard options.}
-
-@table @code
-@cindex Dates
-@cindex Time
-@cindex Specifying dates
-@item -D @var{date_spec}
-Use the most recent revision no later than @var{date_spec}.
-@var{date_spec} is a single argument, a date description
-specifying a date in the past.
-
-The specification is @dfn{sticky} when you use it to make a
-private copy of a source file; that is, when you get a working
-file using @samp{-D}, @sc{cvs} records the date you specified, so that
-further updates in the same directory will use the same date
-(for more information on sticky tags/dates, @pxref{Sticky tags}).
-
-@samp{-D} is available with the @code{annotate}, @code{checkout},
-@code{diff}, @code{export}, @code{history}, @code{ls},
-@code{rdiff}, @code{rls}, @code{rtag}, @code{tag}, and @code{update} commands.
-(The @code{history} command uses this option in a
-slightly different way; @pxref{history options}).
-
-For a complete description of the date formats accepted by @sc{cvs},
-@ref{Date input formats}.
-@c What other formats should we accept?  I don't want
-@c to start accepting a whole mess of non-standard
-@c new formats (there are a lot which are in wide use in
-@c one context or another), but practicality does
-@c dictate some level of flexibility.
-@c * POSIX.2 (e.g. touch, ls output, date) and other
-@c POSIX and/or de facto unix standards (e.g. at).  The
-@c practice here is too inconsistent to be of any use.
-@c * VMS dates.  This is not a formal standard, but
-@c there is a published specification (see SYS$ASCTIM
-@c and SYS$BINTIM in the _VMS System Services Reference
-@c Manual_), it is implemented consistently in VMS
-@c utilities, and VMS users will expect CVS running on
-@c VMS to support this format (and if we're going to do
-@c that, better to make CVS support it on all
-@c platforms.  Maybe).
-@c
-@c One more note: In output, CVS should consistently
-@c use one date format, and that format should be one that
-@c it accepts in input as well.  The former isn't
-@c really true (see survey below), and I'm not
-@c sure that either of those formats is accepted in
-@c input.
-@c
-@c cvs log
-@c   current 1996/01/02 13:45:31
-@c   Internet 02 Jan 1996 13:45:31 UT
-@c   ISO 1996-01-02 13:45:31
-@c cvs ann
-@c   current 02-Jan-96
-@c   Internet-like 02 Jan 96
-@c   ISO 96-01-02
-@c cvs status
-@c   current Tue Jun 11 02:54:53 1996
-@c   Internet [Tue,] 11 Jun 1996 02:54:53
-@c   ISO 1996-06-11 02:54:53
-@c   note: date possibly should be omitted entirely for
-@c   other reasons.
-@c cvs editors
-@c   current Tue Jun 11 02:54:53 1996 GMT
-@c cvs history
-@c   current 06/11 02:54 +0000
-@c any others?
-@c There is a good chance the proper solution has to
-@c involve at least some level of letting the user
-@c decide which format (with the default being the
-@c formats CVS has always used; changing these might be
-@c _very_ disruptive since scripts may very well be
-@c parsing them).
-@c
-@c Another random bit of prior art concerning dates is
-@c the strptime function which takes templates such as
-@c "%m/%d/%y", and apparent a variant of getdate()
-@c which also honors them.  See
-@c X/Open CAE Specification, System Interfaces and
-@c Headers Issue 4, Version 2 (September 1994), in the
-@c entry for getdate() on page 231
-
-Remember to quote the argument to the @samp{-D}
-flag so that your shell doesn't interpret spaces as
-argument separators.  A command using the @samp{-D}
-flag can look like this:
-
-@example
-$ cvs diff -D "1 hour ago" cvs.texinfo
-@end example
-
-@cindex Forcing a tag match
-@item -f
-When you specify a particular date or tag to @sc{cvs} commands, they
-normally ignore files that do not contain the tag (or did not
-exist prior to the date) that you specified.  Use the @samp{-f} option
-if you want files retrieved even when there is no match for the
-tag or date.  (The most recent revision of the file
-will be used).
-
-Note that even with @samp{-f}, a tag that you specify
-must exist (that is, in some file, not necessary in
-every file).  This is so that @sc{cvs} will continue to
-give an error if you mistype a tag name.
-
-@need 800
-@samp{-f} is available with these commands:
-@code{annotate}, @code{checkout}, @code{export},
-@code{rdiff}, @code{rtag}, and @code{update}.
-
-@strong{WARNING:  The @code{commit} and @code{remove}
-commands also have a
-@samp{-f} option, but it has a different behavior for
-those commands.  See @ref{commit options}, and
-@ref{Removing files}.}
-
-@item -k @var{kflag}
-Override the default processing of RCS keywords other than
-@samp{-kb}.  @xref{Keyword substitution}, for the meaning of
-@var{kflag}.  Used with the @code{checkout} and @code{update}
-commands, your @var{kflag} specification is
-@dfn{sticky}; that is, when you use this option
-with a @code{checkout} or @code{update} command,
-@sc{cvs} associates your selected @var{kflag} with any files
-it operates on, and continues to use that @var{kflag} with future
-commands on the same files until you specify otherwise.
-
-The @samp{-k} option is available with the @code{add},
-@code{checkout}, @code{diff}, @code{export}, @code{import},
-@code{rdiff}, and @code{update} commands.
-
-@strong{WARNING: Prior to CVS version 1.12.2, the @samp{-k} flag
-overrode the @samp{-kb} indication for a binary file.  This could
-sometimes corrupt binary files.  @xref{Merging and keywords}, for
-more.}
-
-@item -l
-Local; run only in current working directory, rather than
-recursing through subdirectories.
-
-Available with the following commands: @code{annotate}, @code{checkout},
-@code{commit}, @code{diff}, @code{edit}, @code{editors}, @code{export},
-@code{log}, @code{rdiff}, @code{remove}, @code{rtag},
-@code{status}, @code{tag}, @code{unedit}, @code{update}, @code{watch},
-and @code{watchers}.
-
-@cindex Editor, avoiding invocation of
-@cindex Avoiding editor invocation
-@item -m @var{message}
-Use @var{message} as log information, instead of
-invoking an editor.
-
-Available with the following commands: @code{add},
-@code{commit} and @code{import}.
-
-@item -n
-Do not run any tag program.  (A program can be
-specified to run in the modules
-database (@pxref{modules}); this option bypasses it).
-
-@strong{Note: this is not the same as the @samp{cvs -n}
-program option, which you can specify to the left of a cvs command!}
-
-Available with the @code{checkout}, @code{commit}, @code{export},
-and @code{rtag} commands.
-
-@item -P
-Prune empty directories.  See @ref{Removing directories}.
-
-@item -p
-Pipe the files retrieved from the repository to standard output,
-rather than writing them in the current directory.  Available
-with the @code{checkout} and @code{update} commands.
-
-@item -R
-Process directories recursively.  This is the default for all @sc{cvs}
-commands, with the exception of @code{ls} & @code{rls}.
-
-Available with the following commands: @code{annotate}, @code{checkout},
-@code{commit}, @code{diff}, @code{edit}, @code{editors}, @code{export},
-@code{ls}, @code{rdiff}, @code{remove}, @code{rls}, @code{rtag},
-@code{status}, @code{tag}, @code{unedit}, @code{update}, @code{watch},
-and @code{watchers}.
-
-@item -r @var{tag}
-@item -r @var{tag}[:@var{date}]
-@cindex HEAD, special tag
-@cindex BASE, special tag
-Use the revision specified by the @var{tag} argument (and the @var{date}
-argument for the commands which accept it) instead of the
-default @dfn{head} revision.  As well as arbitrary tags defined
-with the @code{tag} or @code{rtag} command, two special tags are
-always available: @samp{HEAD} refers to the most recent version
-available in the repository, and @samp{BASE} refers to the
-revision you last checked out into the current working directory.
-
-@c FIXME: What does HEAD really mean?  I believe that
-@c the current answer is the head of the default branch
-@c for all cvs commands except diff.  For diff, it
-@c seems to be (a) the head of the trunk (or the default
-@c branch?) if there is no sticky tag, (b) the head of the
-@c branch for the sticky tag, if there is a sticky tag.
-@c (b) is ugly as it differs
-@c from what HEAD means for other commands, but people
-@c and/or scripts are quite possibly used to it.
-@c See "head" tests in sanity.sh.
-@c Probably the best fix is to introduce two new
-@c special tags, ".thead" for the head of the trunk,
-@c and ".bhead" for the head of the current branch.
-@c Then deprecate HEAD.  This has the advantage of
-@c not surprising people with a change to HEAD, and a
-@c side benefit of also phasing out the poorly-named
-@c HEAD (see discussion of reserved tag names in node
-@c "Tags").  Of course, .thead and .bhead should be
-@c carefully implemented (with the implementation the
-@c same for "diff" as for everyone else), test cases
-@c written (similar to the ones in "head"), new tests
-@c cases written for things like default branches, &c.
-
-The tag specification is sticky when you use this
-with @code{checkout} or @code{update} to make your own
-copy of a file: @sc{cvs} remembers the tag and continues to use it on
-future update commands, until you specify otherwise (for more information
-on sticky tags/dates, @pxref{Sticky tags}).
-
-The tag can be either a symbolic or numeric tag, as
-described in @ref{Tags}, or the name of a branch, as
-described in @ref{Branching and merging}.
-When @var{tag} is the name of a
-branch, some commands accept the optional @var{date} argument to specify
-the revision as of the given date on the branch.
-When a command expects a specific revision,
-the name of a branch is interpreted as the most recent
-revision on that branch.
-
-Specifying the @samp{-q} global option along with the
-@samp{-r} command option is often useful, to suppress
-the warning messages when the @sc{rcs} file
-does not contain the specified tag.
-
-@strong{Note: this is not the same as the overall @samp{cvs -r} option,
-which you can specify to the left of a @sc{cvs} command!}
-
-@samp{-r @var{tag}} is available with the @code{commit} and @code{history}
-commands.
-
-@samp{-r @var{tag}[:@var{date}]} is available with the @code{annotate},
-@code{checkout}, @code{diff}, @code{export}, @code{rdiff}, @code{rtag},
-and @code{update} commands.
-
-@item -W
-Specify file names that should be filtered.  You can
-use this option repeatedly.  The spec can be a file
-name pattern of the same type that you can specify in
-the @file{.cvswrappers} file.
-Available with the following commands: @code{import},
-and @code{update}.
-
-@end table
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@include getdate-cvs.texi
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node admin
-@appendixsec admin---Administration
-@cindex Admin (subcommand)
-
-@itemize @bullet
-@item
-Requires: repository, working directory.
-@item
-Changes: repository.
-@item
-Synonym: rcs
-@end itemize
-
-This is the @sc{cvs} interface to assorted
-administrative facilities.  Some of them have
-questionable usefulness for @sc{cvs} but exist for
-historical purposes.  Some of the questionable options
-are likely to disappear in the future.  This command
-@emph{does} work recursively, so extreme care should be
-used.
-
-@cindex cvsadmin
-@cindex UserAdminOptions, in CVSROOT/config
-On unix, if there is a group named @code{cvsadmin},
-only members of that group can run @code{cvs admin}
-commands, except for those specified using the
-@code{UserAdminOptions} configuration option in the
-@file{CVSROOT/config} file.  Options specified using
-@code{UserAdminOptions} can be run by any user.  See
-@ref{config} for more on @code{UserAdminOptions}.
-
-The @code{cvsadmin} group should exist on the server,
-or any system running the non-client/server @sc{cvs}.
-To disallow @code{cvs admin} for all users, create a
-group with no users in it.  On NT, the @code{cvsadmin}
-feature does not exist and all users
-can run @code{cvs admin}.
-
-@menu
-* admin options::               admin options
-@end menu
-
-@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
-@node admin options
-@appendixsubsec admin options
-
-Some of these options have questionable usefulness for
-@sc{cvs} but exist for historical purposes.  Some even
-make it impossible to use @sc{cvs} until you undo the
-effect!
-
-@table @code
-@item -A@var{oldfile}
-Might not work together with @sc{cvs}.  Append the
-access list of @var{oldfile} to the access list of the
-@sc{rcs} file.
-
-@item -a@var{logins}
-Might not work together with @sc{cvs}.  Append the
-login names appearing in the comma-separated list
-@var{logins} to the access list of the @sc{rcs} file.
-
-@item -b[@var{rev}]
-Set the default branch to @var{rev}.  In @sc{cvs}, you
-normally do not manipulate default branches; sticky
-tags (@pxref{Sticky tags}) are a better way to decide
-which branch you want to work on.  There is one reason
-to run @code{cvs admin -b}: to revert to the vendor's
-version when using vendor branches (@pxref{Reverting
-local changes}).
-There can be no space between @samp{-b} and its argument.
-@c Hmm, we don't document the usage where rev is
-@c omitted.  Maybe that usage can/should be deprecated
-@c (and replaced with -bHEAD or something?) (so we can toss
-@c the optional argument).  Note that -bHEAD does not
-@c work, as of 17 Sep 1997, but probably will once "cvs
-@c admin" is internal to CVS.
-
-@cindex Comment leader
-@item -c@var{string}
-Sets the comment leader to @var{string}.  The comment
-leader is not used by current versions of @sc{cvs} or
-@sc{rcs} 5.7.  Therefore, you can almost surely not
-worry about it.  @xref{Keyword substitution}.
-
-@item -e[@var{logins}]
-Might not work together with @sc{cvs}.  Erase the login
-names appearing in the comma-separated list
-@var{logins} from the access list of the RCS file.  If
-@var{logins} is omitted, erase the entire access list.
-There can be no space between @samp{-e} and its argument.
-
-@item -I
-Run interactively, even if the standard input is not a
-terminal.  This option does not work with the
-client/server @sc{cvs} and is likely to disappear in
-a future release of @sc{cvs}.
-
-@item -i
-Useless with @sc{cvs}.  This creates and initializes a
-new @sc{rcs} file, without depositing a revision.  With
-@sc{cvs}, add files with the @code{cvs add} command
-(@pxref{Adding files}).
-
-@item -k@var{subst}
-Set the default keyword
-substitution to @var{subst}.  @xref{Keyword
-substitution}.  Giving an explicit @samp{-k} option to
-@code{cvs update}, @code{cvs export}, or @code{cvs
-checkout} overrides this default.
-
-@item -l[@var{rev}]
-Lock the revision with number @var{rev}.  If a branch
-is given, lock the latest revision on that branch.  If
-@var{rev} is omitted, lock the latest revision on the
-default branch.  There can be no space between
-@samp{-l} and its argument.
-
-This can be used in conjunction with the
-@file{rcslock.pl} script in the @file{contrib}
-directory of the @sc{cvs} source distribution to
-provide reserved checkouts (where only one user can be
-editing a given file at a time).  See the comments in
-that file for details (and see the @file{README} file
-in that directory for disclaimers about the unsupported
-nature of contrib).  According to comments in that
-file, locking must set to strict (which is the default).
-
-@item -L
-Set locking to strict.  Strict locking means that the
-owner of an RCS file is not exempt from locking for
-checkin.  For use with @sc{cvs}, strict locking must be
-set; see the discussion under the @samp{-l} option above.
-
-@cindex Changing a log message
-@cindex Replacing a log message
-@cindex Correcting a log message
-@cindex Fixing a log message
-@cindex Log message, correcting
-@item -m@var{rev}:@var{msg}
-Replace the log message of revision @var{rev} with
-@var{msg}.
-
-@c The rcs -M option, to suppress sending mail, has never been
-@c documented as a cvs admin option.
-
-@item -N@var{name}[:[@var{rev}]]
-Act like @samp{-n}, except override any previous
-assignment of @var{name}.  For use with magic branches,
-see @ref{Magic branch numbers}.
-
-@item -n@var{name}[:[@var{rev}]]
-Associate the symbolic name @var{name} with the branch
-or revision @var{rev}.  It is normally better to use
-@samp{cvs tag} or @samp{cvs rtag} instead.  Delete the
-symbolic name if both @samp{:} and @var{rev} are
-omitted; otherwise, print an error message if
-@var{name} is already associated with another number.
-If @var{rev} is symbolic, it is expanded before
-association.  A @var{rev} consisting of a branch number
-followed by a @samp{.} stands for the current latest
-revision in the branch.  A @samp{:} with an empty
-@var{rev} stands for the current latest revision on the
-default branch, normally the trunk.  For example,
-@samp{cvs admin -n@var{name}:} associates @var{name} with the
-current latest revision of all the RCS files;
-this contrasts with @samp{cvs admin -n@var{name}:$} which
-associates @var{name} with the revision numbers
-extracted from keyword strings in the corresponding
-working files.
-
-@cindex Deleting revisions
-@cindex Outdating revisions
-@cindex Saving space
-@item -o@var{range}
-Deletes (@dfn{outdates}) the revisions given by
-@var{range}.
-
-Note that this command can be quite dangerous unless
-you know @emph{exactly} what you are doing (for example
-see the warnings below about how the
-@var{rev1}:@var{rev2} syntax is confusing).
-
-If you are short on disc this option might help you.
-But think twice before using it---there is no way short
-of restoring the latest backup to undo this command!
-If you delete different revisions than you planned,
-either due to carelessness or (heaven forbid) a @sc{cvs}
-bug, there is no opportunity to correct the error
-before the revisions are deleted.  It probably would be
-a good idea to experiment on a copy of the repository
-first.
-
-Specify @var{range} in one of the following ways:
-
-@table @code
-@item @var{rev1}::@var{rev2}
-Collapse all revisions between rev1 and rev2, so that
-@sc{cvs} only stores the differences associated with going
-from rev1 to rev2, not intermediate steps.  For
-example, after @samp{-o 1.3::1.5} one can retrieve
-revision 1.3, revision 1.5, or the differences to get
-from 1.3 to 1.5, but not the revision 1.4, or the
-differences between 1.3 and 1.4.  Other examples:
-@samp{-o 1.3::1.4} and @samp{-o 1.3::1.3} have no
-effect, because there are no intermediate revisions to
-remove.
-
-@item ::@var{rev}
-Collapse revisions between the beginning of the branch
-containing @var{rev} and @var{rev} itself.  The
-branchpoint and @var{rev} are left intact.  For
-example, @samp{-o ::1.3.2.6} deletes revision 1.3.2.1,
-revision 1.3.2.5, and everything in between, but leaves
-1.3 and 1.3.2.6 intact.
-
-@item @var{rev}::
-Collapse revisions between @var{rev} and the end of the
-branch containing @var{rev}.  Revision @var{rev} is
-left intact but the head revision is deleted.
-
-@item @var{rev}
-Delete the revision @var{rev}.  For example, @samp{-o
-1.3} is equivalent to @samp{-o 1.2::1.4}.
-
-@item @var{rev1}:@var{rev2}
-Delete the revisions from @var{rev1} to @var{rev2},
-inclusive, on the same branch.  One will not be able to
-retrieve @var{rev1} or @var{rev2} or any of the
-revisions in between.  For example, the command
-@samp{cvs admin -oR_1_01:R_1_02 .} is rarely useful.
-It means to delete revisions up to, and including, the
-tag R_1_02.  But beware!  If there are files that have not
-changed between R_1_02 and R_1_03 the file will have
-@emph{the same} numerical revision number assigned to
-the tags R_1_02 and R_1_03.  So not only will it be
-impossible to retrieve R_1_02; R_1_03 will also have to
-be restored from the tapes!  In most cases you want to
-specify @var{rev1}::@var{rev2} instead.
-
-@item :@var{rev}
-Delete revisions from the beginning of the
-branch containing @var{rev} up to and including
-@var{rev}.
-
-@item @var{rev}:
-Delete revisions from revision @var{rev}, including
-@var{rev} itself, to the end of the branch containing
-@var{rev}.
-@end table
-
-None of the revisions to be deleted may have
-branches or locks.
-
-If any of the revisions to be deleted have symbolic
-names, and one specifies one of the @samp{::} syntaxes,
-then @sc{cvs} will give an error and not delete any
-revisions.  If you really want to delete both the
-symbolic names and the revisions, first delete the
-symbolic names with @code{cvs tag -d}, then run
-@code{cvs admin -o}.  If one specifies the
-non-@samp{::} syntaxes, then @sc{cvs} will delete the
-revisions but leave the symbolic names pointing to
-nonexistent revisions.  This behavior is preserved for
-compatibility with previous versions of @sc{cvs}, but
-because it isn't very useful, in the future it may
-change to be like the @samp{::} case.
-
-Due to the way @sc{cvs} handles branches @var{rev}
-cannot be specified symbolically if it is a branch.
-@xref{Magic branch numbers}, for an explanation.
-@c FIXME: is this still true?  I suspect not.
-
-Make sure that no-one has checked out a copy of the
-revision you outdate.  Strange things will happen if he
-starts to edit it and tries to check it back in.  For
-this reason, this option is not a good way to take back
-a bogus commit; commit a new revision undoing the bogus
-change instead (@pxref{Merging two revisions}).
-
-@item -q
-Run quietly; do not print diagnostics.
-
-@item -s@var{state}[:@var{rev}]
-Useful with @sc{cvs}.  Set the state attribute of the
-revision @var{rev} to @var{state}.  If @var{rev} is a
-branch number, assume the latest revision on that
-branch.  If @var{rev} is omitted, assume the latest
-revision on the default branch.  Any identifier is
-acceptable for @var{state}.  A useful set of states is
-@samp{Exp} (for experimental), @samp{Stab} (for
-stable), and @samp{Rel} (for released).  By default,
-the state of a new revision is set to @samp{Exp} when
-it is created.  The state is visible in the output from
-@var{cvs log} (@pxref{log}), and in the
-@samp{$@splitrcskeyword{Log}$} and @samp{$@splitrcskeyword{State}$} keywords
-(@pxref{Keyword substitution}).  Note that @sc{cvs}
-uses the @code{dead} state for its own purposes (@pxref{Attic}); to
-take a file to or from the @code{dead} state use
-commands like @code{cvs remove} and @code{cvs add}
-(@pxref{Adding and removing}), not @code{cvs admin -s}.
-
-@item -t[@var{file}]
-Useful with @sc{cvs}.  Write descriptive text from the
-contents of the named @var{file} into the RCS file,
-deleting the existing text.  The @var{file} pathname
-may not begin with @samp{-}.  The descriptive text can be seen in the
-output from @samp{cvs log} (@pxref{log}).
-There can be no space between @samp{-t} and its argument.
-
-If @var{file} is omitted,
-obtain the text from standard input, terminated by
-end-of-file or by a line containing @samp{.} by itself.
-Prompt for the text if interaction is possible; see
-@samp{-I}.
-
-@item -t-@var{string}
-Similar to @samp{-t@var{file}}. Write descriptive text
-from the @var{string} into the @sc{rcs} file, deleting
-the existing text.
-There can be no space between @samp{-t} and its argument.
-
-@c The rcs -T option, do not update last-mod time for
-@c minor changes, has never been documented as a
-@c cvs admin option.
-
-@item -U
-Set locking to non-strict.  Non-strict locking means
-that the owner of a file need not lock a revision for
-checkin.  For use with @sc{cvs}, strict locking must be
-set; see the discussion under the @samp{-l} option
-above.
-
-@item -u[@var{rev}]
-See the option @samp{-l} above, for a discussion of
-using this option with @sc{cvs}.  Unlock the revision
-with number @var{rev}.  If a branch is given, unlock
-the latest revision on that branch.  If @var{rev} is
-omitted, remove the latest lock held by the caller.
-Normally, only the locker of a revision may unlock it;
-somebody else unlocking a revision breaks the lock.
-This causes the original locker to be sent a @code{commit}
-notification (@pxref{Getting Notified}).
-There can be no space between @samp{-u} and its argument.
-
-@item -V@var{n}
-In previous versions of @sc{cvs}, this option meant to
-write an @sc{rcs} file which would be acceptable to
-@sc{rcs} version @var{n}, but it is now obsolete and
-specifying it will produce an error.
-@c Note that -V without an argument has never been
-@c documented as a cvs admin option.
-
-@item -x@var{suffixes}
-In previous versions of @sc{cvs}, this was documented
-as a way of specifying the names of the @sc{rcs}
-files.  However, @sc{cvs} has always required that the
-@sc{rcs} files used by @sc{cvs} end in @samp{,v}, so
-this option has never done anything useful.
-
-@c The rcs -z option, to specify the timezone, has
-@c never been documented as a cvs admin option.
-@end table
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node annotate
-@appendixsec annotate---What revision modified each line of a file?
-@cindex annotate (subcommand)
-
-@itemize @bullet
-@item
-Synopsis: annotate [options] files@dots{}
-@item
-Requires: repository.
-@item
-Changes: nothing.
-@end itemize
-
-For each file in @var{files}, print the head revision
-of the trunk, together with information on the last
-modification for each line.  If @samp{-b} is specified,
-the first modification after the revision selected by
-@samp{-r} is shown.  
-
-@menu
-* annotate options::            annotate options
-* annotate example::            annotate example
-@end menu
-
-@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
-@node annotate options
-@appendixsubsec annotate options
-
-These standard options are supported by @code{annotate}
-(@pxref{Common options}, for a complete description of
-them):
-
-@table @code
-@item -b
-Backwards, show when a line was removed.
-
-@item -l
-Local directory only, no recursion.
-
-@item -R
-Process directories recursively.
-
-@item -f
-Use head revision if tag/date not found.
-
-@item -F
-Annotate binary files.
-
-@item -r @var{tag}[:@var{date}]
-Annotate file as of specified revision/tag or, when @var{date} is specified
-and @var{tag} is a branch tag, the version from the branch @var{tag} as it
-existed on @var{date}.  See @ref{Common options}.
-
-@item -D @var{date}
-Annotate file as of specified date.
-@end table
-
-@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
-@node annotate example
-@appendixsubsec annotate example
-
-For example:
-
-@example
-$ cvs annotate ssfile
-Annotations for ssfile
-***************
-1.1          (mary     27-Mar-96): ssfile line 1
-1.2          (joe      28-Mar-96): ssfile line 2
-@end example
-
-The file @file{ssfile} currently contains two lines.
-The @code{ssfile line 1} line was checked in by
-@code{mary} on March 27.  Then, on March 28, @code{joe}
-added a line @code{ssfile line 2}, without modifying
-the @code{ssfile line 1} line.  This report doesn't
-tell you anything about lines which have been deleted
-or replaced; you need to use @code{cvs diff} for that
-(@pxref{diff}).
-
-The options to @code{cvs annotate} are listed in
-@ref{Invoking CVS}, and can be used to select the files
-and revisions to annotate.  The options are described
-in more detail there and in @ref{Common options}.
-
-@c FIXME: maybe an example using the options?  Just
-@c what it means to select a revision might be worth a
-@c few words of explanation ("you want to see who
-@c changed this line *before* 1.4"...).
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node checkout
-@appendixsec checkout---Check out sources for editing
-@cindex checkout (subcommand)
-@cindex co (subcommand)
-
-@itemize @bullet
-@item
-Synopsis: checkout [options] modules@dots{}
-@item
-Requires: repository.
-@item
-Changes: working directory.
-@item
-Synonyms: co, get
-@end itemize
-
-Create or update a working directory containing copies of the
-source files specified by @var{modules}.  You must execute
-@code{checkout} before using most of the other @sc{cvs}
-commands, since most of them operate on your working
-directory.
-
-The @var{modules} are either
-symbolic names for some
-collection of source directories and files, or paths to
-directories or files in the repository.  The symbolic
-names are defined in the @samp{modules} file.
-@xref{modules}.
-@c Needs an example, particularly of the non-"modules"
-@c case but probably of both.
-
-@c FIXME: this seems like a very odd place to introduce
-@c people to how CVS works.  The bit about unreserved
-@c checkouts is also misleading as it depends on how
-@c things are set up.
-Depending on the modules you specify, @code{checkout} may
-recursively create directories and populate them with
-the appropriate source files.  You can then edit these
-source files at any time (regardless of whether other
-software developers are editing their own copies of the
-sources); update them to include new changes applied by
-others to the source repository; or commit your work as
-a permanent change to the source repository.
-
-Note that @code{checkout} is used to create
-directories.  The top-level directory created is always
-added to the directory where @code{checkout} is
-invoked, and usually has the same name as the specified
-module.  In the case of a module alias, the created
-sub-directory may have a different name, but you can be
-sure that it will be a sub-directory, and that
-@code{checkout} will show the relative path leading to
-each file as it is extracted into your private work
-area (unless you specify the @samp{-Q} global option).
-
-The files created by @code{checkout} are created
-read-write, unless the @samp{-r} option to @sc{cvs}
-(@pxref{Global options}) is specified, the
-@code{CVSREAD} environment variable is specified
-(@pxref{Environment variables}), or a watch is in
-effect for that file (@pxref{Watches}).
-
-Note that running @code{checkout} on a directory that was already
-built by a prior @code{checkout} is also permitted.
-This is similar to specifying the @samp{-d} option
-to the @code{update} command in the sense that new
-directories that have been created in the repository
-will appear in your work area.
-However, @code{checkout} takes a module name whereas
-@code{update} takes a directory name.  Also
-to use @code{checkout} this way it must be run from the
-top level directory (where you originally ran
-@code{checkout} from), so before you run
-@code{checkout} to update an existing directory, don't
-forget to change your directory to the top level
-directory.
-
-For the output produced by the @code{checkout} command
-see @ref{update output}.
-
-@menu
-* checkout options::            checkout options
-* checkout examples::           checkout examples
-@end menu
-
-@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
-@node checkout options
-@appendixsubsec checkout options
-
-These standard options are supported by @code{checkout}
-(@pxref{Common options}, for a complete description of
-them):
-
-@table @code
-@item -D @var{date}
-Use the most recent revision no later than @var{date}.
-This option is sticky, and implies @samp{-P}.  See
-@ref{Sticky tags}, for more information on sticky tags/dates.
-
-@item -f
-Only useful with the @samp{-D} or @samp{-r} flags.  If no matching revision is
-found, retrieve the most recent revision (instead of ignoring the file).
-
-@item -k @var{kflag}
-Process keywords according to @var{kflag}.  See
-@ref{Keyword substitution}.
-This option is sticky; future updates of
-this file in this working directory will use the same
-@var{kflag}.  The @code{status} command can be viewed
-to see the sticky options.  See @ref{Invoking CVS}, for
-more information on the @code{status} command.
-
-@item -l
-Local; run only in current working directory.
-
-@item -n
-Do not run any checkout program (as specified
-with the @samp{-o} option in the modules file;
-@pxref{modules}).
-
-@item -P
-Prune empty directories.  See @ref{Moving directories}.
-
-@item -p
-Pipe files to the standard output.
-
-@item -R
-Checkout directories recursively.  This option is on by default.
-
-@item -r @var{tag}[:@var{date}]
-Checkout the revision specified by @var{tag} or, when @var{date} is specified
-and @var{tag} is a branch tag, the version from the branch @var{tag} as it
-existed on @var{date}.  This option is sticky, and implies @samp{-P}.
-See @ref{Sticky tags}, for more information on sticky tags/dates.  Also,
-see @ref{Common options}.
-@end table
-
-In addition to those, you can use these special command
-options with @code{checkout}:
-
-@table @code
-@item -A
-Reset any sticky tags, dates, or @samp{-k} options.
-See @ref{Sticky tags}, for more information on sticky tags/dates.
-
-@item -c
-Copy the module file, sorted, to the standard output,
-instead of creating or modifying any files or
-directories in your working directory.
-
-@item -d @var{dir}
-Create a directory called @var{dir} for the working
-files, instead of using the module name.  In general,
-using this flag is equivalent to using @samp{mkdir
-@var{dir}; cd @var{dir}} followed by the checkout
-command without the @samp{-d} flag.
-
-There is an important exception, however.  It is very
-convenient when checking out a single item to have the
-output appear in a directory that doesn't contain empty
-intermediate directories.  In this case @emph{only},
-@sc{cvs} tries to ``shorten'' pathnames to avoid those empty
-directories.
-
-For example, given a module @samp{foo} that contains
-the file @samp{bar.c}, the command @samp{cvs co -d dir
-foo} will create directory @samp{dir} and place
-@samp{bar.c} inside.  Similarly, given a module
-@samp{bar} which has subdirectory @samp{baz} wherein
-there is a file @samp{quux.c}, the command @samp{cvs co
--d dir bar/baz} will create directory @samp{dir} and
-place @samp{quux.c} inside.
-
-Using the @samp{-N} flag will defeat this behavior.
-Given the same module definitions above, @samp{cvs co
--N -d dir foo} will create directories @samp{dir/foo}
-and place @samp{bar.c} inside, while @samp{cvs co -N -d
-dir bar/baz} will create directories @samp{dir/bar/baz}
-and place @samp{quux.c} inside.
-
-@item -j @var{tag}
-With two @samp{-j} options, merge changes from the
-revision specified with the first @samp{-j} option to
-the revision specified with the second @samp{j} option,
-into the working directory.
-
-With one @samp{-j} option, merge changes from the
-ancestor revision to the revision specified with the
-@samp{-j} option, into the working directory.  The
-ancestor revision is the common ancestor of the
-revision which the working directory is based on, and
-the revision specified in the @samp{-j} option.
-
-In addition, each -j option can contain an optional
-date specification which, when used with branches, can
-limit the chosen revision to one within a specific
-date.  An optional date is specified by adding a colon
-(:) to the tag:
-@samp{-j@var{Symbolic_Tag}:@var{Date_Specifier}}.
-
-@xref{Branching and merging}.
-
-@item -N
-Only useful together with @samp{-d @var{dir}}.  With
-this option, @sc{cvs} will not ``shorten'' module paths
-in your working directory when you check out a single
-module.  See the @samp{-d} flag for examples and a
-discussion.
-
-@item -s
-Like @samp{-c}, but include the status of all modules,
-and sort it by the status string.  @xref{modules}, for
-info about the @samp{-s} option that is used inside the
-modules file to set the module status.
-@end table
-
-@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
-@node checkout examples
-@appendixsubsec checkout examples
-
-Get a copy of the module @samp{tc}:
-
-@example
-$ cvs checkout tc
-@end example
-
-Get a copy of the module @samp{tc} as it looked one day
-ago:
-
-@example
-$ cvs checkout -D yesterday tc
-@end example
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node commit
-@appendixsec commit---Check files into the repository
-@cindex commit (subcommand)
-
-@itemize @bullet
-@item
-Synopsis: commit [-lnRf] [-m 'log_message' |
--F file] [-r revision] [files@dots{}]
-@item
-Requires: working directory, repository.
-@item
-Changes: repository.
-@item
-Synonym: ci
-@end itemize
-
-Use @code{commit} when you want to incorporate changes
-from your working source files into the source
-repository.
-
-If you don't specify particular files to commit, all of
-the files in your working current directory are
-examined.  @code{commit} is careful to change in the
-repository only those files that you have really
-changed.  By default (or if you explicitly specify the
-@samp{-R} option), files in subdirectories are also
-examined and committed if they have changed; you can
-use the @samp{-l} option to limit @code{commit} to the
-current directory only.
-
-@code{commit} verifies that the selected files are up
-to date with the current revisions in the source
-repository; it will notify you, and exit without
-committing, if any of the specified files must be made
-current first with @code{update} (@pxref{update}).
-@code{commit} does not call the @code{update} command
-for you, but rather leaves that for you to do when the
-time is right.
-
-When all is well, an editor is invoked to allow you to
-enter a log message that will be written to one or more
-logging programs (@pxref{modules}, and @pxref{loginfo})
-and placed in the @sc{rcs} file inside the
-repository.  This log message can be retrieved with the
-@code{log} command; see @ref{log}.  You can specify the
-log message on the command line with the @samp{-m
-@var{message}} option, and thus avoid the editor invocation,
-or use the @samp{-F @var{file}} option to specify
-that the argument file contains the log message.
-
-At @code{commit}, a unique commitid is placed in the @sc{rcs}
-file inside the repository. All files committed at once
-get the same commitid. The commitid can be retrieved with
-the @code{log} and @code{status} command; see @ref{log},
-@ref{File status}.
-
-@menu
-* commit options::              commit options
-* commit examples::             commit examples
-@end menu
-
-@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
-@node commit options
-@appendixsubsec commit options
-
-These standard options are supported by @code{commit}
-(@pxref{Common options}, for a complete description of
-them):
-
-@table @code
-@item -l
-Local; run only in current working directory.
-
-@item -R
-Commit directories recursively.  This is on by default.
-
-@item -r @var{revision}
-Commit to @var{revision}.  @var{revision} must be
-either a branch, or a revision on the main trunk that
-is higher than any existing revision number
-(@pxref{Assigning revisions}).  You
-cannot commit to a specific revision on a branch.
-@c FIXME: Need xref for branch case.
-@end table
-
-@code{commit} also supports these options:
-
-@table @code
-@item -c
-Refuse to commit files unless the user has registered a valid edit on the
-file via @code{cvs edit}.  This is most useful when @samp{commit -c}
-and @samp{edit -c} have been placed in all @file{.cvsrc} files.
-A commit can be forced anyways by either regestering an edit retroactively
-via @code{cvs edit} (no changes to the file will be lost) or using the
-@code{-f} option to commit.  Support for @code{commit -c} requires both
-client and a server versions 1.12.10 or greater.
-
-@item -F @var{file}
-Read the log message from @var{file}, instead
-of invoking an editor.
-
-@item -f
-Note that this is not the standard behavior of
-the @samp{-f} option as defined in @ref{Common options}.
-
-Force @sc{cvs} to commit a new revision even if you haven't
-made any changes to the file.  As of @sc{cvs} version 1.12.10,
-it also causes the @code{-c} option to be ignored.  If the current revision
-of @var{file} is 1.7, then the following two commands
-are equivalent:
-
-@example
-$ cvs commit -f @var{file}
-$ cvs commit -r 1.8 @var{file}
-@end example
-
-@c This is odd, but it's how CVS has worked for some
-@c time.
-The @samp{-f} option disables recursion (i.e., it
-implies @samp{-l}).  To force @sc{cvs} to commit a new
-revision for all files in all subdirectories, you must
-use @samp{-f -R}.
-
-@item -m @var{message}
-Use @var{message} as the log message, instead of
-invoking an editor.
-@end table
-
-@need 2000
-@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
-@node commit examples
-@appendixsubsec commit examples
-
-@c FIXME: this material wants to be somewhere
-@c in "Branching and merging".
-
-@appendixsubsubsec Committing to a branch
-
-You can commit to a branch revision (one that has an
-even number of dots) with the @samp{-r} option.  To
-create a branch revision, use the @samp{-b} option
-of the @code{rtag} or @code{tag} commands
-(@pxref{Branching and merging}).  Then, either @code{checkout} or
-@code{update} can be used to base your sources on the
-newly created branch.  From that point on, all
-@code{commit} changes made within these working sources
-will be automatically added to a branch revision,
-thereby not disturbing main-line development in any
-way.  For example, if you had to create a patch to the
-1.2 version of the product, even though the 2.0 version
-is already under development, you might do:
-
-@example
-$ cvs rtag -b -r FCS1_2 FCS1_2_Patch product_module
-$ cvs checkout -r FCS1_2_Patch product_module
-$ cd product_module
-[[ hack away ]]
-$ cvs commit
-@end example
-
-@noindent
-This works automatically since the @samp{-r} option is
-sticky.
-
-@appendixsubsubsec Creating the branch after editing
-
-Say you have been working on some extremely
-experimental software, based on whatever revision you
-happened to checkout last week.  If others in your
-group would like to work on this software with you, but
-without disturbing main-line development, you could
-commit your change to a new branch.  Others can then
-checkout your experimental stuff and utilize the full
-benefit of @sc{cvs} conflict resolution.  The scenario might
-look like:
-
-@c FIXME: Should we be recommending tagging the branchpoint?
-@example
-[[ hacked sources are present ]]
-$ cvs tag -b EXPR1
-$ cvs update -r EXPR1
-$ cvs commit
-@end example
-
-The @code{update} command will make the @samp{-r
-EXPR1} option sticky on all files.  Note that your
-changes to the files will never be removed by the
-@code{update} command.  The @code{commit} will
-automatically commit to the correct branch, because the
-@samp{-r} is sticky.  You could also do like this:
-
-@c FIXME: Should we be recommending tagging the branchpoint?
-@example
-[[ hacked sources are present ]]
-$ cvs tag -b EXPR1
-$ cvs commit -r EXPR1
-@end example
-
-@noindent
-but then, only those files that were changed by you
-will have the @samp{-r EXPR1} sticky flag.  If you hack
-away, and commit without specifying the @samp{-r EXPR1}
-flag, some files may accidentally end up on the main
-trunk.
-
-To work with you on the experimental change, others
-would simply do
-
-@example
-$ cvs checkout -r EXPR1 whatever_module
-@end example
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node diff
-@appendixsec diff---Show differences between revisions
-@cindex diff (subcommand)
-
-@itemize @bullet
-@item
-Synopsis: diff [-lR] [-k kflag] [format_options] [(-r rev1[:date1] | -D date1) [-r rev2[:date2] | -D date2]] [files@dots{}]
-@item
-Requires: working directory, repository.
-@item
-Changes: nothing.
-@end itemize
-
-The @code{diff} command is used to compare different
-revisions of files.  The default action is to compare
-your working files with the revisions they were based
-on, and report any differences that are found.
-
-If any file names are given, only those files are
-compared.  If any directories are given, all files
-under them will be compared.
-
-The exit status for diff is different than for other
-@sc{cvs} commands; for details @ref{Exit status}.
-
-@menu
-* diff options::                diff options
-* diff examples::               diff examples
-@end menu
-
-@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
-@node diff options
-@appendixsubsec diff options
-
-These standard options are supported by @code{diff}
-(@pxref{Common options}, for a complete description of
-them):
-
-@table @code
-@item -D @var{date}
-Use the most recent revision no later than @var{date}.
-See @samp{-r} for how this affects the comparison.
-
-@item -k @var{kflag}
-Process keywords according to @var{kflag}.  See
-@ref{Keyword substitution}.
-
-@item -l
-Local; run only in current working directory.
-
-@item -R
-Examine directories recursively.  This option is on by
-default.
-
-@item -r @var{tag}[:@var{date}]
-Compare with revision specified by @var{tag} or, when @var{date} is specified
-and @var{tag} is a branch tag, the version from the branch @var{tag} as it
-existed on @var{date}.  Zero, one or two
-@samp{-r} options can be present.  With no @samp{-r}
-option, the working file will be compared with the
-revision it was based on.  With one @samp{-r}, that
-revision will be compared to your current working file.
-With two @samp{-r} options those two revisions will be
-compared (and your working file will not affect the
-outcome in any way).
-@c We should be a lot more explicit, with examples,
-@c about the difference between "cvs diff" and "cvs
-@c diff -r HEAD".  This often confuses new users.
-
-One or both @samp{-r} options can be replaced by a
-@samp{-D @var{date}} option, described above.
-@end table
-
-@c Conceptually, this is a disaster.  There are 3
-@c zillion diff formats that we support via the diff
-@c library.  It is not obvious to me that we should
-@c document them all.  Maybe just the most common ones
-@c like -c and -u, and think about phasing out the
-@c obscure ones.
-@c FIXCVS: also should be a way to specify an external
-@c diff program (which can be different for different
-@c file types) and pass through
-@c arbitrary options, so that the user can do
-@c "--pass=-Z --pass=foo" or something even if CVS
-@c doesn't know about the "-Z foo" option to diff.
-@c This would fit nicely with deprecating/eliminating
-@c the obscure options of the diff library, because it
-@c would let people specify an external GNU diff if
-@c they are into that sort of thing.
-The following options specify the format of the
-output.  They have the same meaning as in GNU diff.
-Most options have two equivalent names, one of which is a single letter
-preceded by @samp{-}, and the other of which is a long name preceded by
-@samp{--}.
-
-@table @samp
-@item -@var{lines}
-Show @var{lines} (an integer) lines of context.  This option does not
-specify an output format by itself; it has no effect unless it is
-combined with @samp{-c} or @samp{-u}.  This option is obsolete.  For proper
-operation, @code{patch} typically needs at least two lines of context.
-
-@item -a
-Treat all files as text and compare them line-by-line, even if they
-do not seem to be text.
-
-@item -b
-Ignore trailing white space and consider all other sequences of one or
-more white space characters to be equivalent.
-
-@item -B
-Ignore changes that just insert or delete blank lines.
-
-@item --binary
-Read and write data in binary mode.
-
-@item --brief
-Report only whether the files differ, not the details of the
-differences.
-
-@item -c
-Use the context output format.
-
-@item -C @var{lines}
-@itemx --context@r{[}=@var{lines}@r{]}
-Use the context output format, showing @var{lines} (an integer) lines of
-context, or three if @var{lines} is not given.
-For proper operation, @code{patch} typically needs at least two lines of
-context.
-
-@item --changed-group-format=@var{format}
-Use @var{format} to output a line group containing differing lines from
-both files in if-then-else format.  @xref{Line group formats}.
-
-@item -d
-Change the algorithm to perhaps find a smaller set of changes.  This makes
-@code{diff} slower (sometimes much slower).
-
-@item -e
-@itemx --ed
-Make output that is a valid @code{ed} script.
-
-@item --expand-tabs
-Expand tabs to spaces in the output, to preserve the alignment of tabs
-in the input files.
-
-@item -f
-Make output that looks vaguely like an @code{ed} script but has changes
-in the order they appear in the file.
-
-@item -F @var{regexp}
-In context and unified format, for each hunk of differences, show some
-of the last preceding line that matches @var{regexp}.
-
-@item --forward-ed
-Make output that looks vaguely like an @code{ed} script but has changes
-in the order they appear in the file.
-
-@item -H
-Use heuristics to speed handling of large files that have numerous
-scattered small changes.
-
-@item --horizon-lines=@var{lines}
-Do not discard the last @var{lines} lines of the common prefix
-and the first @var{lines} lines of the common suffix.
-
-@item -i
-Ignore changes in case; consider upper- and lower-case letters
-equivalent.
-
-@item -I @var{regexp}
-Ignore changes that just insert or delete lines that match @var{regexp}.
-
-@item --ifdef=@var{name}
-Make merged if-then-else output using @var{name}.
-
-@item --ignore-all-space
-Ignore white space when comparing lines.
-
-@item --ignore-blank-lines
-Ignore changes that just insert or delete blank lines.
-
-@item --ignore-case
-Ignore changes in case; consider upper- and lower-case to be the same.
-
-@item --ignore-matching-lines=@var{regexp}
-Ignore changes that just insert or delete lines that match @var{regexp}.
-
-@item --ignore-space-change
-Ignore trailing white space and consider all other sequences of one or
-more white space characters to be equivalent.
-
-@item --initial-tab
-Output a tab rather than a space before the text of a line in normal or
-context format.  This causes the alignment of tabs in the line to look
-normal.
-
-@item -L @var{label}
-Use @var{label} instead of the file name in the context format
-and unified format headers.
-
-@item --label=@var{label}
-Use @var{label} instead of the file name in the context format
-and unified format headers.
-
-@item --left-column
-Print only the left column of two common lines in side by side format.
-
-@item --line-format=@var{format}
-Use @var{format} to output all input lines in if-then-else format.
-@xref{Line formats}.
-
-@item --minimal
-Change the algorithm to perhaps find a smaller set of changes.  This
-makes @code{diff} slower (sometimes much slower).
-
-@item -n
-Output RCS-format diffs; like @samp{-f} except that each command
-specifies the number of lines affected.
-
-@item -N
-@itemx --new-file
-In directory comparison, if a file is found in only one directory,
-treat it as present but empty in the other directory.
-
-@item --new-group-format=@var{format}
-Use @var{format} to output a group of lines taken from just the second
-file in if-then-else format.  @xref{Line group formats}.
-
-@item --new-line-format=@var{format}
-Use @var{format} to output a line taken from just the second file in
-if-then-else format.  @xref{Line formats}.
-
-@item --old-group-format=@var{format}
-Use @var{format} to output a group of lines taken from just the first
-file in if-then-else format.  @xref{Line group formats}.
-
-@item --old-line-format=@var{format}
-Use @var{format} to output a line taken from just the first file in
-if-then-else format.  @xref{Line formats}.
-
-@item -p
-Show which C function each change is in.
-
-@item --rcs
-Output RCS-format diffs; like @samp{-f} except that each command
-specifies the number of lines affected.
-
-@item --report-identical-files
-@itemx -s
-Report when two files are the same.
-
-@item --show-c-function
-Show which C function each change is in.
-
-@item --show-function-line=@var{regexp}
-In context and unified format, for each hunk of differences, show some
-of the last preceding line that matches @var{regexp}.
-
-@item --side-by-side
-Use the side by side output format.
-
-@item --speed-large-files
-Use heuristics to speed handling of large files that have numerous
-scattered small changes.
-
-@item --suppress-common-lines
-Do not print common lines in side by side format.
-
-@item -t
-Expand tabs to spaces in the output, to preserve the alignment of tabs
-in the input files.
-
-@item -T
-Output a tab rather than a space before the text of a line in normal or
-context format.  This causes the alignment of tabs in the line to look
-normal.
-
-@item --text
-Treat all files as text and compare them line-by-line, even if they
-do not appear to be text.
-
-@item -u
-Use the unified output format.
-
-@item --unchanged-group-format=@var{format}
-Use @var{format} to output a group of common lines taken from both files
-in if-then-else format.  @xref{Line group formats}.
-
-@item --unchanged-line-format=@var{format}
-Use @var{format} to output a line common to both files in if-then-else
-format.  @xref{Line formats}.
-
-@item -U @var{lines}
-@itemx --unified@r{[}=@var{lines}@r{]}
-Use the unified output format, showing @var{lines} (an integer) lines of
-context, or three if @var{lines} is not given.
-For proper operation, @code{patch} typically needs at least two lines of
-context.
-
-@item -w
-Ignore white space when comparing lines.
-
-@item -W @var{columns}
-@itemx --width=@var{columns}
-Use an output width of @var{columns} in side by side format.
-
-@item -y
-Use the side by side output format.
-@end table
-
-@menu
-* Line group formats::          Line group formats
-* Line formats::                Line formats
-@end menu
-
-@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
-@node Line group formats
-@appendixsubsubsec Line group formats
-
-Line group formats let you specify formats suitable for many
-applications that allow if-then-else input, including programming
-languages and text formatting languages.  A line group format specifies
-the output format for a contiguous group of similar lines.
-
-For example, the following command compares the TeX file @file{myfile}
-with the original version from the repository,
-and outputs a merged file in which old regions are
-surrounded by @samp{\begin@{em@}}-@samp{\end@{em@}} lines, and new
-regions are surrounded by @samp{\begin@{bf@}}-@samp{\end@{bf@}} lines.
-
-@example
-cvs diff \
-   --old-group-format='\begin@{em@}
-%<\end@{em@}
-' \
-   --new-group-format='\begin@{bf@}
-%>\end@{bf@}
-' \
-   myfile
-@end example
-
-The following command is equivalent to the above example, but it is a
-little more verbose, because it spells out the default line group formats.
-
-@example
-cvs diff \
-   --old-group-format='\begin@{em@}
-%<\end@{em@}
-' \
-   --new-group-format='\begin@{bf@}
-%>\end@{bf@}
-' \
-   --unchanged-group-format='%=' \
-   --changed-group-format='\begin@{em@}
-%<\end@{em@}
-\begin@{bf@}
-%>\end@{bf@}
-' \
-   myfile
-@end example
-
-Here is a more advanced example, which outputs a diff listing with
-headers containing line numbers in a ``plain English'' style.
-
-@example
-cvs diff \
-   --unchanged-group-format='' \
-   --old-group-format='-------- %dn line%(n=1?:s) deleted at %df:
-%<' \
-   --new-group-format='-------- %dN line%(N=1?:s) added after %de:
-%>' \
-   --changed-group-format='-------- %dn line%(n=1?:s) changed at %df:
-%<-------- to:
-%>' \
-   myfile
-@end example
-
-To specify a line group format, use one of the options
-listed below.  You can specify up to four line group formats, one for
-each kind of line group.  You should quote @var{format}, because it
-typically contains shell metacharacters.
-
-@table @samp
-@item --old-group-format=@var{format}
-These line groups are hunks containing only lines from the first file.
-The default old group format is the same as the changed group format if
-it is specified; otherwise it is a format that outputs the line group as-is.
-
-@item --new-group-format=@var{format}
-These line groups are hunks containing only lines from the second
-file.  The default new group format is same as the changed group
-format if it is specified; otherwise it is a format that outputs the
-line group as-is.
-
-@item --changed-group-format=@var{format}
-These line groups are hunks containing lines from both files.  The
-default changed group format is the concatenation of the old and new
-group formats.
-
-@item --unchanged-group-format=@var{format}
-These line groups contain lines common to both files.  The default
-unchanged group format is a format that outputs the line group as-is.
-@end table
-
-In a line group format, ordinary characters represent themselves;
-conversion specifications start with @samp{%} and have one of the
-following forms.
-
-@table @samp
-@item %<
-stands for the lines from the first file, including the trailing newline.
-Each line is formatted according to the old line format (@pxref{Line formats}).
-
-@item %>
-stands for the lines from the second file, including the trailing newline.
-Each line is formatted according to the new line format.
-
-@item %=
-stands for the lines common to both files, including the trailing newline.
-Each line is formatted according to the unchanged line format.
-
-@item %%
-stands for @samp{%}.
-
-@item %c'@var{C}'
-where @var{C} is a single character, stands for @var{C}.
-@var{C} may not be a backslash or an apostrophe.
-For example, @samp{%c':'} stands for a colon, even inside
-the then-part of an if-then-else format, which a colon would
-normally terminate.
-
-@item %c'\@var{O}'
-where @var{O} is a string of 1, 2, or 3 octal digits,
-stands for the character with octal code @var{O}.
-For example, @samp{%c'\0'} stands for a null character.
-
-@item @var{F}@var{n}
-where @var{F} is a @code{printf} conversion specification and @var{n} is one
-of the following letters, stands for @var{n}'s value formatted with @var{F}.
-
-@table @samp
-@item e
-The line number of the line just before the group in the old file.
-
-@item f
-The line number of the first line in the group in the old file;
-equals @var{e} + 1.
-
-@item l
-The line number of the last line in the group in the old file.
-
-@item m
-The line number of the line just after the group in the old file;
-equals @var{l} + 1.
-
-@item n
-The number of lines in the group in the old file; equals @var{l} - @var{f} + 1.
-
-@item E, F, L, M, N
-Likewise, for lines in the new file.
-
-@end table
-
-The @code{printf} conversion specification can be @samp{%d},
-@samp{%o}, @samp{%x}, or @samp{%X}, specifying decimal, octal,
-lower case hexadecimal, or upper case hexadecimal output
-respectively.  After the @samp{%} the following options can appear in
-sequence: a @samp{-} specifying left-justification; an integer
-specifying the minimum field width; and a period followed by an
-optional integer specifying the minimum number of digits.
-For example, @samp{%5dN} prints the number of new lines in the group
-in a field of width 5 characters, using the @code{printf} format @code{"%5d"}.
-
-@item (@var{A}=@var{B}?@var{T}:@var{E})
-If @var{A} equals @var{B} then @var{T} else @var{E}.
-@var{A} and @var{B} are each either a decimal constant
-or a single letter interpreted as above.
-This format spec is equivalent to @var{T} if
-@var{A}'s value equals @var{B}'s; otherwise it is equivalent to @var{E}.
-
-For example, @samp{%(N=0?no:%dN) line%(N=1?:s)} is equivalent to
-@samp{no lines} if @var{N} (the number of lines in the group in the
-new file) is 0, to @samp{1 line} if @var{N} is 1, and to @samp{%dN lines}
-otherwise.
-@end table
-
-@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
-@node Line formats
-@appendixsubsubsec Line formats
-
-Line formats control how each line taken from an input file is
-output as part of a line group in if-then-else format.
-
-For example, the following command outputs text with a one-column
-change indicator to the left of the text.  The first column of output
-is @samp{-} for deleted lines, @samp{|} for added lines, and a space
-for unchanged lines.  The formats contain newline characters where
-newlines are desired on output.
-
-@example
-cvs diff \
-   --old-line-format='-%l
-' \
-   --new-line-format='|%l
-' \
-   --unchanged-line-format=' %l
-' \
-   myfile
-@end example
-
-To specify a line format, use one of the following options.  You should
-quote @var{format}, since it often contains shell metacharacters.
-
-@table @samp
-@item --old-line-format=@var{format}
-formats lines just from the first file.
-
-@item --new-line-format=@var{format}
-formats lines just from the second file.
-
-@item --unchanged-line-format=@var{format}
-formats lines common to both files.
-
-@item --line-format=@var{format}
-formats all lines; in effect, it sets all three above options simultaneously.
-@end table
-
-In a line format, ordinary characters represent themselves;
-conversion specifications start with @samp{%} and have one of the
-following forms.
-
-@table @samp
-@item %l
-stands for the contents of the line, not counting its trailing
-newline (if any).  This format ignores whether the line is incomplete.
-
-@item %L
-stands for the contents of the line, including its trailing newline
-(if any).  If a line is incomplete, this format preserves its
-incompleteness.
-
-@item %%
-stands for @samp{%}.
-
-@item %c'@var{C}'
-where @var{C} is a single character, stands for @var{C}.
-@var{C} may not be a backslash or an apostrophe.
-For example, @samp{%c':'} stands for a colon.
-
-@item %c'\@var{O}'
-where @var{O} is a string of 1, 2, or 3 octal digits,
-stands for the character with octal code @var{O}.
-For example, @samp{%c'\0'} stands for a null character.
-
-@item @var{F}n
-where @var{F} is a @code{printf} conversion specification,
-stands for the line number formatted with @var{F}.
-For example, @samp{%.5dn} prints the line number using the
-@code{printf} format @code{"%.5d"}.  @xref{Line group formats}, for
-more about printf conversion specifications.
-
-@end table
-
-The default line format is @samp{%l} followed by a newline character.
-
-If the input contains tab characters and it is important that they line
-up on output, you should ensure that @samp{%l} or @samp{%L} in a line
-format is just after a tab stop (e.g.@: by preceding @samp{%l} or
-@samp{%L} with a tab character), or you should use the @samp{-t} or
-@samp{--expand-tabs} option.
-
-Taken together, the line and line group formats let you specify many
-different formats.  For example, the following command uses a format
-similar to @code{diff}'s normal format.  You can tailor this command
-to get fine control over @code{diff}'s output.
-
-@example
-cvs diff \
-   --old-line-format='< %l
-' \
-   --new-line-format='> %l
-' \
-   --old-group-format='%df%(f=l?:,%dl)d%dE
-%<' \
-   --new-group-format='%dea%dF%(F=L?:,%dL)
-%>' \
-   --changed-group-format='%df%(f=l?:,%dl)c%dF%(F=L?:,%dL)
-%<---
-%>' \
-   --unchanged-group-format='' \
-   myfile
-@end example
-
-@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
-@node diff examples
-@appendixsubsec diff examples
-
-The following line produces a Unidiff (@samp{-u} flag)
-between revision 1.14 and 1.19 of
-@file{backend.c}.  Due to the @samp{-kk} flag no
-keywords are substituted, so differences that only depend
-on keyword substitution are ignored.
-
-@example
-$ cvs diff -kk -u -r 1.14 -r 1.19 backend.c
-@end example
-
-Suppose the experimental branch EXPR1 was based on a
-set of files tagged RELEASE_1_0.  To see what has
-happened on that branch, the following can be used:
-
-@example
-$ cvs diff -r RELEASE_1_0 -r EXPR1
-@end example
-
-A command like this can be used to produce a context
-diff between two releases:
-
-@example
-$ cvs diff -c -r RELEASE_1_0 -r RELEASE_1_1 > diffs
-@end example
-
-If you are maintaining ChangeLogs, a command like the following
-just before you commit your changes may help you write
-the ChangeLog entry.  All local modifications that have
-not yet been committed will be printed.
-
-@example
-$ cvs diff -u | less
-@end example
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node export
-@appendixsec export---Export sources from CVS, similar to checkout
-@cindex export (subcommand)
-
-@itemize @bullet
-@item
-Synopsis: export [-flNnR] (-r rev[:date] | -D date) [-k subst] [-d dir] module@dots{}
-@item
-Requires: repository.
-@item
-Changes: current directory.
-@end itemize
-
-This command is a variant of @code{checkout}; use it
-when you want a copy of the source for module without
-the @sc{cvs} administrative directories.  For example, you
-might use @code{export} to prepare source for shipment
-off-site.  This command requires that you specify a
-date or tag (with @samp{-D} or @samp{-r}), so that you
-can count on reproducing the source you ship to others
-(and thus it always prunes empty directories).
-
-One often would like to use @samp{-kv} with @code{cvs
-export}.  This causes any keywords to be
-expanded such that an import done at some other site
-will not lose the keyword revision information.  But be
-aware that doesn't handle an export containing binary
-files correctly.  Also be aware that after having used
-@samp{-kv}, one can no longer use the @code{ident}
-command (which is part of the @sc{rcs} suite---see
-ident(1)) which looks for keyword strings.  If
-you want to be able to use @code{ident} you must not
-use @samp{-kv}.
-
-@menu
-* export options::              export options
-@end menu
-
-@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
-@node export options
-@appendixsubsec export options
-
-These standard options are supported by @code{export}
-(@pxref{Common options}, for a complete description of
-them):
-
-@table @code
-@item -D @var{date}
-Use the most recent revision no later than @var{date}.
-
-@item -f
-If no matching revision is found, retrieve the most
-recent revision (instead of ignoring the file).
-
-@item -l
-Local; run only in current working directory.
-
-@item -n
-Do not run any checkout program.
-
-@item -R
-Export directories recursively.  This is on by default.
-
-@item -r @var{tag}[:@var{date}]
-Export the revision specified by @var{tag} or, when @var{date} is specified
-and @var{tag} is a branch tag, the version from the branch @var{tag} as it
-existed on @var{date}.  See @ref{Common options}.
-@end table
-
-In addition, these options (that are common to
-@code{checkout} and @code{export}) are also supported:
-
-@table @code
-@item -d @var{dir}
-Create a directory called @var{dir} for the working
-files, instead of using the module name.
-@xref{checkout options}, for complete details on how
-@sc{cvs} handles this flag.
-
-@item -k @var{subst}
-Set keyword expansion mode (@pxref{Substitution modes}).
-
-@item -N
-Only useful together with @samp{-d @var{dir}}.
-@xref{checkout options}, for complete details on how
-@sc{cvs} handles this flag.
-@end table
-
-@ignore
-@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
-@c @node export examples
-@appendixsubsec export examples
-
-Contributed examples are gratefully accepted.
-@c -- Examples here!!
-@end ignore
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node history
-@appendixsec history---Show status of files and users
-@cindex history (subcommand)
-
-@itemize @bullet
-@item
-Synopsis:     history [-report] [-flags] [-options args] [files@dots{}]
-@item
-Requires: the file @file{$CVSROOT/CVSROOT/history}
-@item
-Changes: nothing.
-@end itemize
-
-@sc{cvs} can keep a history log that tracks each use of most @sc{cvs}
-commands.  You can use @code{history} to display this information in
-various formats.
-
-To enable logging, the @samp{LogHistory} config option must be set to
-some value other than the empty string and the history file specified by
-the @samp{HistoryLogPath} option must be writable by all users who may run
-the @sc{cvs} executable (@pxref{config}).
-
-To enable the @code{history} command, logging must be enabled as above and
-the @samp{HistorySearchPath} config option (@pxref{config}) must be set to
-specify some number of the history logs created thereby and these files must
-be readable by each user who might run the @code{history} command.
-
-Creating a repository via the @code{cvs init} command will enable logging of
-all possible events to a single history log file
-(@file{$CVSROOT/CVSROOT/history}) with read and write permissions for all
-users (@pxref{Creating a repository}).
-
-@strong{Note: @code{history} uses @samp{-f}, @samp{-l},
-@samp{-n}, and @samp{-p} in ways that conflict with the
-normal use inside @sc{cvs} (@pxref{Common options}).}
-
-@menu
-* history options::             history options
-@end menu
-
-@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
-@node history options
-@appendixsubsec history options
-
-Several options (shown above as @samp{-report})  control  what
-kind of report is generated:
-
-@table @code
-@item -c
-Report on each time commit was used (i.e., each time
-the repository was modified).
-
-@item -e
-Everything (all record types).  Equivalent to
-specifying @samp{-x} with all record types.  Of course,
-@samp{-e} will also include record types which are
-added in a future version of @sc{cvs}; if you are
-writing a script which can only handle certain record
-types, you'll want to specify @samp{-x}.
-
-@item -m @var{module}
-Report on a particular module.  (You can meaningfully
-use @samp{-m} more than once on the command line.)
-
-@item -o
-Report on checked-out modules.  This is the default report type.
-
-@item -T
-Report on all tags.
-
-@item -x @var{type}
-Extract a particular set of record types @var{type} from the @sc{cvs}
-history.  The types are indicated by single letters,
-which you may specify in combination.
-
-Certain commands have a single record type:
-
-@table @code
-@item F
-release
-@item O
-checkout
-@item E
-export
-@item T
-rtag
-@end table
-
-@noindent
-One of five record types may result from an update:
-
-@table @code
-@item C
-A merge was necessary but collisions were
-detected (requiring manual merging).
-@item G
-A merge was necessary and it succeeded.
-@item U
-A working file was copied from the repository.
-@item P
-A working file was patched to match the repository.
-@item W
-The working copy of a file was deleted during
-update (because it was gone from the repository).
-@end table
-
-@noindent
-One of three record types results from commit:
-
-@table @code
-@item A
-A file was added for the first time.
-@item M
-A file was modified.
-@item R
-A file was removed.
-@end table
-@end table
-
-The options shown as @samp{-flags} constrain or expand
-the report without requiring option arguments:
-
-@table @code
-@item -a
-Show data for all users (the default is to show data
-only for the user executing @code{history}).
-
-@item -l
-Show last modification only.
-
-@item -w
-Show only the records for modifications done from the
-same working directory where @code{history} is
-executing.
-@end table
-
-The options shown as @samp{-options @var{args}} constrain the report
-based on an argument:
-
-@table @code
-@item -b @var{str}
-Show data back to a record containing  the  string
-@var{str}  in  either the module name, the file name, or
-the repository path.
-
-@item -D @var{date}
-Show data since @var{date}.  This is slightly different
-from the normal use of @samp{-D @var{date}}, which
-selects the newest revision older than @var{date}.
-
-@item -f @var{file}
-Show data for a particular file
-(you can specify several @samp{-f} options on the same command line).
-This is equivalent to specifying the file on the command line.
-
-@item -n @var{module}
-Show data for a particular module
-(you can specify several @samp{-n} options on the same command line).
-
-@item -p @var{repository}
-Show data for a particular source repository  (you
-can specify several @samp{-p} options on the same command
-line).
-
-@item -r @var{rev}
-Show records referring to revisions since the revision
-or tag named @var{rev} appears in individual @sc{rcs}
-files.  Each @sc{rcs} file is searched for the revision or
-tag.
-
-@item -t @var{tag}
-Show records since tag @var{tag} was last added to the
-history file.  This differs from the @samp{-r} flag
-above in that it reads only the history file, not the
-@sc{rcs} files, and is much faster.
-
-@item -u @var{name}
-Show records for user @var{name}.
-
-@item -z @var{timezone}
-Show times in the selected records using the specified
-time zone instead of UTC.
-@end table
-
-@ignore
-@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
-@c @node history examples
-@appendixsubsec history examples
-
-Contributed examples will gratefully be accepted.
-@c -- Examples here!
-@end ignore
-
-@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-@node import