.\"	$Id: rfl.1,v 1.0 1996/01/02 20:57:28 jerry Exp $
.TH RFL 1 [mh.6]
.SH NAME
rfl \- add messages to a storage digest
.SH SYNOPSIS
.in +.5i
.ti -.5i
rfl
\%[+dest-folder] \%[msgs]
\%[\-add component \%[\-add component...]]
\%[\-inplace] \%[\-noinplace]
\%[\-keep] \%[\-nokeep]
\%[\-query] \%[\-noquery]
\%[[\-range msgs] OR \%[\-to msg]]
\%[\-src +src-folder]
\%[\-verbose] \%[\-noverbose]
\%[\-help]
.in -.5i
.SH DESCRIPTION
.PP
.I rfl
is a Perl script.
It reads the message(s) (default: current message) named on the command line
from the current folder (or another folder, if you name it with `\-src').
.I rfl
appends the message(s) to the last message with the same `Subject:'
in the destination folder.
The destination message will be changed
into an RFC934-compatible digest format (if it isn't already)
that you can feed to
.IR burst (1)
to get the individual messages back.
You can add more messages to the digest by using
.I rfl
again.
A special `X-mhglue:' field is added to mark the digest;
if you delete this field,
.I rfl
won't recognize the digest.
.PP
For example, this command:
.RS
rfl 23 24 +foobar
.RE
would read message 23 from the current folder, find the last message
with the same `Subject:' in the `+foobar' folder, and add it to the end.
Then, it will do the same thing for message 24 (find message with
same subject, append message 24 to it).
.PP
.I rfl
will edit the destination message in place, so any links to
it won't be broken.
If you use the `\-noinplace' switch,
.I rfl
will create a new message from a copy of the destination message.
.PP
.I rfl
always tells you which message is being added to which.
The `\-verbose' switch makes
.I rfl
tell you more.
.PP
The `\-query' switch shows you a
.IR scan (1)
list of messages in the
destination folder and asks which one to append each message to.
.PP
The program searches the destination folder starting at the last
(highest-numbered) message.
By default,
.I rfl
checks the last 998 messages in the destination folder.
If the folder has a lot of messages, that can take a while.
So, if you use the `\-range' switch (typically, in your MH profile),
.I rfl
will only search those particular messages.
For example:
.RS
rfl @sub \-range last:20
.RE
would check the last 20 messages in the `@sub' subfolder and add
the current message from the current folder to the last	message
that matches.
To give a range of specific numbers, quote the
argument (so the shell will pass all of it as one argument).
For instance, to make
.I rfl
search the previous 50 and next 50 messages:
.RS
rfl \-range "prev:50 next:50" ...
.RE
If
.I rfl
can't find a matching message (unless you use \-query, of
course), it skips the message and tries the next one (if any).
.PP
You can also use `\-to msg' to specify the exact destination
message (no subject searching).
This is handy for adding other messages to the current message (`cur')
or when you know the exact message number (like `last').
For example, to add the last 2
messages from the current folder to the last message in `+reports':
.RS
rfl \-to last +reports last:2
.RE
To add messages 1 and 5 from `+junk'
to the current message in the current folder, type:
.RS
rfl 1 5 \-src +junk \-to cur
.RE
.PP
By default,
.I rfl
copies all message headers into the digest body.
If you have a file named `rfl.skiphdrs' in your top-level
mail directory,
.I rfl
will not copy the fields listed there.
List the fields to skip, one per line, in the file.
You can also use
.IR perl -type
(basically,
.IR ed -type)
regular expressions in the file.
For instance, to omit `Received:', `Sender:',
and any `X\-' fields, use these three lines (not indented):
.RS
.nf
received
sender
x\-.*
.fi
.RE
.PP
By default,
.I rfl
copies the `From:', `To:', and
`Subject:' fields to the
header of the digest.
(It also adds a `Date:' field with the time
the digest was edited.)
The `\-add' switch names other fields to add.
For example, to add `Message\-ID:' and `cc:' fields, use:
.RS
rfl \-add message\-id \-add cc ...
.RE
Note: the same `\-add' switches must be used every time you append more
messages to the digest.
Otherwise, the extra fields you `\-add'ed
before won't be copied to the new digest.
.PP
By default,
.I rfl
uses
.IR rmm (1)
on the source message(s) after copying.
If you use the `\-keep' switch,
.I rfl
won't use
.IR rmm .
.PP
You can put an `rfl:' field in your MH profile with default switches
you want (like `\-verbose').
And, as with most MH commands, you can make
.I rfl
versions (links)
with other names.
For example, to simulate the old
.I mhadd
script I used to have that adds other messages to
the current message, I made a symbolic link named
.I mhadd
pointing to
.IR rfl .
Then I put this line in my MH profile:
.RS
mhadd: \-to cur
.RE
Then I can use:
.RS
mhadd 23
.RE
to add message 23 to the current message.
(Note: the
.I rfl.skiphdrs
file won't be used when you call
.I rfl
by a different name.
This is a feature.
Create another file \(em here, for example, \fImhadd.skiphdrs\fP \(em or
just link the other file to your original \fIrfl.skiphdrs\fP.
.SH DISCLAIMER (SIGH)
USE THIS CODE AT YOUR OWN RISK.
THE AUTHOR(S) CANNOT BE RESPONSIBLE FOR ANY PROBLEMS YOU HAVE WITH THE
SCRIPT OR LIABLE FOR ANY DAMAGES THAT THIS SCRIPT CAUSES, DIRECTLY OR
INDIRECTLY.
THE USER IS ASSUMED TO UNDERSTAND MH AND PERL WELL ENOUGH TO DECIDE
WHETHER OR NOT THIS SCRIPT IS SUITABLE AND WILL WORK CORRECTLY.
ETC. ETC.
.PP
This program is in the public domain.
If you modify it, please add comments to the code that mark your revisions
clearly (so people will know that it isn't the original
.IR rfl ).
Please also send me a copy of any changes you make so that I can think about
folding them into a new release.
.SH FILES
.ta 3i
$MH or $HOME/.mh_profile	The user profile
.br
<mh-dir>/<prog>.skiphdrs	Header fields not to copy
.SH PROFILE COMPONENTS
.ta 2.2i
Path:	To determine the user's MH directory
.br
Current-Folder:	To find the default current folder
.SH SEE ALSO
.I "Proposed Standard for Message Encapsulation"
(aka RFC-934),
.IR perl (1),
.IR refile (1),
.IR burst (1),
.IR scan (1),
.IR rmm (1),
.IR mh-mail (5).
.SH CONTEXT
If `-src +folder' is given, it will become the current folder.
.SH BUGS
.IR mhpath (1)
refuses to handle folders with more than 998 messages, so
.I rfl
can't use a destination `\-range' of more than 998 messages.
.PP
.I rfl
can't add an
.I rfl
digest to another
.I rfl
digest and keep the same digest format.
.PP
With a command like `rfl 19 20', you can accidentally add
the first message (19) to the second message (20) if they both have the
same subject.
Then the second message can't be added to anything because it's an
.I rfl
digest.
Workaround (until
.I rfl
can add digests to digests): use `\-range "1\-18 21-last"'.
.PP
.I rfl
does lots of work to make the digest header have `Subject:' fields
without newlines or multiple spaces.
That's because
.IR repl (1)
formats the subjects of messages it replies to in the same way.
.PP
.I rfl
checks pathnames to be sure a message isn't added to itself.
But that doesn't stop
.I rfl
from adding a message to the message's own \fIlink\fP.
.PP
Some coding is kind of ugly or inefficient.
(This is my first Perl script.)
.PP
Prints informative messages without the `\-verbose' switch.
This is actually a feature...
.SH AUTHOR
Jerry Peek.
I can't promise to support the program, but please report
bugs to me, jpeek@jpeek.com... I'll fix them as soon as possible,
with thanks.
Suggestions are welcome, too!