new.c: Order two return statements to match comment.

[nmh] / man / forw.man

diff --git a/man/forw.man b/man/forw.man
index 8561d93be1e9424bec175250707dbb31bd7062de..d21fe580ab660947d588453eeb96caf977b953c9 100644 (file)
--- a/man/forw.man
+++ b/man/forw.man
@@ -1,16 +1,18 @@
-.\"
+.TH FORW %manext1% 2013-03-22 "%nmhversion%"
+.

 .\" %nmhwarning%
 .\" %nmhwarning%

-.\" $Id$
-.\"
-.TH FORW %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
+.

 .SH NAME
 .SH NAME

-forw \- forward messages
+forw \- forward nmh messages

 .SH SYNOPSIS
 .HP 5
 .SH SYNOPSIS
 .HP 5

+.na

 .B forw
 .B forw

+.RB [ \-help ]
+.RB [ \-version ]

 .RI [ +folder ]
 .RI [ msgs ]
 .RI [ +folder ]
 .RI [ msgs ]

-.RB [ \-annotate " | " \-noannotate ] 
+.RB [ \-annotate " | " \-noannotate ]

 .RB [ \-form
 .IR formfile ]
 .RB [ \-format " | " \-noformat ]
 .RB [ \-form
 .IR formfile ]
 .RB [ \-format " | " \-noformat ]


@@ -26,6 +28,18 @@ forw \- forward messages
 .RB [ \-editor
 .IR editor ]
 .RB [ \-noedit ]
 .RB [ \-editor
 .IR editor ]
 .RB [ \-noedit ]

+.RB [ \-width
+.IR columns ]
+.RB [ \-from
+.IR address ]
+.RB [ \-to
+.IR address ]
+.RB [ \-cc
+.IR address ]
+.RB [ \-fcc
+.IR +folder ]
+.RB [ \-subject
+.IR text ]

 .RB [ \-whatnowproc
 .IR program ]
 .RB [ \-nowhatnowproc ]
 .RB [ \-whatnowproc
 .IR program ]
 .RB [ \-nowhatnowproc ]


@@ -33,11 +47,10 @@ forw \- forward messages
 .RB [ \-build ]
 .RB [ \-file
 .IR msgfile ]
 .RB [ \-build ]
 .RB [ \-file
 .IR msgfile ]

-.RB [ \-version ]
-.RB [ \-help ]
-.PP

 .HP 5
 .B forw
 .HP 5
 .B forw

+.RB [ \-help ]
+.RB [ \-version ]

 .RI [ +folder ]
 .RI [ msgs ]
 .RB [ \-digest
 .RI [ +folder ]
 .RI [ msgs ]
 .RB [ \-digest


@@ -46,26 +59,27 @@ forw \- forward messages
 .IR number ]
 .RB [ \-volume
 .IR number ]
 .IR number ]
 .RB [ \-volume
 .IR number ]

-[other\ switches\ for\ 
+[other\ switches\ for\

 .BR forw ]
 .BR forw ]

-.RB [ \-version ]
-.RB [ \-help ]
+.ad

 .SH DESCRIPTION
 .SH DESCRIPTION

-.B Forw
-may be used to prepare a message containing other messages.
-.PP
-It constructs the new message from a forms (components) file, with a
-body composed of the message(s) to be forwarded.  An editor is invoked
-as in
-.BR comp ,
-and after editing is complete, the user is prompted
-before the message is sent.
+.B forw
+constructs a new message from a forms (components) file, with a body
+composed of the message(s) to be forwarded.  An editor is invoked
+and, after editing is complete, the user is prompted before the
+message is sent.

 .PP
 .PP

-The default message form contains the following elements:
+The default message template will direct
+.B forw
+to construct the draft as follows:

 .PP
 .RS 5
 .nf
 .PP
 .RS 5
 .nf

-%forwcomps%
+From: {from switch} or <Local-Mailbox> or <username@hostname>
+To: {to switch} or blank
+Fcc: {fcc switch} or +outbox
+Subject: {subject switch} or "{original subject} (fwd)"
+--------

 .fi
 .RE
 .PP
 .fi
 .RE
 .PP


@@ -76,11 +90,60 @@ it will be used instead of this default form.  You may also specify an
 alternate forms file with the switch
 .B \-form
 .IR formfile .
 alternate forms file with the switch
 .B \-form
 .IR formfile .

+Forms are processed via the
+.B nmh
+template system; see
+.IR mh\-format (5)
+for details.  Components from the first forwarded message are available
+as standard component escapes in the forms file.
+.PP
+In addition to the standard
+.I mh\-format
+escapes, the following
+.I component
+escapes are also supported:
+.PP
+.RS 5
+.nf
+.ta \w'nmh\-subject    'u +\w'Returns  'u
+.I "Escape     Returns Description"
+fcc    string  Any folders specified with `\-fcc\ folder'
+nmh\-from      string  Addresses specified with `\-from\ address'
+nmh\-to        string  Addresses specified with `\-to\ address'
+nmh\-cc        string  Addresses specified with `\-cc\ address'
+nmh\-subject   string  Any text specified with `\-subject\ text'
+.fi
+.RE
+.PP
+By default, the \*(lqTo:\*(rq and \*(lqcc:\*(rq fields are empty.  You may
+add addresses to these fields with the
+.B \-to
+.I address
+and
+.B \-cc
+.I address
+switches.  You may give these switches multiple times to add multiple
+addresses.
+.PP
+By default, the \*(lqFrom:\*(rq field contains either the value of the
+.B Local\-Mailbox
+profile entry, or a system default email address.
+This default can be overridden by using the
+.B \-from
+.I address
+switch.  The default mailbox in the \*(lqFcc:\*(rq field is
+.IR +outbox .
+This can be overridden by the
+.B \-fcc
+switch.
+.PP
+Any text given to the
+.B \-subject
+switch will be placed in the \*(lqSubject:\*(rq field in the draft.

 .PP
 If the draft already exists,
 .B forw
 .PP
 If the draft already exists,
 .B forw

-will ask you as to the disposition
-of the draft.  A reply of
+will ask you as to the disposition of the draft.  A reply of

 .B quit
 will abort
 .BR forw ,
 .B quit
 will abort
 .BR forw ,


@@ -92,28 +155,32 @@ will display the draft.
 .PP
 If the
 .B \-annotate
 .PP
 If the
 .B \-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
+switch is given, each message being forwarded will be annotated
+with the lines:
+.PP
+.RS 5
+.nf
+Forwarded:\ date
+Forwarded:\ addrs
+.fi
+.RE
+.PP
+where each address list contains as many lines as required.
+This annotation will be done only if the message is sent directly from

 .BR forw .
 If the message is not sent immediately from
 .BR forw ,
 .RB \*(lq comp
 .BR \-use \*(rq
 .BR forw .
 If the message is not sent immediately from
 .BR forw ,
 .RB \*(lq comp
 .BR \-use \*(rq

-may be used to re\-edit and send the constructed
-message, but the annotations won't take place.  Normally annotations
-are done inplace in order to preserve any links to the message.  You may
-change this by using the
+may be used to re-edit and send the constructed message, but the
+annotations won't take place.  Normally, annotations are done in place
+in order to preserve any links to the message.
+You may change this by using the

 .B \-noinplace
 switch.
 .PP
 See
 .B \-noinplace
 switch.
 .PP
 See

-.BR comp (1)
+.IR comp (1)

 for a description of the
 .B \-editor
 and
 for a description of the
 .B \-editor
 and


@@ -122,17 +189,16 @@ switches.
 .PP
 Although
 .B forw
 .PP
 Although
 .B forw

-uses a forms (components) file to direct it how to
-construct the beginning of the draft, it uses a message filter file to
-direct it as to how each forwarded message should be formatted in the
-body of the draft.  The filter file for \fIforw\fR should be a standard
-form file for
-.BR mhl ,
+uses a forms (components) file to construct the initial draft,
+a message filter file is used to format each forwarded message in the
+body of the draft.
+The filter file for \fIforw\fR should be a standard form file for
+.IR mhl (1),

 as
 .B forw
 will invoke
 .B mhl
 as
 .B forw
 will invoke
 .B mhl

-to filter (re\-format) the forwarded messages prior to being output to
+to filter (re-format) the forwarded messages prior to being output to

 the body of the draft.
 .PP
 The switches
 the body of the draft.
 .PP
 The switches


@@ -141,22 +207,16 @@ The switches
 and
 .B \-filter
 .I filterfile
 and
 .B \-filter
 .I filterfile

-specify which message filter file to use.
-.PP
-If
+specify which message filter file to use.  If

 .B \-noformat
 is specified (this is the default), then each forwarded
 .B \-noformat
 is specified (this is the default), then each forwarded

-message is output into the draft exactly as it appears with no
+message is output into the draft exactly as it appears, with no

 .B mhl
 .B mhl

-filtering.
-.PP
-If
+filtering.  If

 .B \-format
 .B \-format

-is specified, then a default message filter file is used.
-This default message filter should be adequate for most users.
-This default filter
-.RI \*(lq mhl.forward \*(rq
-is:
+is specified, then the following default message filter file,
+.RI \*(lq mhl.forward \*(rq ,
+which should be adequate for most users, is used:

 .PP
 .RS 5
 .nf
 .PP
 .RS 5
 .nf


@@ -167,7 +227,7 @@ is:
 If a file named
 .RI \*(lq mhl.forward \*(rq
 exists in the user's nmh
 If a file named
 .RI \*(lq mhl.forward \*(rq
 exists in the user's nmh

-directory, it will be used instead of this form.  You may specify an
+directory, it will be used instead.  You may specify an

 alternate message filter file with the switch
 .B \-filter
 .IR filterfile .
 alternate message filter file with the switch
 .B \-filter
 .IR filterfile .


@@ -176,44 +236,31 @@ Each forwarded message is separated with an encapsulation delimiter.
 By default, any dashes in the first column of the forwarded messages
 will be prepended with `\-\ ' so that when received, the message is
 suitable for bursting by
 By default, any dashes in the first column of the forwarded messages
 will be prepended with `\-\ ' so that when received, the message is
 suitable for bursting by

-.BR burst .
-This follows the Internet RFC\-934 guidelines.  You may use the flag
+.IR burst (1).
+This follows the guidelines in RFC 934.  You may use the

 .B \-nodashstuffing
 .B \-nodashstuffing

-in order
-to suppress this form of quoting to the forwarded messages.
+switch to suppress this form of quoting.

 .PP
 .PP

-For users of
-.BR prompter ,
-by specifying
+Users of
+.IR prompter (1)
+can, by specifying

 .BR prompter 's
 .B \-prepend
 switch in the
 .BR prompter 's
 .B \-prepend
 switch in the

-.I \&.mh\(ruprofile
-file, any commentary text is entered
-before the forwarded messages.  (A major win!)
+.I \&.mh_profile
+file, prepend any commentary text before the forwarded messages.

 .PP
 To use the MIME rules for encapsulation, specify the
 .B \-mime
 .PP
 To use the MIME rules for encapsulation, specify the
 .B \-mime

-switch. This directs
+switch.  This directs

 .B forw
 to generate an
 .B mhbuild
 .B forw
 to generate an
 .B mhbuild

-composition file. Note that
+composition file.  Note that

 .B nmh
 will not invoke
 .B mhbuild
 .B nmh
 will not invoke
 .B mhbuild

-automatically, unless you
-add this line to your
-.I \&.mh\(ruprofile
-file:
-.PP
-.RS 5
-.nf
-automimeproc: 1
-.fi
-.RE
-.PP
-Otherwise, you must specifically give the command
+automatically; you must specifically give the command

 .PP
 .RS 5
 .nf
 .PP
 .RS 5
 .nf


@@ -231,27 +278,26 @@ and
 .I msg
 switches invoke the
 .B nmh
 .I msg
 switches invoke the
 .B nmh

-draft folder facility.  This is an advanced (and highly
-useful) feature.  Consult the
-.BR mh-draft (5)
-man page for more information.
+draft folder facility.  This is an advanced (and highly useful) feature.
+Consult
+.IR mh-draft (5)
+for more information.

 .PP
 The
 .B \-editor
 .I editor
 .PP
 The
 .B \-editor
 .I editor

-switch indicates the editor to use for the
-initial edit.  Upon exiting from the editor,
+switch indicates the editor to use for the initial edit.
+Upon exiting from the editor,

 .B comp
 will invoke the
 .B whatnow
 program.  See
 .B comp
 will invoke the
 .B whatnow
 program.  See

-.BR whatnow (1)
+.IR whatnow (1)

 for a discussion of
 for a discussion of

-available options.  The invocation of this program can be inhibited
-by using the
+available options.
+The invocation of this program can be inhibited by using the

 .B \-nowhatnowproc
 .B \-nowhatnowproc

-switch.  (In truth of fact, it is
-the
+switch.  (In fact, it is the

 .I whatnow
 program which starts the initial edit.  Hence,
 .B \-nowhatnowproc
 .I whatnow
 program which starts the initial edit.  Hence,
 .B \-nowhatnowproc


@@ -260,41 +306,29 @@ will prevent any edit from occurring.)
 The
 .B \-build
 switch is intended to be used by the Emacs mh-e interface to
 The
 .B \-build
 switch is intended to be used by the Emacs mh-e interface to

-.BR nmh ,
-and is only present if
-.B nmh
-was compiled with support for mh-e. It implies
+.BR nmh .
+It implies

 .BR \-nowhatnowproc .
 .BR \-nowhatnowproc .

-It causes a file <mh\-dir>/draft
-to be created, containing the draft message that would normally be presented
-to the user for editing.
-No mail is actually sent. Note that this switch is not guaranteed to
-be present or to have the same effects in future versions of
-.BR nmh :
-it is documented here only for completeness.
+It causes a file <mh-dir>/draft
+to be created, containing the draft message that would normally be
+presented to the user for editing.  No mail is actually sent.

 .PP
 The
 .B \-file
 .I msgfile
 .PP
 The
 .B \-file
 .I msgfile

-switch specifies the message to be forwarded as an 
-exact filename rather than as an
+switch specifies the message to be forwarded as an exact filename
+rather than as an

 .B nmh
 .B nmh

-folder and message number. It is 
-intended to be used by the
-.B msh
-interface to
-.BR nmh . 
-This switch implies
+folder and message number.  This switch implies

 .BR \-noannotate .
 .BR \-noannotate .

-The forwarded message is simply
-copied verbatim into the draft; the processing implied by
-the
+The forwarded message is simply copied verbatim into the draft;
+the processing implied by the

 .BR \-filter ,
 .BR \-mime ,
 and
 .B \-digest
 .BR \-filter ,
 .BR \-mime ,
 and
 .B \-digest

-switches is bypassed, and the usual leading and trailing
-'Forwarded Message' delimiters are not added.
+switches is bypassed, and the usual leading and
+trailing 'Forwarded Message' delimiters are not added.

 The same caveats apply to this option as to the
 .B \-build
 switch.
 The same caveats apply to this option as to the
 .B \-build
 switch.


@@ -314,69 +348,114 @@ Specifying these switches enables and/or overloads the following escapes:
 .RS 5
 .nf
 .ta \w'Component  'u +\w'Escape  'u +\w'Returns  'u
 .RS 5
 .nf
 .ta \w'Component  'u +\w'Escape  'u +\w'Returns  'u

-.I Type        Escape  Returns Description
+.I "Type       Escape  Returns Description"

 component      digest  string  Argument to `\-digest'
 function       cur     integer Argument to `\-volume'
 function       msg     integer Argument to `\-issue'
 .fi
 .RE
 component      digest  string  Argument to `\-digest'
 function       cur     integer Argument to `\-volume'
 function       msg     integer Argument to `\-issue'
 .fi
 .RE

-.PP
-Consult the
-.I "Advanced Features"
-section of the
-.B nmh
-User's Manual for more information on making digests.
-

 .SH FILES
 .SH FILES

-.fc ^ ~
-.nf
-.ta \w'/usr/local/nmh/etc/ExtraBigFileName  'u
-^%etcdir%/forwcomps~^The standard message skeleton
-^or <mh\-dir>/forwcomps~^Rather than the standard skeleton
-^%etcdir%/digestcomps~^The message skeleton if `\-digest' is given
-^or <mh\-dir>/digestcomps~^Rather than the standard skeleton
-^%etcdir%/mhl.forward~^The standard message filter
-^or <mh\-dir>/mhl.forward~^Rather than the standard filter
-^$HOME/\&.mh\(ruprofile~^The user profile
-^<mh\-dir>/draft~^The draft file
-.fi
-
+.B forw
+looks for format and filter files in multiple locations: absolute
+pathnames are accessed directly, tilde expansion is done on usernames,
+and files are searched for in the user's
+.I Mail
+directory as specified in their profile.  If not found there, the directory
+.RI \*(lq %nmhetcdir% \*(rq
+is checked.
+.PP
+.PD 0
+.TP 25
+%nmhetcdir%/forwcomps
+The default message skeleton.
+.TP
+<mh-dir>/forwcomps
+The user's message skeleton.
+.TP
+%nmhetcdir%/digestcomps
+The default message skeleton if
+.B \-digest
+is given.
+.TP
+<mh-dir>/digestcomps
+The user's
+.B \-digest
+skeleton.
+.TP
+^%nmhetcdir%/mhl.forward
+The default message filter.
+.TP
+<mh-dir>/mhl.forward
+The user's message filter.
+.TP
+^$HOME/.mh_profile
+The user's profile.
+.PD

 .SH "PROFILE COMPONENTS"
 .SH "PROFILE COMPONENTS"

-.fc ^ ~
-.nf
-.ta 2.4i
-.ta \w'ExtraBigProfileName  'u
-^Path:~^To determine the user's nmh directory
-^Current\-Folder:~^To find the default current folder
-^Draft\-Folder:~^To find the default draft\-folder
-^Editor:~^To override the default editor
-^Msg\-Protect:~^To set mode when creating a new message (draft)
-^fileproc:~^Program to refile the message
-^mhlproc:~^Program to filter messages being forwarded
-^whatnowproc:~^Program to ask the \*(lqWhat now?\*(rq questions
-.fi
-
+.PD 0
+.TP 25
+Path:
+To determine the user's nmh directory.
+.TP
+Current\-Folder:
+To find the default current folder.
+.TP
+Draft\-Folder:
+To find the default draft-folder.
+.TP
+Editor:
+To override the default editor.
+.TP
+Msg\-Protect:
+To set mode when creating a new message (draft).
+.TP
+fileproc:
+Program to refile the message.
+.TP
+mhlproc:
+Program to filter messages being forwarded.
+.TP
+whatnowproc:
+Program to ask the \*(lqWhat now?\*(rq questions.
+.PD

 .SH "SEE ALSO"
 .SH "SEE ALSO"

-mhbuild(1), comp(1), repl(1), send(1), whatnow(1), mh\-format(5),
-.I "Proposed Standard for Message Encapsulation"
-(RFC\-934)
-
+.IR burst (1),
+.IR comp (1),
+.IR mh\-format (5),
+.IR mhbuild (1),
+.IR mhl (1),
+.IR prompter (1),
+.IR repl (1),
+.IR send (1),
+.IR whatnow (1)
+.PP
+.I
+Proposed Standard for Message Encapsulation
+(RFC 934)

 .SH DEFAULTS
 .SH DEFAULTS

-.nf
-.RB ` +folder "' defaults to the current folder"
-.RB ` msgs "' defaults to cur"
-.RB ` \-noannotate '
-.RB ` \-nodraftfolder '
-.RB ` \-noformat '
-.RB ` \-inplace '
-.RB ` \-dashstuffing '
-.RB ` \-nomime '
-.fi
-
+.PD 0
+.TP 25
++folder
+The current folder.
+.TP
+msgs
+The current message.
+.TP
+\-noannotate
+.TP
+\-nodraftfolder
+.TP
+\-noformat
+.TP
+\-inplace
+.TP
+\-dashstuffing
+.TP
+\-nomime
+.PD

 .SH CONTEXT
 If a folder is given, it will become the current folder.
 The first message forwarded will become the current message.
 .SH CONTEXT
 If a folder is given, it will become the current folder.
 The first message forwarded will become the current message.

-

 .SH BUGS
 If
 .I whatnowproc
 .SH BUGS
 If
 .I whatnowproc


@@ -384,7 +463,7 @@ is
 .BR whatnow ,
 then
 .B forw
 .BR whatnow ,
 then
 .B forw

-uses a built\-in
+uses a built-in

 .BR whatnow ,
 it does not actually run the
 .B whatnow
 .BR whatnow ,
 it does not actually run the
 .B whatnow


@@ -399,21 +478,21 @@ won't run it.
 .PP
 When
 .B forw
 .PP
 When
 .B forw

-is told to annotate the messages it forwards, it
-doesn't actually annotate them until the draft is successfully sent.
-If from the
+is told to annotate the messages it forwards, it doesn't actually
+annotate them until the draft is successfully sent.
+If, from the

 .IR whatnowproc ,
 you
 .B push
 instead of
 .BR send ,
 .IR whatnowproc ,
 you
 .B push
 instead of
 .BR send ,

-it's possible to confuse
+it is possible to confuse

 .B forw
 .B forw

-by re\-ordering the file (e.g. by using
+by re-ordering the file (e.g.\& by using

 .RB \*(lq folder
 .BR \-pack \*(rq)
 before the message is successfully sent.
 .RB \*(lq folder
 .BR \-pack \*(rq)
 before the message is successfully sent.

-.B Dist
+.B dist

 and
 .B repl
 don't have this problem.
 and
 .B repl
 don't have this problem.