gnu/usr.bin/rcs/rcs/rcsfile.5

   1 .de Id
   2 .ds Rv \\$3
   3 .ds Dt \\$4
   4 ..
   5 .Id $Id: rcsfile.5,v 5.1 1991/08/19 03:13:55 eggert Exp $
   6 .ds r \s-1RCS\s0
   7 .if n .ds - \%--
   8 .if t .ds - \(em
   9 .TH RCSFILE 5 \*(Dt GNU
  10 .SH NAME
  11 rcsfile \- format of RCS file
  12 .SH DESCRIPTION
  13 An \*r file's
  14 contents are described by the grammar
  15 below.
  16 .PP
  17 The text is free format: space, backspace, tab, newline, vertical
  18 tab, form feed, and carriage return (collectively,
  19 .IR "white space")
  20 have no significance except in strings.
  21 However, an \*r file must end in a newline character.
  22 .PP
  23 Strings are enclosed by
  24 .BR @ .
  25 If a string contains a
  26 .BR @ ,
  27 it must be doubled;
  28 otherwise, strings may contain arbitrary binary data.
  29 .PP
  30 The meta syntax uses the following conventions: `|' (bar) separates
  31 alternatives; `{' and `}' enclose optional phrases; `{' and `}*' enclose
  32 phrases that may be repeated zero or more times;
  33 `{' and '}+' enclose phrases that must appear at least once and may be
  34 repeated;
  35 Terminal symbols are in
  36 .BR boldface ;
  37 nonterminal symbols are in
  38 .IR italics .
  39 .LP
  40 .nr x \w'\f3branches\fP'
  41 .nr y \w'{ \f3comment\fP'
  42 .if \nx<\ny .nr x \ny
  43 .nr y \w'\f3{ branch\fP'
  44 .if \nx<\ny .nr x \ny
  45 .ta \w'\f2deltatext\fP  'u +\w'::=  'u +\nxu+\w'  'u
  46 .fc ~
  47 .nf
  48 \f2rcstext\fP   ::=     \f2admin\fP {\f2delta\fP}* \f2desc\fP {\f2deltatext\fP}*
  49 .LP
  50 \f2admin\fP     ::=     \f3head\fP      {\f2num\fP}\f3;\fP
  51                 { \f3branch\fP  {\f2num\fP}\f3;\fP }
  52                 \f3access\fP    {\f2id\fP}*\f3;\fP
  53                 \f3symbols\fP   {\f2id\fP \f3:\fP \f2num\fP}*\f3;\fP
  54                 \f3locks\fP     {\f2id\fP \f3:\fP \f2num\fP}*\f3;\fP  {\f3strict  ;\fP}
  55                 { \f3comment\fP {\f2string\fP}\f3;\fP }
  56                 { \f3expand\fP  {\f2string\fP}\f3;\fP }
  57                 { \f2newphrase\fP }*
  58 .LP
  59 \f2delta\fP     ::=     \f2num\fP
  60                 \f3date\fP      \f2num\fP\f3;\fP
  61                 \f3author\fP    \f2id\fP\f3;\fP
  62                 \f3state\fP     {\f2id\fP}\f3;\fP
  63                 \f3branches\fP  {\f2num\fP}*\f3;\fP
  64                 \f3next\fP      {\f2num\fP}\f3;\fP
  65                 { \f2newphrase\fP }*
  66 .LP
  67 \f2desc\fP      ::=     \f3desc\fP      \f2string\fP
  68 .LP
  69 \f2deltatext\fP ::=     \f2num\fP
  70                 \f3log\fP       \f2string\fP
  71                 { \f2newphrase\fP }*
  72                 \f3text\fP      \f2string\fP
  73 .LP
  74 \f2num\fP       ::=     {\f2digit\fP{\f3.\fP}}+
  75 .LP
  76 \f2digit\fP     ::=     \f30\fP | \f31\fP | .\|.\|. | \f39\fP
  77 .LP
  78 \f2id\fP        ::=     \f2letter\fP{\f2idchar\fP}*
  79 .LP
  80 \f2letter\fP    ::=     any letter
  81 .LP
  82 \f2idchar\fP    ::=     any visible graphic character except \f2special\fP
  83 .LP
  84 \f2special\fP   ::=     \f3$\fP | \f3,\fP | \f3.\fP | \f3:\fP | \f3;\fP | \f3@\fP
  85 .LP
  86 \f2string\fP    ::=     \f3@\fP{any character, with \f3@\fP doubled}*\f3@\fP
  87 .LP
  88 \f2newphrase\fP ::=     \f2id\fP \f2word\fP* \f3;\fP
  89 .LP
  90 \f2word\fP      ::=     \f2id\fP | \f2num\fP | \f2string\fP | \f3:\fP
  91 .fi
  92 .PP
  93 Identifiers are case sensitive.  Keywords are in lower case only.
  94 The sets of keywords and identifiers may overlap.
  95 In most environments RCS uses the ISO 8859/1 encoding:
  96 letters are octal codes 101\-132, 141\-172, 300\-326, 330\-366 and 370-377,
  97 visible graphic characters are codes 041\-176 and 240\-377,
  98 and white space characters are codes 010\-015 and 040.
  99 .PP
 100 The
 101 .I newphrase
 102 productions in the grammar are reserved for future extensions
 103 to the format of \*r files.
 104 No
 105 .I newphrase
 106 will begin with any keyword already in use.
 107 .PP
 108 The
 109 .I delta
 110 nodes form a tree.  All nodes whose numbers
 111 consist of a single pair
 112 (e.g., 2.3, 2.1, 1.3, etc.)
 113 are on the trunk, and are linked through the
 114 .B next
 115 field in order of decreasing numbers.
 116 The
 117 .B head
 118 field in the
 119 .I admin
 120 node points to the head of that sequence (i.e., contains
 121 the highest pair).
 122 The
 123 .B branch
 124 node in the admin node indicates the default
 125 branch (or revision) for most \*r operations.
 126 If empty, the default
 127 branch is the highest branch on the trunk.
 128 .PP
 129 All
 130 .I delta
 131 nodes whose numbers consist of
 132 .RI 2 n
 133 fields
 134 .RI ( n >=2)
 135 (e.g., 3.1.1.1, 2.1.2.2, etc.)
 136 are linked as follows.
 137 All nodes whose first
 138 .RI 2 n \-1
 139 number fields are identical are linked through the
 140 .B next
 141 field in order of increasing numbers.
 142 For each such sequence,
 143 the
 144 .I delta
 145 node whose number is identical to the first
 146 .RI 2 n \-2
 147 number fields of the deltas on that sequence is called the branchpoint.
 148 The
 149 .B branches
 150 field of a node contains a list of the
 151 numbers of the first nodes of all sequences for which it is a branchpoint.
 152 This list is ordered in increasing numbers.
 153 .LP
 154 .nf
 155 .vs 12
 156 .ne 38
 157 Example:
 158 .if t .in +0.5i
 159 .cs 1 20
 160 .eo
 161
 162                            Head
 163                              |
 164                              |
 165                              v                        / \
 166                          ---------                   /   \
 167    / \          / \      |       |      / \         /     \
 168   /   \        /   \     |  2.1  |     /   \       /       \
 169  /     \      /     \    |       |    /     \     /         \
 170 /1.2.1.3\    /1.3.1.1\   |       |   /1.2.2.2\   /1.2.2.1.1.1\
 171 ---------    ---------   ---------   ---------   -------------
 172     ^            ^           |           ^             ^
 173     |            |           |           |             |
 174     |            |           v           |             |
 175    / \           |       ---------      / \            |
 176   /   \          |       \  1.3  /     /   \           |
 177  /     \         ---------\     /     /     \-----------
 178 /1.2.1.1\                  \   /     /1.2.2.1\
 179 ---------                   \ /      ---------
 180     ^                        |           ^
 181     |                        |           |
 182     |                        v           |
 183     |                    ---------       |
 184     |                    \  1.2  /       |
 185     ----------------------\     /---------
 186                            \   /
 187                             \ /
 188                              |
 189                              |
 190                              v
 191                          ---------
 192                          \  1.1  /
 193                           \     /
 194                            \   /
 195                             \ /
 196
 197 .ec
 198 .if t .in
 199 .cs 1
 200 .ce
 201 Fig. 1: A revision tree
 202 .vs
 203 .fi
 204 .PP
 205 .SH IDENTIFICATION
 206 .de VL
 207 \\$2
 208 ..
 209 Author: Walter F. Tichy,
 210 Purdue University, West Lafayette, IN, 47907.
 211 .br
 212 Revision Number: \*(Rv; Release Date: \*(Dt.
 213 .br
 214 Copyright \(co 1982, 1988, 1989 by Walter F. Tichy.
 215 .br
 216 Copyright \(co 1990, 1991 by Paul Eggert.
 217 .SH SEE ALSO
 218 ci(1), co(1), ident(1), rcs(1), rcsdiff(1), rcsmerge(1), rlog(1),
 219 .br
 220 Walter F. Tichy,
 221 \*r\*-A System for Version Control,
 222 .I "Software\*-Practice & Experience"
 223 .BR 15 ,
 224 7 (July 1985), 637-654.