.\"	@(MHWARNING)
.\" @(#)$Id$
.SC FORW 1
.NA
forw \- forward messages
.SY
forw
\%[+folder] \%[msgs]
\%[\-annotate] \%[\-noannotate]
\%[\-draftfolder\ +folder] \%[\-draftmessage\ msg] \%[\-nodraftfolder]
\%[\-editor\ editor] \%[\-noedit]
\%[\-filter\ filterfile]
\%[\-form\ formfile]
\%[\-format] \%[\-noformat]
\%[\-inplace] \%[\-noinplace]
@BEGIN: MIME
\%[\-mime] \%[\-nomime]
@END: MIME
\%[\-whatnowproc\ program] \%[\-nowhatnowproc]
\%[\-help]

.ti .5i
forw
\%[+folder] \%[msgs]
\%[\-digest\ list] \%[\-issue\ number] \%[\-volume\ number]
\%[other\ switches\ for\ \fIforw\fR]
\%[\-help]
.DE
\fIForw\fR may be used to prepare a message containing other
messages.
It constructs the new message from the components file
or `\-form\ formfile' (see \fIcomp\fR\0), with a body composed of the
message(s) to be forwarded.
An editor is invoked as in \fIcomp\fR,
and after editing is complete, the user is prompted before the message
is sent.

The default message form contains the following elements:

.nf
.in +.5i
.ne 10
.eo
.so @(MHETCPATH)/forwcomps
.ec
.in -.5i
.fi

If the file named \*(lqforwcomps\*(rq exists in the user's MH directory,
it will be used instead of this form.
In either case, the file specified by `\-form\ formfile' will be
used if given.

If the draft already exists,
\fIforw\fR will ask you as to the disposition of the draft.
A reply of \fBquit\fR will abort \fIforw\fR, leaving the draft intact;
\fBreplace\fR will replace the existing draft with a blank skeleton;
and \fBlist\fR will display the draft.

If the `\-annotate' switch is given, each message being
forwarded will be annotated with the lines

     Forwarded:\ date
     Forwarded:\ addrs

where each address list contains as many lines as required.
This annotation
will be done only if the message is sent directly from \fIforw\fR.
If the message is not sent immediately from \fIforw\fR,
\*(lqcomp\ \-use\*(rq may be used to re\-edit and send the constructed message,
but
the annotations won't take place.
The '\-inplace' switch causes annotation to
be done in place in order to preserve links to the annotated message.

See \fIcomp\fR\0(1) for a description of the `\-editor' and `\-noedit'
switches.

Although \fIforw\fR uses the `\-form\ formfile' switch to direct it how to
construct the beginning of the draft, the `\-filter\ filterfile',
`\-format', and `\-noformat'
switches direct \fIforw\fR as to how each forwarded message should be
formatted in the body of the draft.
If `\-noformat' is specified,
then each forwarded message is output exactly as it appears.
If `\-format' or `\-filter\ filterfile' is specified,
then each forwarded message is filtered (re\-formatted) prior to being
output to the body of the draft.
The filter file for \fIforw\fR should be a standard form file for
\fImhl\fR,
as \fIforw\fR will invoke \fImhl\fR to format the forwarded messages.
The default message filter (what you get with `\-format') is:

.nf
.in +.5i
.ne 10
.eo
.so @(MHETCPATH)/mhl.forward
.ec
.in -.5i
.fi

If the file named \*(lqmhl.forward\*(rq exists in the user's MH directory,
it will be used instead of this form.
In either case, the file specified by `\-filter\ filterfile' will be
used if given.
To summarize:
`\-noformat' will reproduce each forwarded message exactly,
`\-format' will use \fImhl\fR and a default filterfile, \*(lqmhl.forward\*(rq,
to format each forwarded message, and
`\-filter\ filterfile' will use the named filterfile to format each
forwarded message with \fImhl\fR.

Each forwarded message is separated with an encapsulation delimiter 
and
dashes in the first column of the forwarded messages will be prepended
with `\-\ ' so that
when received, the message is suitable for bursting by \fIburst\fR\0(1).
This follows the Internet RFC\-934 guidelines.

For users of \fIprompter\fR\0(1), by specifying prompter's `-prepend'
switch in the \&.mh\(ruprofile file, any commentary text is entered before
the forwarded messages.  (A major win!)

@BEGIN: MIME
To use the MIME rules for encapsulation,
specify the `\-mime' switch.
This directs \fIforw\fR to generate an \fImhn\fR composition file.
Note that MH will not invoke \fImhn\fR automatically,
unless you  add this line to your \&.mh\(ruprofile file:
.sp
.in +.5i
automhnproc: mhn
.in -.5i
.sp
Otherwise,
you must specifically give the command
.sp
.in +.5i
What now? edit mhn
.in -.5i
.sp
prior to sending the draft.

To automate this somewhat,
create a link to \fIprompter\fR called \fIrapid\fR
and put these lines in your \&.mh\(ruprofile file:
.sp
.in +.5i
.nf
forw: -editor rapid -mime
rapid: -rapid
rapid-next: mhn
.fi
.in -.5i
.sp
Then,
you can simply do:
.sp
.in +.5i
.nf
\fIforw msgs\fR
To: \fImailbox\fR
cc:
Subject: \fIwhatever\fR

--------Enter initial text

\fIblah, blah, blah.\fR
<CTRL-D>
--------

What now? \fIedit\fR
What now? \fIsend\fR
...
.fi
.in -.5i
.sp
The \fIedit\fR command invokes \fImhn\fR automatically.

@END: MIME
The `\-draftfolder\ +folder' and `\-draftmessage\ msg' switches invoke the
\fIMH\fR draft folder facility.
This is an advanced (and highly useful) feature.
Consult the \fBAdvanced Features\fR section of the \fIMH\fR manual for more
information.

Upon exiting from the editor,
\fIforw\fR will invoke the \fIwhatnow\fR program.
See \fIwhatnow\fR\0(1) for a discussion of available options.
The invocation of this program can be inhibited by using the `\-nowhatnowproc'
switch.
(In truth of fact,
it is the \fIwhatnow\fR program which starts the initial edit.
Hence, `\-nowhatnowproc' will prevent any edit from occurring.)

The `\-digest\ list', `\-issue\ number', and `\-volume\ number' switches
implement a digest facility for \fIMH\fR.  Specifying these switches
enables and/or overloads the following escapes:
.sp 1
.nf
.ta \w'Component  'u +\w'Escape  'u +\w'Returns  'u
\fIType\fR	\fIEscape\fR	\fIReturns\fR	\fIDescription\fR
\fIcomponent\fR	\fIdigest\fR	string	Argument to `\-digest'
\fIfunction\fR	\fIcur\fR	integer	Argument to `\-volume'
\fIfunction\fR	\fImsg\fR	integer	Argument to `\-issue'
.re
.fi

Consult the \fBAdvanced Features\fR section of 
the \fIMH\fR User's Manual for more information on making digests.
.Fi
^@(MHETCPATH)/forwcomps~^The message skeleton
^or <mh\-dir>/forwcomps~^Rather than the standard skeleton
^@(MHETCPATH)/digestcomps~^The message skeleton if `\-digest' is given
^or <mh\-dir>/digestcomps~^Rather than the standard skeleton
^@(MHETCPATH)/mhl.forward~^The message filter
^or <mh\-dir>/mhl.forward~^Rather than the standard filter
^$HOME/\&.mh\(ruprofile~^The user profile
^<mh\-dir>/draft~^The draft file
.Pr
^Path:~^To determine the user's MH directory
.Ps
^Current\-Folder:~^To find the default current folder
.Ps
^Draft\-Folder:~^To find the default draft\-folder
.Ps
^Editor:~^To override the default editor
.Ps
^Msg\-Protect:~^To set mode when creating a new message (draft)
.Ps
^fileproc:~^Program to refile the message
.Ps
^mhlproc:~^Program to filter messages being forwarded
.Ps
^whatnowproc:~^Program to ask the \*(lqWhat now?\*(rq questions
.Sa
\fIProposed Standard for Message Encapsulation\fR (aka RFC\-934),
.br
comp(1), dist(1), repl(1), send(1), whatnow(1), mh\-format(5)
.De
`+folder' defaults to the current folder
`msgs' defaults to cur
.Ds
`\-noannotate'
.Ds
`\-nodraftfolder'
.Ds
`\-noformat'
.Ds
`\-noinplace'
@BEGIN: MIME
.Ds
`\-nomime'
@END: MIME
.Co
If a folder is given, it will become the current folder.
The first message forwarded will become the current message.
.Bu
If \fIwhatnowproc\fR is \fIwhatnow\fR,
then \fIforw\fR uses a built\-in \fIwhatnow\fR,
it does not actually run the \fIwhatnow\fR program.
Hence, if you define your own \fIwhatnowproc\fR,
don't call it \fIwhatnow\fR since \fIforw\fR won't run it.

When \fIforw\fR is told to annotate the messages it forwards,
it doesn't actually annotate them until the draft is successfully sent.
If from the \fIwhatnowproc\fR,
you \fIpush\fR instead of \fIsend\fR,
it's possible to confuse \fIforw\fR by re\-ordering the file
(e.g., by using `folder\0\-pack') before the message is successfully sent.
\fIDist\fR and \fIrepl\fR don't have this problem.

To avoid prepending the leading dash characters in forwarded messages,
there is a `\-nodashmunging' option.  See the \*(lqHidden Features\*(rq
section of the \fIMH Administrator's Guide\fR for more details.
.En