summaryrefslogtreecommitdiffstats
path: root/contrib/cvs/doc/RCSFILES
diff options
context:
space:
mode:
Diffstat (limited to 'contrib/cvs/doc/RCSFILES')
-rw-r--r--contrib/cvs/doc/RCSFILES276
1 files changed, 0 insertions, 276 deletions
diff --git a/contrib/cvs/doc/RCSFILES b/contrib/cvs/doc/RCSFILES
deleted file mode 100644
index 4650337..0000000
--- a/contrib/cvs/doc/RCSFILES
+++ /dev/null
@@ -1,276 +0,0 @@
-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.
-
-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 | \f3@\fP
- .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
-
OpenPOWER on IntegriCloud