Factor trim format function out
[mmh] / man / forw.man1
1 .\"
2 .\" %nmhwarning%
3 .\"
4 .TH FORW %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
5 .SH NAME
6 forw \- forward messages
7 .SH SYNOPSIS
8 .HP 5
9 .na
10 .B forw
11 .RI [ +folder ]
12 .RI [ msgs ]
13 .RB [ \-annotate " | " \-noannotate ]
14 .RB [ \-form
15 .IR formfile ]
16 .RB [ \-editor
17 .IR editor ]
18 .RB [ \-whatnowproc
19 .IR program ]
20 .RB [ \-build ]
21 .RB [ \-Version ]
22 .RB [ \-help ]
23 .PP
24 .HP 5
25 .B forw
26 .RI [ +folder ]
27 .RI [ msgs ]
28 .RB [ \-digest
29 .IR list ]
30 .RB [ \-issue
31 .IR number ]
32 .RB [ \-volume
33 .IR number ]
34 [other\ switches\ for
35 .BR forw ]
36 .RB [ \-Version ]
37 .RB [ \-help ]
38 .ad
39 .SH DESCRIPTION
40 .B Forw
41 may be used to prepare a message containing other messages.
42 .PP
43 It constructs the new message from a forms (components) file, with a
44 body composed of the message(s) to be forwarded.  An editor is invoked
45 as in
46 .BR comp ,
47 and after editing is complete, the user is prompted
48 before the message is sent.
49 .PP
50 The default message form contains the following elements:
51 .PP
52 .RS 5
53 .nf
54 %forwcomps%
55 .fi
56 .RE
57 .PP
58 If a file named
59 .RI ` forwcomps '
60 exists in the user's mmh directory,
61 it will be used instead of this default form.  You may also specify an
62 alternate forms file with the switch
63 .B \-form
64 .IR formfile .
65 .PP
66 If the
67 .B \-annotate
68 switch is given, each message being forwarded will
69 be annotated with the line:
70 .PP
71 .RS 5
72 .nf
73 Forwarded:\ date
74 .fi
75 .RE
76 .PP
77 This annotation will be done only if the message is sent directly from
78 .BR forw .
79 If the message is not sent immediately from
80 .BR forw ,
81 .RB ` comp
82 .BR \-use '
83 may be used to re\-edit and send the constructed
84 message, but the annotations won't take place.  Annotations
85 are always done inplace in order to preserve any links to the message.
86 .PP
87 See
88 .BR comp (1)
89 for a description of the
90 .B \-editor
91 switch.
92 .PP
93 .B Forw
94 generates an attachment header field for the messages to be forwarded.
95 .B Send
96 will care to encapsulate them using MIME rules.
97 .PP
98 To send non-MIME forwarded messages, compose a new message (e.g. with
99 .B comp )
100 and read in the output of:
101 .PP
102 .RS 5
103 mhl \-forwall \-form mhl.forward `mhpath
104 .I MSGS... `
105 .RE
106 .PP
107 The
108 .B \-editor
109 .I editor
110 switch indicates the editor to use for the
111 initial edit.  Upon exiting from the editor,
112 .B comp
113 will invoke the
114 .B whatnow
115 program.  See
116 .BR whatnow (1)
117 for a discussion of
118 available options.
119 .PP
120 The
121 .B \-build
122 switch is intended to be used by the Emacs mh-e interface to
123 .BR nmh .
124 It causes a file `draft' in the mail storage root
125 to be created, containing the draft message that would normally be presented
126 to the user for editing.
127 No
128 .B whatnow
129 program is invoked.
130 No mail is actually sent.
131 .PP
132 The
133 .B \-digest
134 .IR list ,
135 .B \-issue
136 .IR number ,
137 and
138 .B \-volume
139 .I number
140 switches implement a digest facility for
141 .BR mmh .
142 Specifying these switches enables and/or overloads the following escapes:
143 .PP
144 .RS 5
145 .nf
146 .ta \w'Component  'u +\w'Escape  'u +\w'Returns  'u
147 .I "Type        Escape  Returns Description
148 component       digest  string  Argument to `\-digest'
149 function        cur     integer Argument to `\-volume'
150 function        msg     integer Argument to `\-issue'
151 .fi
152 .RE
153 .PP
154 Consult the
155 .I "Advanced Features"
156 section of the
157 .B nmh
158 User's Manual for more information on making digests.
159
160 .SH FILES
161 .fc ^ ~
162 .nf
163 .ta \w'%etcdir%/ExtraBigFileName  'u
164 ^%etcdir%/forwcomps~^The standard message skeleton
165 ^or $HOME/.mmh/forwcomps~^Rather than the standard skeleton
166 ^%etcdir%/digestcomps~^The message skeleton if `\-digest' is given
167 ^or $HOME/.mmh/digestcomps~^Rather than the standard skeleton
168 ^$HOME/.mmh/profile~^The user profile
169 ^+drafts~^The draft folder
170 .fi
171
172 .SH "PROFILE COMPONENTS"
173 .fc ^ ~
174 .nf
175 .ta 2.4i
176 .ta \w'ExtraBigProfileName  'u
177 ^Path:~^To determine the user's mail storage
178 ^Current\-Folder:~^To find the default current folder
179 ^Draft\-Folder:~^To set the default draft\-folder
180 ^Editor:~^To override the default editor
181 ^Msg\-Protect:~^To set mode when creating a new message (draft)
182 ^whatnowproc:~^Program to ask the `What now?' questions
183 .fi
184
185 .SH "SEE ALSO"
186 mhbuild(1), comp(1), repl(1), send(1), whatnow(1), mh\-format(5),
187 .I "Proposed Standard for Message Encapsulation"
188 (RFC\-934)
189
190 .SH DEFAULTS
191 .nf
192 .RB ` +folder "' defaults to the current folder"
193 .RB ` msgs "' defaults to the current message"
194 .RB ` \-noannotate '
195 .fi
196
197 .SH CONTEXT
198 If a folder is given, it will become the current folder.
199 The first message forwarded will become the current message.
200
201 .SH BUGS
202 When
203 .B forw
204 is told to annotate the messages it forwards, it
205 doesn't actually annotate them until the draft is successfully sent.
206 If from the
207 .IR whatnowproc ,
208 you
209 .B push
210 instead of
211 .BR send ,
212 it's possible to confuse
213 .B forw
214 by re\-ordering the file (e.g. by using
215 .RB ` folder
216 .BR \-pack ')
217 before the message is successfully sent.
218 .B Dist
219 and
220 .B repl
221 don't have this problem.