New release from Cyclic Software

1 files changed, 7 insertions, 160 deletions

diff --git a/gnu/usr.bin/cvs/doc/RCSFILES b/gnu/usr.bin/cvs/doc/RCSFILES
index 46503377901..0ac61aa1d42 100644
--- a/gnu/usr.bin/cvs/doc/RCSFILES
+++ b/gnu/usr.bin/cvs/doc/RCSFILES
@@ -1,4 +1,4 @@
-It would be nice if the RCS file format (which is implemented by a
+It would be nice for the RCS file format (which is implemented by a
 great many tools, both free and non-free, both by calling GNU RCS and
 by reimplementing access to RCS files) were documented in some
 standard separate from any one tool.  But as far as I know no such
@@ -24,37 +24,12 @@ several other output formats.  If you just want some source code to
 look at, the part of CVS which applies these is RCS_deltas in
 src/rcs.c.
 
-The rcsfile.5 documentation only _very_ briefly touches on the order
-of the revisions.  The order _is_ important and CVS relies on it.
-Here is an example of what I was able to find, based on the join3
-sanity.sh testcase (and the behavior I am documenting here seems to be
-the same for RCS 5.7 and CVS 1.9.27):
-
-    1.1 ----------------->  1.2
-     \---> 1.1.2.1           \---> 1.2.2.1
-
-Here is how this shows up in the RCS file (omitting irrelevant parts):
-
-  admin:  head 1.2;
-  deltas:
-    1.2 branches 1.2.2.1; next 1.1;
-    1.1 branches 1.1.2.1; next;
-    1.1.2.1 branches; next;
-    1.2.2.1 branches; next;
-  deltatexts:
-    1.2
-    1.2.2.1
-    1.1
-    1.1.2.1
-
-Yes, the order seems to differ between the deltas and the deltatexts.
-I have no idea how much of this should actually be considered part of
-the RCS file format, and how much programs reading it should expect to
-encounter any order.
-
-The rcsfile.5 grammar shows the {num} after "next" as optional; if it
-is omitted then there is no next delta node (for example 1.1 or the
-head of a branch will typically have no next).
+The first time I read rcsfile.5 I didn't really notice the part about
+the order of the revisions.  This order _is_ important and CVS relies
+on it.  It is documented but it would be clearer if the example in
+rcsfile.5 also showed the order of the revisions (and the "next" and
+"branch" fields and anything else where it would be useful to have an
+example of how a revision tree is represented in an RCS file).
 
 There is one case where CVS uses CVS-specific, non-compatible changes
 to the RCS file format, and this is magic branches.  See cvs.texinfo
@@ -62,134 +37,6 @@ for more information on them.  CVS also sets the RCS state to "dead"
 to indicate that a file does not exist in a given revision (this is
 stored just as any other RCS state is).
 
-The RCS file format allows quite a variety of extensions to be added
-in a compatible manner by use of the "newphrase" feature documented in
-rcsfile.5.  We won't try to document extensions not used by CVS in any
-detail, but we will briefly list them.  Each occurrence of a newphrase
-begins with an identifier, which is what we list here.  Future
-designers of extensions are strongly encouraged to pick
-non-conflicting identifiers.  Note that newphrase occurs several
-places in the RCS grammar, and a given extension may not be legal in
-all locations.  However, it seems better to reserve a particular
-identifier for all locations, to avoid confusion and complicated
-rules.
-
-   Identifier   Used by
-   ----------   -------
-   namespace    RCS library done at Silicon Graphics Inc. (SGI) in 1996
-                (a modified RCS 5.7--not sure it has any other name).
-   dead         A set of RCS patches developed by Rich Pixley at
-                Cygnus about 1992.  These were for CVS, and predated
-                the current CVS death support, which uses a state "dead"
-                rather than a "dead" newphrase.
-
-CVS does use newphrases to implement the `PreservePermissions'
-extension introduced in CVS 1.9.26.  The following new keywords are
-defined when PreservePermissions=yes:
-
-   owner
-   group
-   permissions
-   special
-   symlink
-   hardlinks
-
-The contents of the `owner' and `group' field should be a numeric uid
-and a numeric gid, respectively, representing the user and group who
-own the file.  The `permissions' field contains an octal integer,
-representing the permissions that should be applied to the file.  The
-`special' field contains two words; the first must be either `block'
-or `character', and the second is the file's device number.  The
-`symlink' field should be present only in files which are symbolic
-links to other files, and absent on all regular files.  The
-`hardlinks' field contains a list of filenames to which the current
-file is linked, in alphabetical order.  Because files often contain
-characters special to RCS, like `.' and sometimes even contain spaces
-or eight-bit characters, the filenames in the hardlinks field will
-usually be enclosed in RCS strings.  For example:
-
-	hardlinks	README @install.txt@ @Installation Notes@;
-
-The hardlinks field should always include the name of the current
-file.  That is, in the repository file README,v, any hardlinks fields
-in the delta nodes should include `README'; CVS will not operate
-properly if this is not done.
-
-The rules regarding keyword expansion are not documented along with
-the rest of the RCS file format; they are documented in the co(1)
-manpage in the RCS 5.7 distribution.  See also the "Keyword
-substitution" chapter of cvs.texinfo.  The co(1) manpage refers to
-special behavior if the log prefix for the $Log keyword is /* or (*.
-RCS 5.7 produces a warning whenever it behaves that way, and current
-versions of CVS do not handle this case in a special way (CVS 1.9 and
-earlier invoke RCS to perform keyword expansion).
-
-Note that if the "expand" keyword is omitted from the RCS file, the
-default is "kv".
-
-Note that the "comment {string};" syntax from rcsfile.5 specifies a
-comment leader, which affects expansion of the $Log keyword for old
-versions of RCS.  The comment leader is not used by RCS 5.7 or current
-versions of CVS.
-
-Both RCS 5.7 and current versions of CVS handle the $Log keyword in a
-different way if the log message starts with "checked in with -k by ".
-I don't think this behavior is documented anywhere.
-
-Here is a clarification regarding characters versus bytes in certain
-character sets like JIS and Big5:
-
-    The RCS file format, as described in the rcsfile(5) man page, is
-    actually byte-oriented, not character-oriented, despite hints to
-    the contrary in the man page.  This distinction is important for
-    multibyte characters.  For example, if a multibyte character
-    contains a `@' byte, the `@' must be doubled within strings in RCS
-    files, since RCS uses `@' bytes as escapes.
-
-    This point is not an issue for encodings like ISO 8859, which do
-    not have multibyte characters.  Nor is it an issue for encodings
-    like UTF-8 and EUC-JIS, which never uses ASCII bytes within a
-    multibyte character.  It is an issue only for multibyte encodings
-    like JIS and BIG5, which _do_ usurp ASCII bytes.
-
-    If `@' doubling occurs within a multibyte char, the resulting RCS
-    file is not a properly encoded text file.  Instead, it is a byte
-    stream that does not use a consistent character encoding that can
-    be understood by the usual text tools, since doubling `@' messes
-    up the encoding.  This point affects only programs that examine
-    the RCS files -- it doesn't affect the external RCS interface, as
-    the RCS commands always give you the properly encoded text files
-    and logs (assuming that you always check in properly encoded
-    text).
-
-    CVS 1.10 (and earlier) probably has some bugs in this area on
-    systems where a C "char" is signed and where the data contains
-    bytes with the eighth bit set.
-
-One common concern about the RCS file format is the fact that to get
-the head of a branch, one must apply deltas from the head of the trunk
-to the branchpoint, and then from the branchpoint to the head of the
-branch.  While more detailed analyses might be worth doing, we will
-note:
-
-    * The performance bottleneck for CVS generally is figuring out which
-    files to operate on and that sort of thing, not applying deltas.
-
-    * Here is one quick test (probably not a very good test; a better test
-    would use a normally sized file (say 50-200K) instead of a small one):
-
-	I just did a quick test with a small file (on a Sun Ultra 1/170E
-	running Solaris 5.5.1), with 1000 revisions on the main branch and
-	1000 revisions on branch that forked at the root (i.e., RCS revisions
-	1.1, 1.2, ..., 1.1000, and branch revisions 1.1.1.1, 1.1.1.2, ...,
-	1.1.1.1000).  It took about 0.15 seconds real time to check in the
-	first revision, and about 0.6 seconds to check in and 0.3 seconds to
-	retrieve revision 1.1.1.1000 (the worst case).
-
-    * Any attempt to "fix" this problem should be careful not to interfere
-    with other features, such as lightweight creation of branches
-    (particularly using CVS magic branches).
-
 Diff follows:
 
 (Note that in the following diff the old value for the Id keyword was: