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

   1 .TH FORW %manext1% "October 10, 2016" "%nmhversion%"
   2 .\"
   3 .\" %nmhwarning%
   4 .\"
   5 .SH NAME
   6 forw \- forward 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 colums ]
  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 .PP
  51 .HP 5
  52 .B forw
  53 .RB [ \-help ]
  54 .RB [ \-version ]
  55 .RI [ +folder ]
  56 .RI [ msgs ]
  57 .RB [ \-digest
  58 .IR list ]
  59 .RB [ \-issue
  60 .IR number ]
  61 .RB [ \-volume
  62 .IR number ]
  63 [other\ switches\ for\
  64 .BR forw ]
  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.
 340 This switch implies
 341 .BR \-noannotate .
 342 The forwarded message is simply
 343 copied verbatim into the draft; the processing implied by
 344 the
 345 .BR \-filter ,
 346 .BR \-mime ,
 347 and
 348 .B \-digest
 349 switches is bypassed, and the usual leading and
 350 trailing 'Forwarded Message' delimiters are not added.
 351 The same caveats apply to this option as to the
 352 .B \-build
 353 switch.
 354 .PP
 355 The
 356 .B \-digest
 357 .IR list ,
 358 .B \-issue
 359 .IR number ,
 360 and
 361 .B \-volume
 362 .I number
 363 switches implement a digest facility for
 364 .BR nmh .
 365 Specifying these switches enables and/or overloads the following escapes:
 366 .PP
 367 .RS 5
 368 .nf
 369 .ta \w'Component  'u +\w'Escape  'u +\w'Returns  'u
 370 .I "Type        Escape  Returns Description"
 371 component       digest  string  Argument to `\-digest'
 372 function        cur     integer Argument to `\-volume'
 373 function        msg     integer Argument to `\-issue'
 374 .fi
 375 .RE
 376 .PP
 377 .SH FILES
 378 .B forw
 379 looks for format and filter files in multiple locations: absolute
 380 pathnames are accessed directly, tilde expansion is done on usernames,
 381 and files are searched for in the user's
 382 .I Mail
 383 directory as specified in their profile.  If not found there, the directory
 384 .RI \*(lq %nmhetcdir% \*(rq
 385 is checked.
 386 .PP
 387 .PD 0
 388 .TP 25
 389 %nmhetcdir%/forwcomps
 390 The standard message skeleton.
 391 .TP
 392 <mh\-dir>/forwcomps
 393 Rather than the standard skeleton.
 394 .TP
 395 %nmhetcdir%/digestcomps
 396 The message skeleton if
 397 .B \-digest
 398 is given.
 399 .TP
 400 <mh\-dir>/digestcomps
 401 Rather than the standard skeleton.
 402 .TP
 403 ^%nmhetcdir%/mhl.forward
 404 The standard message filter.
 405 .TP
 406 <mh\-dir>/mhl.forward
 407 Rather than the standard filter.
 408 .TP
 409 ^$HOME/.mh_profile
 410 The user's profile.
 411 .PD
 412 .SH "PROFILE COMPONENTS"
 413 .PD 0
 414 .TP 25
 415 Path:
 416 To determine the user's nmh directory.
 417 .TP
 418 Current\-Folder:
 419 To find the default current folder.
 420 .TP
 421 Draft\-Folder:
 422 To find the default draft\-folder.
 423 .TP
 424 Editor:
 425 To override the default editor.
 426 .TP
 427 Msg\-Protect:
 428 To set mode when creating a new message (draft).
 429 .TP
 430 fileproc:
 431 Program to refile the message.
 432 .TP
 433 mhlproc:
 434 Program to filter messages being forwarded.
 435 .TP
 436 whatnowproc:
 437 Program to ask the \*(lqWhat now?\*(rq questions.
 438 .PD
 439 .SH "SEE ALSO"
 440 .IR comp (1),
 441 .IR mhbuild (1),
 442 .IR repl (1),
 443 .IR send (1),
 444 .IR whatnow (1),
 445 .IR mh\-format (5)
 446 .PP
 447 .I
 448 Proposed Standard for Message Encapsulation
 449 (RFC 934)
 450 .SH DEFAULTS
 451 .PD 0
 452 .TP 25
 453 +folder
 454 The current folder.
 455 .TP
 456 msgs
 457 The current message.
 458 .TP
 459 \-noannotate
 460 .TP
 461 \-nodraftfolder
 462 .TP
 463 \-noformat
 464 .TP
 465 \-inplace
 466 .TP
 467 \-dashstuffing
 468 .TP
 469 \-nomime
 470 .PD
 471 .SH CONTEXT
 472 If a folder is given, it will become the current folder.
 473 The first message forwarded will become the current message.
 474 .SH BUGS
 475 If
 476 .I whatnowproc
 477 is
 478 .BR whatnow ,
 479 then
 480 .B forw
 481 uses a built\-in
 482 .BR whatnow ,
 483 it does not actually run the
 484 .B whatnow
 485 program.
 486 Hence, if you define your own
 487 .IR whatnowproc ,
 488 don't call it
 489 .B whatnow
 490 since
 491 .B forw
 492 won't run it.
 493 .PP
 494 When
 495 .B forw
 496 is told to annotate the messages it forwards, it
 497 doesn't actually annotate them until the draft is successfully sent.
 498 If from the
 499 .IR whatnowproc ,
 500 you
 501 .B push
 502 instead of
 503 .BR send ,
 504 it's possible to confuse
 505 .B forw
 506 by re\-ordering the file (e.g.\& by using
 507 .RB \*(lq folder
 508 .BR \-pack \*(rq)
 509 before the message is successfully sent.
 510 .B Dist
 511 and
 512 .B repl
 513 don't have this problem.