[Cvs-cvs] Changes to ccvs/doc/RCSFILES [signed-commits]

[Derek Robert Price]

Index: ccvs/doc/RCSFILES
diff -u /dev/null ccvs/doc/RCSFILES:1.16.4.1
--- /dev/null   Sun Oct 16 20:48:31 2005
+++ ccvs/doc/RCSFILES   Sun Oct 16 20:48:29 2005
@@ -0,0 +1,282 @@
+It would be nice if 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
+standard exists.  Hence this file.
+
+The place to start is the rcsfile.5 manpage in the GNU RCS 5.7
+distribution.  Then look at the diff at the end of this file (which
+contains a few fixes and clarifications to that manpage).
+
+If you are interested in MKS RCS, src/ci.c in GNU RCS 5.7 has a
+comment about their date format.  However, as far as we know there
+isn't really any document describing MKS's changes to the RCS file
+format.
+
+The rcsfile.5 manpage does not document what goes in the "text" field
+for each revision.  The answer is that the head revision contains the
+contents of that revision and every other revision contain a bunch of
+edits to produce that revision ("a" and "d" lines).  The GNU diff
+manual (the version I looked at was for GNU diff 2.4) documents this
+format somewhat (as the "RCS output format"), but the presentation is
+a bit confusing as it is all tangled up with the documentation of
+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).
+
+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
+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.
+
+Newphrases are also used to implement the 'commitid' & OpenPGP signature
+features. The following new keywords are defined for these purposes:
+
+   commitid
+   signatures
+
+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:
+    Id: rcsfile.5in,v 5.6 1995/06/05 08:28:35 eggert Exp 
+and the new one was:
+    Id: rcsfile.5in,v 5.7 1996/12/09 17:31:44 eggert Exp 
+but since this file itself might be subject to keyword expansion I
+haven't included a diff for that fact).
+
+===================================================================
+RCS file: RCS/rcsfile.5in,v
+retrieving revision 5.6
+retrieving revision 5.7
+diff -u -r5.6 -r5.7
+--- rcsfile.5in        1995/06/05 08:28:35     5.6
++++ rcsfile.5in        1996/12/09 17:31:44     5.7
+@@ -85,7 +85,8 @@
+ .LP
+ \f2sym\fP     ::=     {\f2digit\fP}* \f2idchar\fP {\f2idchar\fP | 
\f2digit\fP}*
+ .LP
+-\f2idchar\fP  ::=     any visible graphic character except \f2special\fP
++\f2idchar\fP  ::=     any visible graphic character,
++              except \f2digit\fP or \f2special\fP
+ .LP
+ \f2special\fP ::=     \f3$\fP | \f3,\fP | \f3.\fP | \f3:\fP | \f3;\fP | 
address@hidden
+ .LP
+@@ -119,12 +120,23 @@
+ the minute (00\-59),
+ and
+ .I ss
+-the second (00\-60).
++the second (00\-59).
++If
+ .I Y
+-contains just the last two digits of the year
+-for years from 1900 through 1999,
+-and all the digits of years thereafter.
+-Dates use the Gregorian calendar; times use UTC.
++contains exactly two digits,
++they are the last two digits of a year from 1900 through 1999;
++otherwise,
++.I Y
++contains all the digits of the year.
++Dates use the Gregorian calendar.
++Times use UTC, except that for portability's sake leap seconds are not 
allowed;
++implementations that support leap seconds should output
++.B 59
++for
++.I ss
++during an inserted leap second, and should accept
++.B 59
++for a deleted leap second.
+ .PP
+ The
+ .I newphrase
+@@ -144,16 +156,23 @@
+ field in order of decreasing numbers.
+ The
+ .B head
+-field in the
+-.I admin
+-node points to the head of that sequence (i.e., contains
++field points to the head of that sequence (i.e., contains
+ the highest pair).
+ The
+ .B branch
+-node in the admin node indicates the default
++field indicates the default
+ branch (or revision) for most \*r operations.
+ If empty, the default
+ branch is the highest branch on the trunk.
++The
++.B symbols
++field associates symbolic names with revisions.
++For example, if the file contains
++.B "symbols rr:1.1;"
++then
++.B rr
++is a name for revision
++.BR 1.1 .
+ .PP
+ All
+ .I delta
+