[p4] Peforce History in source code

[Paul Jackson]

Perhaps it's time that Perforce invented a new construct, like
$Log$, but that resolves the problems that cause $Log$ to be such
a pain in the butt for diffing, merging and checking back in.

The basic problem is that $Log$ expansions cause spurious diff's,
spurious merge conflicts, and unlike other single-line RCS
$Keywords$, $Log$ expansions cannot be automatically detected
and unexpanded by the tools because it is non-deterministic
where they end.

In other words, while $Log$ expansions are fine for read-only
output, they complicate life when the expanded versions come
back around, to be diff'ed, merged and checked back in.

My presumption is that it is issues such as these that have been
causing Perforce to be reluctant, in the face of longstanding
and vigourous customer demand, to add $Log$.

RCS 5.7 took one step in the right direction, with the following
change:

  Inserted log lines now have the same prefix as the preceding
  `$Log' line.  E.g. if a $Log line starts with `// $Log', log
  lines are prefixed with `// '.  RCS still records the (now
  obsolescent) comment leader inside RCS files, but it ignores
  the comment leader unless it is emulating older RCS versions.

Paul Eggert, the author of the above, might well have some
thoughts on this as well.  If Larry McVoy, the author of the
upcoming BitKeeper (which expands both RCS and SCCS keywords)
also agreed to support such changes, that would be good too.

I'm thinking of something along the lines of an added term in
the unexpanded $Log$ expression that specified a string to place
at the end of the expanded output.  Along the lines of shell
here documents:

    cat <<!!EOF!!
	stuff
	and more stuff
    !!EOF!!

In the $Log$ case, this would look like $Log !!EOF!! $, for your
choice of "!!EOF!!" string, and with per-RCS-file and general
defaults.  For example, '$Log$' might be taken as equivalent to
'$Log End-of-Log $', absent a specific RCS per-file default.

Then tools could, if they had to, robustly remove $Log$
expansions for diff'ing and merging purposes.


=======================================================================
I won't rest till it's the best ...	   Software Production Engineer
Paul Jackson (pj at sgi.com; pj at usa.net) 3x1373 http://sam.engr.sgi.com/pj