Hi Fabio, Fabio Scotoni wrote on Tue, Apr 23, 2019 at 01:45:22PM +0200:
> While familiarizing myself with OpenRCS, > I noticed that there's no rcsfile(5). > This may be handy for people whose RCS file got corrupted for whatever > reasons. > Other *NIXes that ship SCCS tend to have a sccsfile(4), > so I figured it could be worthwhile to have something of that nature for > OpenRCS. I like this. Especially when a file format is human-readable, non-trivial, and easy to describe, describing it is worthwhile. I think the source should go to /usr/src/usr.bin/rcs/rcs.5 and it should be installed to /usr/share/man/man5/rcs.5. By the way, i recently had to hand-edit RCS files, for merging the histories from multiple different historical CVS repositories. This manual page is useful for such work. > Feedback would be appreciated, Some minor remarks inline. They are not critical, though; polishing of manual pages can also be done in-tree. > as would be proofreading by someone who's > done more work with RCS files than I have. That wouldn't be me. Either way, an additional OK to import would be appreciated. Yours, Ingo At the top of the file, a Copyright notice and license is missing. Please conisder using /usr/share/misc/license.template with the comment markers changed to .\" . > .Dd $Mdocdate$ > .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 multiple sections, each separated by two empty lines. > RCS files should not be edited by hand; > the RCS programs should be used instead. the .Xr rcs 1 programs should be used instead. > .Pp > The RCS file consists of four sections: > .Bl -tag -width "deltatexts" -compact > .It admin > Administrative data about the RCS file itself. > .It deltas > List of deltas, i.e. metadata about changes. > .It desc > A description of what the file. > .It deltatexts > List of the changes made by each delta. > .El Please avoid inventing names that don't actually appear in the file. I suggest using: The RCS file consists of four sections: .Bl -enum -with 2n -compact .It Administrative data about the RCS file itself. .It List of deltas, i.e. metadata about changes. .It A description of what the file. .It List of the changes made by each delta. .El In that case, the structure of the rest of the text would remain more or less unchanged. Alternatively, you could shorten the structure as follows: programs should be used instead. .Ss Administrative data The first section contains administrative data about the RCS file itself. ... .Ss List of deltas And so on. > .Pp > 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 Cm head Ar rev I'd prefer "Ic head" (and similarly in the following) because "head" is a stand-alone keyword, not an argument to something else. > Highest revision number. > .It Cm branch Ar rev > Revision number that specifies the default branch (optional). > .It Cm 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 Cm 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 Cm locks > List of locked revisions. > Each entry consists of a username followed by a colon and > the locked revision. > .It Cm 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 Cm comment @ Ns Ar leader Ns Cm @ > Contains the comment leader surrounded by at signs. > .It Cm expand @ Ns Ar mode Ns Cm @ > 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 > .Pp > 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 Cm date Ar YYYY.mm.dd.HH.MM.SS > Indicates the date and time the revision was checked in. Indicates the date and UTC time the ... > 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 four digits, the other values are specified in > two digits each. > .It Cm author Ar username > Author's username. > This entry immediately follows the > .Cm date > without a newline. > .It Cm state Ar value > Contains the state of this delta, > which is an arbitrary string. > This entry immediately follows the > .Cm author > without a newline. > .It Cm branches > List of revision numbers that are branches stemming from this delta. > .It Cm 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 > .Pp > The RCS file continues with the description. > It consists of the string > .Cm desc Again, .Ic. > 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. > .Pp > 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 Cm log Ic > 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 Cm text Ic > 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 , I suggest inserting .Xr cvs 1 here; it uses the same format. > .Xr ident 1 , > .Xr rcs 1 , > .Xr rcsclean 1 , > .Xr rcsdiff 1 , > .Xr rcsmerge 1
