diplodocus.org Git - nmh/blob - man/forw.man

   1 .TH FORW %manext1% 2013-03-22 "%nmhversion%"
   2 .
   3 .\" %nmhwarning%
   4 .
   5 .SH NAME
   6 forw \- forward nmh messages
   7 .SH SYNOPSIS
   8 .HP 5
   9 .na
  10 .B forw
  11 .RB [ \-help ]
  12 .RB [ \-version ]
  13 .RI [ +folder ]
  14 .RI [ msgs ]
  15 .RB [ \-annotate " | " \-noannotate ]
  16 .RB [ \-form
  17 .IR formfile ]
  18 .RB [ \-format " | " \-noformat ]
  19 .RB [ \-filter
  20 .IR filterfile ]
  21 .RB [ \-inplace " | " \-noinplace ]
  22 .RB [ \-mime " | " \-nomime ]
  23 .RB [ \-draftfolder
  24 .IR +folder ]
  25 .RB [ \-draftmessage
  26 .IR msg ]
  27 .RB [ \-nodraftfolder ]
  28 .RB [ \-editor
  29 .IR editor ]
  30 .RB [ \-noedit ]
  31 .RB [ \-width
  32 .IR columns ]
  33 .RB [ \-from
  34 .IR address ]
  35 .RB [ \-to
  36 .IR address ]
  37 .RB [ \-cc
  38 .IR address ]
  39 .RB [ \-fcc
  40 .IR +folder ]
  41 .RB [ \-subject
  42 .IR text ]
  43 .RB [ \-whatnowproc
  44 .IR program ]
  45 .RB [ \-nowhatnowproc ]
  46 .RB [ \-dashstuffing " | " \-nodashstuffing ]
  47 .RB [ \-build ]
  48 .RB [ \-file
  49 .IR msgfile ]
  50 .HP 5
  51 .B forw
  52 .RB [ \-help ]
  53 .RB [ \-version ]
  54 .RI [ +folder ]
  55 .RI [ msgs ]
  56 .RB [ \-digest
  57 .IR list ]
  58 .RB [ \-issue
  59 .IR number ]
  60 .RB [ \-volume
  61 .IR number ]
  62 [other\ switches\ for\
  63 .BR forw ]
  64 .ad
  65 .SH DESCRIPTION
  66 .B forw
  67 constructs a new message from a forms (components) file, with a body
  68 composed of the message(s) to be forwarded.  An editor is invoked
  69 and, after editing is complete, the user is prompted before the
  70 message is sent.
  71 .PP
  72 The default message template will direct
  73 .B forw
  74 to construct the draft as follows:
  75 .PP
  76 .RS 5
  77 .nf
  78 From: {from switch} or <Local-Mailbox> or <username@hostname>
  79 To: {to switch} or blank
  80 Fcc: {fcc switch} or +outbox
  81 Subject: {subject switch} or "{original subject} (fwd)"
  82 --------
  83 .fi
  84 .RE
  85 .PP
  86 If a file named
  87 .RI \*(lq forwcomps \*(rq
  88 exists in the user's nmh directory,
  89 it will be used instead of this default form.  You may also specify an
  90 alternate forms file with the switch
  91 .B \-form
  92 .IR formfile .
  93 Forms are processed via the
  94 .B nmh
  95 template system; see
  96 .IR mh\-format (5)
  97 for details.  Components from the first forwarded message are available
  98 as standard component escapes in the forms file.
  99 .PP
 100 In addition to the standard
 101 .I mh\-format
 102 escapes, the following
 103 .I component
 104 escapes are also supported:
 105 .PP
 106 .RS 5
 107 .nf
 108 .ta \w'nmh\-subject     'u +\w'Returns  'u
 109 .I "Escape      Returns Description"
 110 fcc     string  Any folders specified with `\-fcc\ folder'
 111 nmh\-from       string  Addresses specified with `\-from\ address'
 112 nmh\-to string  Addresses specified with `\-to\ address'
 113 nmh\-cc string  Addresses specified with `\-cc\ address'
 114 nmh\-subject    string  Any text specified with `\-subject\ text'
 115 .fi
 116 .RE
 117 .PP
 118 By default, the \*(lqTo:\*(rq and \*(lqcc:\*(rq fields are empty.  You may
 119 add addresses to these fields with the
 120 .B \-to
 121 .I address
 122 and
 123 .B \-cc
 124 .I address
 125 switches.  You may give these switches multiple times to add multiple
 126 addresses.
 127 .PP
 128 By default, the \*(lqFrom:\*(rq field contains either the value of the
 129 .B Local\-Mailbox
 130 profile entry, or a system default email address.
 131 This default can be overridden by using the
 132 .B \-from
 133 .I address
 134 switch.  The default mailbox in the \*(lqFcc:\*(rq field is
 135 .IR +outbox .
 136 This can be overridden by the
 137 .B \-fcc
 138 switch.
 139 .PP
 140 Any text given to the
 141 .B \-subject
 142 switch will be placed in the \*(lqSubject:\*(rq field in the draft.
 143 .PP
 144 If the draft already exists,
 145 .B forw
 146 will ask you as to the disposition of the draft.  A reply of
 147 .B quit
 148 will abort
 149 .BR forw ,
 150 leaving the draft intact;
 151 .B replace
 152 will replace the existing draft with a blank skeleton; and
 153 .B list
 154 will display the draft.
 155 .PP
 156 If the
 157 .B \-annotate
 158 switch is given, each message being forwarded will be annotated
 159 with the lines:
 160 .PP
 161 .RS 5
 162 .nf
 163 Forwarded:\ date
 164 Forwarded:\ addrs
 165 .fi
 166 .RE
 167 .PP
 168 where each address list contains as many lines as required.
 169 This annotation will be done only if the message is sent directly from
 170 .BR forw .
 171 If the message is not sent immediately from
 172 .BR forw ,
 173 .RB \*(lq comp
 174 .BR \-use \*(rq
 175 may be used to re-edit and send the constructed message, but the
 176 annotations won't take place.  Normally, annotations are done in place
 177 in order to preserve any links to the message.
 178 You may change this by using the
 179 .B \-noinplace
 180 switch.
 181 .PP
 182 See
 183 .IR comp (1)
 184 for a description of the
 185 .B \-editor
 186 and
 187 .B \-noedit
 188 switches.
 189 .PP
 190 Although
 191 .B forw
 192 uses a forms (components) file to construct the initial draft,
 193 a message filter file is used to format each forwarded message in the
 194 body of the draft.
 195 The filter file for \fIforw\fR should be a standard form file for
 196 .IR mhl (1),
 197 as
 198 .B forw
 199 will invoke
 200 .B mhl
 201 to filter (re-format) the forwarded messages prior to being output to
 202 the body of the draft.
 203 .PP
 204 The switches
 205 .BR \-noformat ,
 206 .BR \-format ,
 207 and
 208 .B \-filter
 209 .I filterfile
 210 specify which message filter file to use.  If
 211 .B \-noformat
 212 is specified (this is the default), then each forwarded
 213 message is output into the draft exactly as it appears, with no
 214 .B mhl
 215 filtering.  If
 216 .B \-format
 217 is specified, then the following default message filter file,
 218 .RI \*(lq mhl.forward \*(rq ,
 219 which should be adequate for most users, is used:
 220 .PP
 221 .RS 5
 222 .nf
 223 %mhl_forward%
 224 .fi
 225 .RE
 226 .PP
 227 If a file named
 228 .RI \*(lq mhl.forward \*(rq
 229 exists in the user's nmh
 230 directory, it will be used instead.  You may specify an
 231 alternate message filter file with the switch
 232 .B \-filter
 233 .IR filterfile .
 234 .PP
 235 Each forwarded message is separated with an encapsulation delimiter.
 236 By default, any dashes in the first column of the forwarded messages
 237 will be prepended with `\-\ ' so that when received, the message is
 238 suitable for bursting by
 239 .IR burst (1).
 240 This follows the guidelines in RFC 934.  You may use the
 241 .B \-nodashstuffing
 242 switch to suppress this form of quoting.
 243 .PP
 244 Users of
 245 .IR prompter (1)
 246 can, by specifying
 247 .BR prompter 's
 248 .B \-prepend
 249 switch in the
 250 .I \&.mh_profile
 251 file, prepend any commentary text before the forwarded messages.
 252 .PP
 253 To use the MIME rules for encapsulation, specify the
 254 .B \-mime
 255 switch.  This directs
 256 .B forw
 257 to generate an
 258 .B mhbuild
 259 composition file.  Note that
 260 .B nmh
 261 will not invoke
 262 .B mhbuild
 263 automatically; you must specifically give the command
 264 .PP
 265 .RS 5
 266 .nf
 267 What now? mime
 268 .fi
 269 .RE
 270 .PP
 271 prior to sending the draft.
 272 .PP
 273 The
 274 .B \-draftfolder
 275 .I +folder
 276 and
 277 .B \-draftmessage
 278 .I msg
 279 switches invoke the
 280 .B nmh
 281 draft folder facility.  This is an advanced (and highly useful) feature.
 282 Consult
 283 .IR mh-draft (5)
 284 for more information.
 285 .PP
 286 The
 287 .B \-editor
 288 .I editor
 289 switch indicates the editor to use for the initial edit.
 290 Upon exiting from the editor,
 291 .B comp
 292 will invoke the
 293 .B whatnow
 294 program.  See
 295 .IR whatnow (1)
 296 for a discussion of
 297 available options.
 298 The invocation of this program can be inhibited by using the
 299 .B \-nowhatnowproc
 300 switch.  (In fact, it is the
 301 .I whatnow
 302 program which starts the initial edit.  Hence,
 303 .B \-nowhatnowproc
 304 will prevent any edit from occurring.)
 305 .PP
 306 The
 307 .B \-build
 308 switch is intended to be used by the Emacs mh-e interface to
 309 .BR nmh .
 310 It implies
 311 .BR \-nowhatnowproc .
 312 It causes a file <mh-dir>/draft
 313 to be created, containing the draft message that would normally be
 314 presented to the user for editing.  No mail is actually sent.
 315 .PP
 316 The
 317 .B \-file
 318 .I msgfile
 319 switch specifies the message to be forwarded as an exact filename
 320 rather than as an
 321 .B nmh
 322 folder and message number.  This switch implies
 323 .BR \-noannotate .
 324 The forwarded message is simply copied verbatim into the draft;
 325 the processing implied by the
 326 .BR \-filter ,
 327 .BR \-mime ,
 328 and
 329 .B \-digest
 330 switches is bypassed, and the usual leading and
 331 trailing 'Forwarded Message' delimiters are not added.
 332 The same caveats apply to this option as to the
 333 .B \-build
 334 switch.
 335 .PP
 336 The
 337 .B \-digest
 338 .IR list ,
 339 .B \-issue
 340 .IR number ,
 341 and
 342 .B \-volume
 343 .I number
 344 switches implement a digest facility for
 345 .BR nmh .
 346 Specifying these switches enables and/or overloads the following escapes:
 347 .PP
 348 .RS 5
 349 .nf
 350 .ta \w'Component  'u +\w'Escape  'u +\w'Returns  'u
 351 .I "Type        Escape  Returns Description"
 352 component       digest  string  Argument to `\-digest'
 353 function        cur     integer Argument to `\-volume'
 354 function        msg     integer Argument to `\-issue'
 355 .fi
 356 .RE
 357 .SH FILES
 358 .B forw
 359 looks for format and filter files in multiple locations: absolute
 360 pathnames are accessed directly, tilde expansion is done on usernames,
 361 and files are searched for in the user's
 362 .I Mail
 363 directory as specified in their profile.  If not found there, the directory
 364 .RI \*(lq %nmhetcdir% \*(rq
 365 is checked.
 366 .PP
 367 .PD 0
 368 .TP 25
 369 %nmhetcdir%/forwcomps
 370 The default message skeleton.
 371 .TP
 372 <mh-dir>/forwcomps
 373 The user's message skeleton.
 374 .TP
 375 %nmhetcdir%/digestcomps
 376 The default message skeleton if
 377 .B \-digest
 378 is given.
 379 .TP
 380 <mh-dir>/digestcomps
 381 The user's
 382 .B \-digest
 383 skeleton.
 384 .TP
 385 ^%nmhetcdir%/mhl.forward
 386 The default message filter.
 387 .TP
 388 <mh-dir>/mhl.forward
 389 The user's message filter.
 390 .TP
 391 ^$HOME/.mh_profile
 392 The user's profile.
 393 .PD
 394 .SH "PROFILE COMPONENTS"
 395 .PD 0
 396 .TP 25
 397 Path:
 398 To determine the user's nmh directory.
 399 .TP
 400 Current\-Folder:
 401 To find the default current folder.
 402 .TP
 403 Draft\-Folder:
 404 To find the default draft-folder.
 405 .TP
 406 Editor:
 407 To override the default editor.
 408 .TP
 409 Msg\-Protect:
 410 To set mode when creating a new message (draft).
 411 .TP
 412 fileproc:
 413 Program to refile the message.
 414 .TP
 415 mhlproc:
 416 Program to filter messages being forwarded.
 417 .TP
 418 whatnowproc:
 419 Program to ask the \*(lqWhat now?\*(rq questions.
 420 .PD
 421 .SH "SEE ALSO"
 422 .IR burst (1),
 423 .IR comp (1),
 424 .IR mh\-format (5),
 425 .IR mhbuild (1),
 426 .IR mhl (1),
 427 .IR prompter (1),
 428 .IR repl (1),
 429 .IR send (1),
 430 .IR whatnow (1)
 431 .PP
 432 .I
 433 Proposed Standard for Message Encapsulation
 434 (RFC 934)
 435 .SH DEFAULTS
 436 .PD 0
 437 .TP 25
 438 +folder
 439 The current folder.
 440 .TP
 441 msgs
 442 The current message.
 443 .TP
 444 \-noannotate
 445 .TP
 446 \-nodraftfolder
 447 .TP
 448 \-noformat
 449 .TP
 450 \-inplace
 451 .TP
 452 \-dashstuffing
 453 .TP
 454 \-nomime
 455 .PD
 456 .SH CONTEXT
 457 If a folder is given, it will become the current folder.
 458 The first message forwarded will become the current message.
 459 .SH BUGS
 460 If
 461 .I whatnowproc
 462 is
 463 .BR whatnow ,
 464 then
 465 .B forw
 466 uses a built-in
 467 .BR whatnow ,
 468 it does not actually run the
 469 .B whatnow
 470 program.
 471 Hence, if you define your own
 472 .IR whatnowproc ,
 473 don't call it
 474 .B whatnow
 475 since
 476 .B forw
 477 won't run it.
 478 .PP
 479 When
 480 .B forw
 481 is told to annotate the messages it forwards, it doesn't actually
 482 annotate them until the draft is successfully sent.
 483 If, from the
 484 .IR whatnowproc ,
 485 you
 486 .B push
 487 instead of
 488 .BR send ,
 489 it is possible to confuse
 490 .B forw
 491 by re-ordering the file (e.g.\& by using
 492 .RB \*(lq folder
 493 .BR \-pack \*(rq)
 494 before the message is successfully sent.
 495 .B dist
 496 and
 497 .B repl
 498 don't have this problem.