X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/3d7993e40a34f52e2b6394c2f64ef0111ab886f7..a9bb157da7d3cee576e8944eaf8fab2bdbc4be8d:/man/forw.man?ds=sidebyside diff --git a/man/forw.man b/man/forw.man index 6d490534..8b792d8f 100644 --- a/man/forw.man +++ b/man/forw.man @@ -1,17 +1,18 @@ -.\" +.TH FORW %manext1% 2013-03-22 "%nmhversion%" +. .\" %nmhwarning% -.\" $Id$ -.\" -.TH FORW %manext1% "%nmhdate%" MH.6.8 [%nmhversion%] +. .SH NAME -forw \- forward messages +forw \- forward nmh messages .SH SYNOPSIS .HP 5 .na .B forw +.RB [ \-help ] +.RB [ \-version ] .RI [ +folder ] .RI [ msgs ] -.RB [ \-annotate " | " \-noannotate ] +.RB [ \-annotate " | " \-noannotate ] .RB [ \-form .IR formfile ] .RB [ \-format " | " \-noformat ] @@ -27,6 +28,18 @@ forw \- forward messages .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 ] @@ -34,11 +47,10 @@ forw \- forward messages .RB [ \-build ] .RB [ \-file .IR msgfile ] -.RB [ \-version ] -.RB [ \-help ] -.PP .HP 5 .B forw +.RB [ \-help ] +.RB [ \-version ] .RI [ +folder ] .RI [ msgs ] .RB [ \-digest @@ -47,27 +59,27 @@ forw \- forward messages .IR number ] .RB [ \-volume .IR number ] -[other\ switches\ for\ +[other\ switches\ for\ .BR forw ] -.RB [ \-version ] -.RB [ \-help ] .ad .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 -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 -%forwcomps% +From: {from switch} or or +To: {to switch} or blank +Fcc: {fcc switch} or +outbox +Subject: {subject switch} or "{original subject} (fwd)" +-------- .fi .RE .PP @@ -78,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 . +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 -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 , @@ -94,28 +155,32 @@ will display the draft. .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 -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 -.BR comp (1) +.IR comp (1) for a description of the .B \-editor and @@ -124,17 +189,16 @@ switches. .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 -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 @@ -143,22 +207,16 @@ The switches 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 -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 -filtering. -.PP -If +filtering. If .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 @@ -169,7 +227,7 @@ is: 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 . @@ -178,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 -.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 -in order -to suppress this form of quoting to the forwarded messages. +switch to suppress this form of quoting. .PP -For users of -.BR prompter , -by specifying +Users of +.IR prompter (1) +can, by specifying .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 -switch. This directs +switch. This directs .B forw to generate an .B mhbuild -composition file. Note that +composition file. Note that .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 @@ -233,27 +278,26 @@ and .I msg switches invoke the .B nmh -draft folder facility. This is an advanced (and highly -useful) feature. Consult the -.BR mh-draft (5) +draft folder facility. This is an advanced (and highly useful) feature. +Consult the +.IR mh-draft (5) man page for more information. .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 -.BR whatnow (1) +.IR whatnow (1) 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 -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 @@ -262,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 -.BR nmh , -and is only present if -.B nmh -was compiled with support for mh-e. It implies +.BR nmh . +It implies .BR \-nowhatnowproc . -It causes a file /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 /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 -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 -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 . -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 -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. @@ -316,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 -.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 -.PP -Consult the -.I "Advanced Features" -section of the -.B nmh -User's Manual for more information on making digests. - .SH FILES -.fc ^ ~ -.nf -.ta \w'/usr/local/nmh/etc/ExtraBigFileName 'u -^%etcdir%/forwcomps~^The standard message skeleton -^or /forwcomps~^Rather than the standard skeleton -^%etcdir%/digestcomps~^The message skeleton if `\-digest' is given -^or /digestcomps~^Rather than the standard skeleton -^%etcdir%/mhl.forward~^The standard message filter -^or /mhl.forward~^Rather than the standard filter -^$HOME/\&.mh\(ruprofile~^The user profile -^/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 +/forwcomps +The user's message skeleton. +.TP +%nmhetcdir%/digestcomps +The default message skeleton if +.B \-digest +is given. +.TP +/digestcomps +The user's +.B \-digest +skeleton. +.TP +^%nmhetcdir%/mhl.forward +The default message filter. +.TP +/mhl.forward +The user's message filter. +.TP +^$HOME/.mh_profile +The user's profile. +.PD .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" -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 -.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 BUGS If .I whatnowproc @@ -386,7 +463,7 @@ is .BR whatnow , then .B forw -uses a built\-in +uses a built-in .BR whatnow , it does not actually run the .B whatnow @@ -401,21 +478,21 @@ won't run it. .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 , -it's possible to confuse +it is possible to confuse .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. -.B Dist +.B dist and .B repl don't have this problem.