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

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