(Lack of) usability of rcs2log

[Alan Mackenzie]

I am currently mystified by the program rcs2log.  I have no man page for
it, and can't find a description of it in either the Emacs manual or the
Elisp manual.

It seems to have something to do with generating ChangeLog from a CVS (or
RCS) repository.

I have a mailbox format file, ~/Mail/CVS-cc consisting of lots of CVS
"update" messages, each consisting of a log message and diffs.  I would
like to use rcs2log to extract these log messages into a ChangeLog.  From
the available explanations and a few experiments, I can not determine if
this is possible, or if so, how.

Although I'm sure I'll manage to figure it out eventually, it would be
nice if the program's "help" or the script's header comments described in
a context-free fashion how to use it - I am not in possession of the
necessary context.

Here in detail are the problems I'm experiencing:

1/- In the script's header comments:

# Generate a change log prefix from RCS files (perhaps in the CVS
# repository)

I don't know what a "change log prefix" is;  I don't know what exactly an
"RCS file" is.  Is this a file which is under RCS control, or is it a
RCS's file.diff which tracks changes in an individual source file, or
some other RCS administrative file?

2/- In the script's help message:

1 Help='The default FILEs are the files registered under the working directory.
2 Options:
3
4   -c CHANGELOG  Output a change log prefix to CHANGELOG (default ChangeLog).
5   -h HOSTNAME  Use HOSTNAME in change log entries (default current host).
6   -i INDENT  Indent change log lines by INDENT spaces (default 8).
7   -l LENGTH  Try to limit log lines to LENGTH characters (default 79).
8   -L FILE  Use rlog-format FILE for source of logs.
9   -R  If no FILEs are given and RCS is used, recurse through working 
directory.
10  -r OPTION  Pass OPTION to subsidiary log command.
11  -t TABWIDTH  Tab stops are every TABWIDTH characters (default 8).
12  -u "LOGIN<tab>FULLNAME<tab>MAILADDR"  Assume LOGIN has FULLNAME and 
MAILADDR.
13  -v  Append RCS revision to file names in log lines.
14  --help  Output help.
15  --version  Output version number.
16
17 Report bugs to <bug-gnu-emacs@gnu.org>.'

L1:  The "default FILEs":  Q: what files are these?  What is their
     purpose?  In what operation will they be used?

     What does "registered" mean here, and which is the "working"
     directory?  Is this the directory that "pwd" identifies, or some
     directory with which RCS is currently working in some way?

L5:  In what manner will a hostname be "used" in change log entries?

L8:  What is an "rlog-format" file?  I tried, without succes, using my
     mailbox file consisting of patch emails from sourceforge (each
     being in diff format with a log entry at the top).  This didn't
     work.

L10: What is a/the "subsidiary log command"?

L12: For what purpose might LOGIN have FULLNAME and MAILADDR.  For what
     purpose is LOGIN going to be used, and on what host?  Is this the
     host identified on L5?

L17: At least this line is crystal clear. ;-)

Sorry if I appear to be being deliberately stupider than I actually am.
I am having genuine and severe difficulties understanding this program.
I think its documentation could be considerably improved.

-- 
Alan Mackenzie (Munich, Germany)
Email: aacm@muuc.dee; to decode, wherever there is a repeated letter
(like "aa"), remove half of them (leaving, say, "a").