new manual page rcsfile(5)

written by Fabio Scotoni <fabio at esse dot ch>
with minimal tweaks by me
OK jmc@ deraadt@ millert@ on an earlier version

2 files changed, 158 insertions, 2 deletions

diff --git a/usr.bin/rcs/Makefile b/usr.bin/rcs/Makefile
index 663ac1c06d0..950413c5d62 100644
--- a/usr.bin/rcs/Makefile
+++ b/usr.bin/rcs/Makefile
@@ -1,7 +1,9 @@
-#	$OpenBSD: Makefile,v 1.40 2010/10/15 08:44:12 tobias Exp $
+#	$OpenBSD: Makefile,v 1.41 2019/04/24 11:57:54 schwarze Exp $
 
 PROG=	rcs
-MAN=	ci.1 co.1 ident.1 merge.1 rcs.1 rcsclean.1 rcsdiff.1 rcsmerge.1 rlog.1
+MAN=	ci.1 co.1 ident.1 merge.1 \
+	rcs.1 rcsclean.1 rcsdiff.1 rcsmerge.1 rlog.1 \
+	rcsfile.5
 
 SRCS=	ci.c co.c ident.c merge.c rcsclean.c rcsdiff.c rcsmerge.c rcsparse.c \
 	rcsprog.c rlog.c rcsutil.c buf.c date.y diff.c diff3.c rcs.c rcsnum.c \
diff --git a/usr.bin/rcs/rcsfile.5 b/usr.bin/rcs/rcsfile.5
new file mode 100644
index 00000000000..9549bca2cbe
--- /dev/null
+++ b/usr.bin/rcs/rcsfile.5
@@ -0,0 +1,154 @@
+.\" $OpenBSD: rcsfile.5,v 1.1 2019/04/24 11:57:54 schwarze Exp $
+.\"
+.\" Copyright (c) 2019 Fabio Scotoni <fabio@esse.ch>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: April 24 2019 $
+.Dt RCSFILE 5
+.Os
+.Sh NAME
+.Nm rcsfile
+.Nd format of an RCS file
+.Sh DESCRIPTION
+An RCS file is a text file.
+It consists of four sections, each separated by two empty lines.
+RCS files should not be edited by hand;
+the
+.Xr rcs 1
+programs should be used instead.
+.Ss Administrative data
+The RCS file begins with admin data.
+Each entry in this section consists of either one or multiple values.
+Entries that take one value are specified on one line:
+The keyword and its corresponding value are separated by
+a tab character.
+Entries that take multiple values begin with a keyword on one line;
+the values are specified on subsequent lines, one per line and
+prefixed with a tab character.
+If the list is empty, the semicolon immediately follows the keyword.
+Entries are terminated with a semicolon.
+The entries are:
+.Bl -tag -width Ds
+.It Ic head Ar rev
+Highest revision number.
+.It Ic branch Ar rev
+Revision number that specifies the default branch (optional).
+.It Ic access
+List of users that are allowed to check in new revisions with
+.Xr ci 1 .
+This keyword is not followed by a tab;
+instead, the list of users is specified with one username per line.
+The list is terminated by a single semicolon.
+.It Ic symbols
+List of symbolic names used as aliases for specific revisions.
+Each entry consists of a symbolic name followed by a colon and
+the revision.
+.It Ic locks
+List of locked revisions.
+Each entry consists of a username followed by a colon and
+the locked revision.
+.It Ic strict
+Indicates that locks are strict;
+if missing, locks are not strict.
+This entry takes no value and immediately follows the list of locks
+without a newline.
+.It Ic comment Pf @ Ar leader Ns @
+Contains the comment leader surrounded by at signs.
+.It Ic expand Pf @ Ar mode Ns @
+Indicates the keyword substitution mode.
+See
+.Xr rcs 1
+for the possible keyword substitution modes.
+If this entry is not given in the admin section,
+.Ar kv
+must be assumed.
+.El
+.Ss List of deltas
+The RCS file continues with a list of deltas.
+Deltas are separated by empty lines.
+The list begins with the head and ends with the initial revision.
+Each entry begins with the revision number, followed by a newline.
+After that, the structure follows the admin section.
+.Bl -tag -width Ds
+.It Ic date Ar YYYY . Ns Ar mm . Ns Ar dd . Ns Ar HH . Ns Ar MM . Ns Ar SS
+Indicates the date and UTC time the revision was checked in.
+The date consists of the year, the month,
+the day of month, the hour, the minute and the second,
+each separated by dots.
+The year is specified in either two or four digits.
+The other values are specified in two digits each.
+.It Ic author Ar username
+Author's username.
+This entry immediately follows the
+.Ic date
+without a newline.
+.It Ic state Ar value
+Contains the state of this delta,
+which is an arbitrary string.
+This entry immediately follows the
+.Ic author
+without a newline.
+.It Ic branches
+List of revision numbers that are branches stemming from this delta.
+.It Ic next Ar rev
+Next revision.
+Chronologically, this is the
+.Em previous
+revision.
+For the initial check-in,
+.Ar rev
+is empty,
+but the tab character that acts as separator is nonetheless present.
+.El
+.Ss Description
+The RCS file continues with the description.
+It consists of the string
+.Ic desc
+followed by a newline and then an at sign.
+The description is an arbitrary string that can span multiple lines.
+A single at sign on a line terminates the description.
+At signs anywhere in the description itself
+are escaped by prefixing them with another at sign.
+.Ss List of deltatexts
+Finally, the RCS file contains the deltatexts.
+The list of deltatexts is ordered the same as the list of deltas.
+Deltatexts are separated by two lines.
+Each entry begins with the revision number, followed by a newline.
+The text
+.Dq Ic log
+follows on its own line.
+The log message follows on another new line;
+it consists of an at sign, the log message itself (which may span
+multiple lines), and finally an at sign on its own line.
+Then the text
+.Dq Ic text
+follows on its own line.
+The format is the same as for the description and log message.
+As with the description,
+at signs anywhere in the log message or in the deltatext itself
+are escaped by prefixing them with another at sign.
+The deltatext of the head consists of the full file contents.
+All subsequent deltatexts contain the differences to the previous
+deltatext in the format of
+.Xr diff 1
+.Fl n .
+.Sh SEE ALSO
+.Xr ci 1 ,
+.Xr co 1 ,
+.Xr cvs 1 ,
+.Xr ident 1 ,
+.Xr rcs 1 ,
+.Xr rcsclean 1 ,
+.Xr rcsdiff 1 ,
+.Xr rcsmerge 1