Re: Are my RCS files actually malformed?

[Bob Proulx]

Peter Budny wrote:
> Anyway, the tool keeps complaining about malformed RCS edits, and I can't
> find enough documentation on what constitutes a *well-formed* RCS edit to
> figure out whether it's the RCS file at fault or the tool.

The best documentation on the rcs file format that I know about is
that found in the man page for rcsfile(5).

  
http://www.freebsd.org/cgi/man.cgi?query=rcsfile&apropos=0&sektion=0&manpath=FreeBSD+9.0-RELEASE&arch=default&format=html

This is also described in the GNU manual:

  http://www.gnu.org/software/rcs/manual/html_node/Concepts.html#Concepts

Between those two I do not believe there is any more authoritative
source other than the source code itself.

> If you have a file that ends with a Unix newline ('\n'), how many lines does
> it have?

The 'wc -l' program will tell you this information.  A text file has
as many lines as there are newline characters.  A non-empty file that
does not end with a newline character is not a text file because it
contains more than "lines of text".

If you are dealing with differences between two files and either file
ends without a newline then by long time practice and standardization
by POSIX it is not a text file.

  
http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_205
  3.205 Line
  A sequence of zero or more non- <newline> characters plus a
  terminating <newline> character.

Originally only GNU rcs handled non-text files and binary files.  This
was due to using GNU diff which had been extended to work with such
files.  Since GNU diff could produce a diff between these cases it was
possible to use GNU rcs with it.  But other tools not using GNU diff
usually didn't handle this case.

> In other words, should an edit for that file look like:
> 
> @d1 50
> 
> a50 1
>
> This file ends with a newline character.
> 
> @
> 
> Or should it look like:
> 
> @d1 50
> 
> a50 2
> 
> This file ends with a newline character.
> 
> @

I think instead of mailing out munged diff deltas that you would be
better off creating a small test case and trying it.  Without the two
files under discussion it is too abstract.  Sorry.

Remember that the delta on the main trunk is in the direction of what
changes are needed to the current file to produce the previous file.

Also note that you may be running into end of line differences
concerning NL versus CR-NL versus CR.

> Does it matter if the file is binary?

Yes in that the diff program used must handle binary data and files
that do not end with a newline are binary files not text files.  And
if you are trying to transport files from one system to another then
the different diff programs on those different systems must handle
binary data in the same way.

> I assume that if the file *doesn't* end in a newline, then it only has 1
> line, such as:

What does 'wc -l' say about the file?  The answer may be zero if it
does not contain any newlines.

> Does it matter if the "text" command after the log is on a new line? Or can
> it follow the "@" ending the log immediately without a newline?
> 
> In other words, is this a valid revision?
> 
> 1.5
> 
> log
> 
> @ @text
> 
> @@

Your mailer has munged your example by adding a lot of extra lines
between everything.  The above is not normal due to those extra
newlines making it hard to know what to say.

The log message occurs between '@' characters.

  string         ::=  @{any character, with @ doubled}*@

After the terminating @ there is a newline.  Then "text" appears
before the next string which will either be the latest version of the
file or the delta between.

Here is a normal case.

  1.2
  log
  @line two added
  @
  text
  @line one
  line two
  @


  1.1
  log
  @Initial revision
  @
  text
  @d2 1
  @

If your files look otherwise then they may need to be "helped" back
into a different format for other tools to work properly with them.

Because your mailer is munging your examples it is hard to read your
examples and know what they are intending.  Consider creating small
files (emphasis on small) and attaching them as text file attachments
to avoid the munging.  Hopefully your mailer will handle that correctly.

Bob