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

   1 .TH FORW %manext1% "December 31, 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 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 may be used to prepare a message containing other messages.
  68 .PP
  69 It constructs the new message from a forms (components) file, with a
  70 body composed of the message(s) to be forwarded.  An editor is invoked
  71 as in
  72 .BR comp ,
  73 and after editing is complete, the user is prompted
  74 before the message is sent.
  75 .PP
  76 The default message template will direct
  77 .B forw
  78 to construct the draft as follows:
  79 .PP
  80 .RS 5
  81 .nf
  82 From: {from switch} or <Local-Mailbox> or <username@hostname>
  83 To: {to switch} or blank
  84 Fcc: {fcc switch} or +outbox
  85 Subject: {subject switch} or "{original subject} (fwd)"
  86 --------
  87 .fi
  88 .RE
  89 .PP
  90 If a file named
  91 .RI \*(lq forwcomps \*(rq
  92 exists in the user's nmh directory,
  93 it will be used instead of this default form.  You may also specify an
  94 alternate forms file with the switch
  95 .B \-form
  96 .IR formfile .
  97 Forms are processed via the
  98 .B nmh
  99 template system; see
 100 .IR mh\-format (5)
 101 for details.  Components from the first forwarded message are available
 102 as standard component escapes in the forms file.
 103 .PP
 104 In addition to the standard
 105 .IR mh\-format (5)
 106 escapes, the following
 107 .I component
 108 escapes are also supported:
 109 .PP
 110 .RS 5
 111 .nf
 112 .ta \w'nmh\-subject     'u +\w'Returns  'u
 113 .I "Escape      Returns Description"
 114 fcc     string  Any folders specified with `\-fcc\ folder'
 115 nmh\-from       string  Addresses specified with `\-from\ address'
 116 nmh\-to string  Addresses specified with `\-to\ address'
 117 nmh\-cc string  Addresses specified with `\-cc\ address'
 118 nmh\-subject    string  Any text specified with `\-subject\ text'
 119 .fi
 120 .RE
 121 .PP
 122 By default the \*(lqTo:\*(rq and \*(lqcc:\*(rq fields are empty.  You may
 123 add addresses to these fields with the
 124 .B \-to
 125 .I address
 126 and
 127 .B \-cc
 128 .I address
 129 switches.  You may give these switches multiple times to add multiple
 130 addresses.
 131 .PP
 132 By default the \*(lqFrom:\*(rq field has either the value of the
 133 .B Local\-Mailbox
 134 profile entry a system default email address.  This default can be overridden
 135 by using the
 136 .B \-from
 137 .I address
 138 switch.  The default mailbox in the \*(lqFcc:\*(rq field is
 139 .IR +outbox .
 140 This can be overridden by the
 141 .B \-fcc
 142 switch.
 143 .PP
 144 Any text you give to the
 145 .B \-subject
 146 switch will be placed in the \*(lqSubject:\*(rq field in the draft.
 147 .PP
 148 If the draft already exists,
 149 .B forw
 150 will ask you as to the disposition
 151 of the draft.  A reply of
 152 .B quit
 153 will abort
 154 .BR forw ,
 155 leaving the draft intact;
 156 .B replace
 157 will replace the existing draft with a blank skeleton; and
 158 .B list
 159 will display the draft.
 160 .PP
 161 If the
 162 .B \-annotate
 163 switch is given, each message being forwarded will
 164 be annotated with the lines:
 165 .PP
 166 .RS 5
 167 .nf
 168 Forwarded:\ date
 169 Forwarded:\ addrs
 170 .fi
 171 .RE
 172 .PP
 173 where each address list contains as many lines as required.  This
 174 annotation will be done only if the message is sent directly from
 175 .BR forw .
 176 If the message is not sent immediately from
 177 .BR forw ,
 178 .RB \*(lq comp
 179 .BR \-use \*(rq
 180 may be used to re\-edit and send the constructed
 181 message, but the annotations won't take place.  Normally annotations
 182 are done inplace in order to preserve any links to the message.  You may
 183 change this by using the
 184 .B \-noinplace
 185 switch.
 186 .PP
 187 See
 188 .IR comp (1)
 189 for a description of the
 190 .B \-editor
 191 and
 192 .B \-noedit
 193 switches.
 194 .PP
 195 Although
 196 .B forw
 197 uses a forms (components) file to direct it how to
 198 construct the beginning of the draft, it uses a message filter file to
 199 direct it as to how each forwarded message should be formatted in the
 200 body of the draft.  The filter file for \fIforw\fR should be a standard
 201 form file for
 202 .BR mhl ,
 203 as
 204 .B forw
 205 will invoke
 206 .B mhl
 207 to filter (re\-format) the forwarded messages prior to being output to
 208 the body of the draft.
 209 .PP
 210 The switches
 211 .BR \-noformat ,
 212 .BR \-format ,
 213 and
 214 .B \-filter
 215 .I filterfile
 216 specify which message filter file to use.
 217 .PP
 218 If
 219 .B \-noformat
 220 is specified (this is the default), then each forwarded
 221 message is output into the draft exactly as it appears with no
 222 .B mhl
 223 filtering.
 224 .PP
 225 If
 226 .B \-format
 227 is specified, then a default message filter file is used.
 228 This default message filter should be adequate for most users.
 229 This default filter
 230 .RI \*(lq mhl.forward \*(rq
 231 is:
 232 .PP
 233 .RS 5
 234 .nf
 235 %mhl_forward%
 236 .fi
 237 .RE
 238 .PP
 239 If a file named
 240 .RI \*(lq mhl.forward \*(rq
 241 exists in the user's nmh
 242 directory, it will be used instead of this form.  You may specify an
 243 alternate message filter file with the switch
 244 .B \-filter
 245 .IR filterfile .
 246 .PP
 247 Each forwarded message is separated with an encapsulation delimiter.
 248 By default, any dashes in the first column of the forwarded messages
 249 will be prepended with `\-\ ' so that when received, the message is
 250 suitable for bursting by
 251 .BR burst .
 252 This follows the Internet RFC 934 guidelines.  You may use the flag
 253 .B \-nodashstuffing
 254 in order
 255 to suppress this form of quoting to the forwarded messages.
 256 .PP
 257 For users of
 258 .BR prompter ,
 259 by specifying
 260 .BR prompter 's
 261 .B \-prepend
 262 switch in the
 263 .I \&.mh\(ruprofile
 264 file, any commentary text is entered
 265 before the forwarded messages.  (A major win!)
 266 .PP
 267 To use the MIME rules for encapsulation, specify the
 268 .B \-mime
 269 switch.  This directs
 270 .B forw
 271 to generate an
 272 .B mhbuild
 273 composition file.  Note that
 274 .B nmh
 275 will not invoke
 276 .B mhbuild
 277 automatically; you must specifically give the command
 278 .PP
 279 .RS 5
 280 .nf
 281 What now? mime
 282 .fi
 283 .RE
 284 .PP
 285 prior to sending the draft.
 286 .PP
 287 The
 288 .B \-draftfolder
 289 .I +folder
 290 and
 291 .B \-draftmessage
 292 .I msg
 293 switches invoke the
 294 .B nmh
 295 draft folder facility.  This is an advanced (and highly
 296 useful) feature.  Consult the
 297 .IR mh-draft (5)
 298 man page for more information.
 299 .PP
 300 The
 301 .B \-editor
 302 .I editor
 303 switch indicates the editor to use for the
 304 initial edit.  Upon exiting from the editor,
 305 .B comp
 306 will invoke the
 307 .B whatnow
 308 program.  See
 309 .IR whatnow (1)
 310 for a discussion of
 311 available options.  The invocation of this program can be inhibited
 312 by using the
 313 .B \-nowhatnowproc
 314 switch.  (In truth of fact, it is
 315 the
 316 .I whatnow
 317 program which starts the initial edit.  Hence,
 318 .B \-nowhatnowproc
 319 will prevent any edit from occurring.)
 320 .PP
 321 The
 322 .B \-build
 323 switch is intended to be used by the Emacs mh-e interface to
 324 .BR nmh .
 325 It implies
 326 .BR \-nowhatnowproc .
 327 It causes a file <mh\-dir>/draft
 328 to be created, containing the draft message that would normally be presented
 329 to the user for editing.
 330 No mail is actually sent.
 331 .PP
 332 The
 333 .B \-file
 334 .I msgfile
 335 switch specifies the message to be forwarded as an
 336 exact filename rather than as an
 337 .B nmh
 338 folder and message number.
 339 This switch implies
 340 .BR \-noannotate .
 341 The forwarded message is simply
 342 copied verbatim into the draft; the processing implied by
 343 the
 344 .BR \-filter ,
 345 .BR \-mime ,
 346 and
 347 .B \-digest
 348 switches is bypassed, and the usual leading and
 349 trailing 'Forwarded Message' delimiters are not added.
 350 The same caveats apply to this option as to the
 351 .B \-build
 352 switch.
 353 .PP
 354 The
 355 .B \-digest
 356 .IR list ,
 357 .B \-issue
 358 .IR number ,
 359 and
 360 .B \-volume
 361 .I number
 362 switches implement a digest facility for
 363 .BR nmh .
 364 Specifying these switches enables and/or overloads the following escapes:
 365 .PP
 366 .RS 5
 367 .nf
 368 .ta \w'Component  'u +\w'Escape  'u +\w'Returns  'u
 369 .I "Type        Escape  Returns Description"
 370 component       digest  string  Argument to `\-digest'
 371 function        cur     integer Argument to `\-volume'
 372 function        msg     integer Argument to `\-issue'
 373 .fi
 374 .RE
 375 .SH FILES
 376 .B forw
 377 looks for format and filter files in multiple locations: absolute
 378 pathnames are accessed directly, tilde expansion is done on usernames,
 379 and files are searched for in the user's
 380 .I Mail
 381 directory as specified in their profile.  If not found there, the directory
 382 .RI \*(lq %nmhetcdir% \*(rq
 383 is checked.
 384 .PP
 385 .PD 0
 386 .TP 25
 387 %nmhetcdir%/forwcomps
 388 The default message skeleton.
 389 .TP
 390 <mh\-dir>/forwcomps
 391 The user's message skeleton.
 392 .TP
 393 %nmhetcdir%/digestcomps
 394 The default message skeleton if
 395 .B \-digest
 396 is given.
 397 .TP
 398 <mh\-dir>/digestcomps
 399 The user's
 400 .B \-digest
 401 skeleton.
 402 .TP
 403 ^%nmhetcdir%/mhl.forward
 404 The default message filter.
 405 .TP
 406 <mh\-dir>/mhl.forward
 407 The user's message 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.