Added test of -nosequence to test-pick.
[mmh] / docs / historical / mh-6.8.5 / doc / mhn.me
1 .\"     This file is automatically generated.  Do not edit!
2 .\" @(#)$Id: mhn.rf,v 1.14 1993/10/26 20:12:56 jromine Exp $
3 .SC MHN 1
4 .NA
5 mhn \- multi-media MH
6 .SY
7 mhn
8 \%[\%[+folder] \%[msgs] | \%[\-file\0file]]
9 .br
10 \%[\-part\0number]... \%[\-type\0content]...
11 .br
12 \%[\-list\0\%[\-headers]\0\%[\-noheaders]
13 .br
14        \%[\-realsize]\0\%[\-norealsize]] \%[-nolist]
15 .br
16 \%[\-show\0\%[\-serialonly]\0\%[\-noserialonly]
17 .br
18        \%[\-form\0formfile]\0\%[\-pause]\0\%[\-nopause]] \%[\-noshow]
19 .br
20 \%[\-store\0\%[\-auto]\0\%[\-noauto]] \%[\-nostore]
21 .br
22 \%[\-cache] \%[\-nocache] \%[\-rcache\0policy] \%[\-wcache\0policy]
23 .br
24 \%[\-check]\0\%[\-nocheck]
25 .br
26 \%[\-ebcdicsafe]\0\%[\-noebcdicsafe]
27 .br
28 \%[\-rfc934mode]\0\%[\-norfc934mode]
29 .br
30 \%[\-verbose]\0\%[\-noverbose]
31 .br
32 \%[\-help]
33 .DE
34 The \fImhn\fR command manipulates multi-media messages as specified in
35 RFC 1521.
36
37 Four action switches direct the operation of \fImhn\fR,
38 namely `\-list', `\-show', `\-store', and `-cache'.
39 Any of these switches may be used concurrently.
40 Normally these action switches will operate on the content of each of the
41 named messages.
42 However,
43 by using the `\-part' and `\-type' switches,
44 the scope of the operation can be focused on particular
45 subparts (of a multipart content) and/or particular content types.
46
47 A part specification consists of a series of numbers separated by dots.
48 For example,
49 in a multipart content containing three parts,
50 these would be named as 1, 2, and 3, respectively.
51 If part 2 was also a multipart content containing two parts,
52 these would be named as 2.1 and 2.2, respectively.
53 Note that the `\-part' switch is effective for only messages
54 containing a multipart content.
55 If a message has some other kind of content,
56 or if the part is itself another multipart content,
57 the `\-part' switch will not prevent the content from being acted upon.
58
59 A content specification consists of a content type and a subtype.
60 The initial list of \*(lqstandard\*(rq content types and subtypes can be found
61 in RFC 1521.
62 .ne 18
63 A list of commonly used contents is briefly reproduced here:
64 .sp
65 .nf
66 .in +.5i
67 .ta \w'application  'u
68 Type    Subtypes
69 ----    --------
70 text    plain
71 multipart       mixed, alternative, digest, parallel
72 message rfc822, partial, external-body
73 application     octet-stream, postscript
74 image   jpeg, gif, x-pbm, x-pgm, x-ppm, x-xwd
75 audio   basic
76 video   mpeg
77 .re
78 .in -.5i
79 .fi
80 .sp
81 Subtypes are mandatory.
82 .PP
83 To specify a content,
84 regardless of its subtype,
85 just use the name of the content,
86 e.g.,
87 \*(lqaudio\*(rq.
88 To specify a specific subtype,
89 separate the two with a slash,
90 e.g.,
91 \*(lqaudio/basic\*(rq.
92 Note that regardless of the values given to the `\-type' switch,
93 a multipart content (of any subtype listed above) is always acted upon.
94 Further note that if the `\-type' switch is used,
95 and it is desirable to act on a message/external-body content,
96 then the `\-type' switch must be used twice:
97 once for message/external-body and once for the content externally referenced.
98
99 Each content may optionally have an integrity check associated with it.
100 If present and the `-check' switch is given,
101 then \fImhn\fR will attempt to verify the integrity of the content.
102
103 The option `\-file\ file' directs \fImhn\fR to use the specified
104 file as the source message, rather than a message from
105 a folder.
106 Note that the file should be a validly formatted message,
107 just like any other \fIMH\fR message.
108 It should \fBNOT\fR be in mail drop format
109 (to convert a file in mail drop format to a folder of \fIMH\fR messages,
110 see \fIinc\fR\0(1)).
111
112 .Uh "Listing the Contents"
113 The `\-list' switch tells \fImhn\fR to list the table of contents
114 associated with the named messages.
115 The `\-headers' switch indicates that a one-line banner should be
116 displayed above the listing.
117 The `\-realsize' switch tells \fImhn\fR to evaluate the \*(lqnative\*(rq
118 (decoded) format of each content prior to listing.
119 This provides an accurate count at the expense of a small delay.
120
121 .Uh "Showing the Contents"
122 The `\-show' switch tells \fImhn\fR to display the contents of the named
123 messages.
124 The headers of the message are displayed with the \fImhlproc\fR,
125 using format file \fImhl.headers\fR.
126 (The choice of format file can be overridden by the `\-form\0formfile' switch.)
127
128 \fImhn\fR will look for information in the user's profile to determine
129 how the different contents should be displayed.
130 This is accomplished by consulting a display string,
131 and executing it under \fB/bin/sh\fR,
132 with the standard input set to the content.
133 .ne 16
134 The display string may contain these escapes:
135 .sp
136 .nf
137 .in +.5i
138 .ta \w'%F  'u
139 %a      additional arguments
140 %e      exclusive execution
141 %f      filename containing content
142 %F      %e, %f, and stdin is terminal not content
143 %l      display listing prior to displaying content
144 %p      %l, and ask for confirmation
145 %s      subtype
146 %d      content description
147 .re
148 .in -.5i
149 .fi
150 .sp
151 For those display strings containing the e- or F-escape,
152 \fImhn\fR will execute at most one of these at any given time.
153 Although the F-escape expands to be the filename containing the content,
154 the e-escape has no expansion as far as the shell is concerned.
155
156 When the p-escape prompts for confirmation,
157 typing INTR (usually control-C) will tell \fImhn\fR not to display
158 that content.
159 (The p-escape can be disabled by specifying `\-nopause'.)
160 Further,
161 when \fImhn\fR is display a content,
162 typing QUIT (usually control-\\) will tell \fImhn\fR to wrap things up
163 immediately.
164
165 Note that if the content being displayed is multipart,
166 but not one of the subtypes listed above,
167 then the f- and F-escapes expand to multiple filenames,
168 one for each subordinate content.
169 Further,
170 stdin is not redirected from the terminal to the content.
171
172 First,
173 \fImhn\fR will look for an entry of the form:
174 .sp
175 .in +.5i
176 mhn-show-<type>/<subtype>
177 .in -.5i
178 .sp
179 to determine the command to use to display the content.
180 If this isn't found,
181 \fImhn\fR will look for an entry of the form:
182 .sp
183 .in +.5i
184 mhn-show-<type>
185 .in -.5i
186 .sp
187 to determine the display command.
188 .ne 10
189 If this isn't found,
190 \fImhn\fR has two default values:
191 .sp
192 .nf
193 .in +.5i
194 mhn-show-text/plain: %pmoreproc '%F'
195 mhn-show-message/rfc822: %pshow -file '%F'
196 .in -.5i
197 .fi
198 .sp
199 If neither apply,
200 \fImhn\fR will check to see if the message has a application/octet-stream
201 content with parameter \*(lqtype=tar\*(rq.
202 If so,
203 \fImhn\fR will use an appropriate command.
204 If not,
205 \fImhn\fR will complain.
206
207 .ne 10
208 Example entries might be:
209 .sp
210 .nf
211 .in +.5i
212 mhn-show-audio/basic: raw2audio 2>/dev/null | play
213 mhn-show-image: xv '%f'
214 mhn-show-application/PostScript: lpr -Pps
215 .in -.5i
216 .fi
217 .sp
218 Note that when using the f- or F-escape,
219 it's a good idea to use single-quotes around the escape.
220 This prevents misinterpretation by the shell of any funny characters
221 that might be present in the filename.
222
223 Because the text content might be in a non-ASCII character set,
224 when \fImhn\fR encounters a \*(lqcharset\*(rq parameter for this content,
225 it checks to see whether the environment variable $MM_CHARSET is set
226 and whether the value of this environment variable is equal to the value of
227 the charset parameter.
228 If not,
229 then
230 \fImhn\fR will look for an entry of the form:
231 .sp
232 .in +.5i
233 mhn-charset-<charset>
234 .in -.5i
235 .sp
236 which should contain a command creating an environment to render the
237 character set.
238 This command string should containing a single \*(lq%s\*(rq,
239 which will be filled-in with the command to display the content.
240
241 An example entry might be:
242 .sp
243 .in +.5i
244 mhn-charset-iso-8859-1: xterm -fn '-*-*-medium-r-normal-*-*-120-*-*-c-*-iso8859-*' -e %s
245 .in -.5i
246 .sp
247 Note that many pagination programs strip off the high-order bit.
248 However,
249 newer releases of the \fIless\fR program have modest support for
250 single-octet character sets.
251 The source to \fIless\fR version 177,
252 which has such support,
253 is found in the MH source tree under \fBmiscellany/less-177\fR.
254 In order to view messages sent in the ISO 8859/1 character set using
255 \fIless\fR,
256 .ne 9
257 put these lines in your \&.login file:
258 .sp
259 .nf
260 .in +.5i
261 setenv LESSCHARSET latin1
262 setenv LESS "-f"
263 .in -.5i
264 .fi
265 .sp
266 The first line tells \fIless\fR to use 8859/1 definition for determing
267 whether a character is \*(lqnormal\*(rq, \*(lqcontrol\*(lq, or
268 \*(lqbinary\*(rq.
269 The second line tells \fIless\fR not to warn you if it encounters a
270 file that has non-ASCII characters.
271 Then,
272 simply set the \fBmoreproc\fR profile entry to \fIless\fR,
273 and it will get called automatically.
274 (To handle other single-octet character sets,
275 look at the \fIless\fR\0(1) manual entry for information about the
276 \fBLESSCHARDEF\fR environment variable.)
277
278 Finally,
279 \fImhn\fR will process each message serially\0--\0it won't start showing
280 the next message until all the commands executed to display the
281 current message have terminated.
282 In the case of a multipart content (of any subtype listed above),
283 the content contains advice indicating if the parts should be
284 displayed serially or in parallel.
285 Because this may cause confusion,
286 particularly on uni-window displays,
287 the `\-serialonly' switch can be given to tell \fImhn\fR to never
288 display parts in parallel.
289
290 .Uh "Storing the Contents"
291 The `\-store' switch tells \fImhn\fR to store the contents of the
292 named messages in \*(lqnative\*(rq (decoded) format.
293 Two things must be determined:
294 the directory to store the content,
295 and the filenames.
296 Files are written in the directory given by the \fBmhn-storage\fR
297 profile entry,
298 .ne 6
299 e.g.,
300 .sp
301 .in +.5i
302 mhn-storage: /tmp
303 .in -.5i
304 .sp
305 If this entry isn't present,
306 the current working directory is used.
307
308 \fImhn\fR will look for information in the user's profile to determine
309 how the different contents should be stored.
310 This is achieved through the use of a formatting string,
311 .ne 13
312 which may contain these escapes:
313 .sp
314 .nf
315 .in +.5i
316 .ta \w'%P  'u
317 %m      message number
318 %P      .part
319 %p      part
320 %s      subtype
321 .re
322 .in -.5i
323 .fi
324 .sp
325 If the content isn't part of a multipart (of any subtype listed above) content,
326 the p-escapes are ignored.
327 Note that if the formatting string starts with a \*(lq+\*(rq character,
328 then these escapes are ignored,
329 and the content is stored in the named folder.
330 (A formatting string consisting solely of a \*(lq+\*(rq character
331 indicates the current folder.)
332 Further,
333 a formatting string consisting solely of a \*(lq-\*(rq character
334 indicates the standard-output.
335
336 First,
337 \fImhn\fR will look for an entry of the form:
338 .sp
339 .in +.5i
340 mhn-store-<type>/<subtype>
341 .in -.5i
342 .sp
343 to determine the formatting string.
344 If this isn't found,
345 \fImhn\fR will look for an entry of the form:
346 .sp
347 .in +.5i
348 mhn-store-<type>
349 .in -.5i
350 .sp
351 to determine the formatting string.
352 If this isn't found,
353 \fImhn\fR will check to see if the content is application/octet-stream
354 with parameter \*(lqtype=tar\*(rq.
355 If so,
356 \fImhn\fR will choose an appropriate filename.
357 If the content is not application/octet-stream,
358 then \fImhn\fR will check to see if the content is a message.
359 If so,
360 \fImhn\fR will use the value \*(lq+\*(rq.
361 If not,
362 \fImhn\fR will use the value \*(lq%m%P.%s\*(rq.
363
364 Note that if the formatting string starts with a '/',
365 then content will be stored in the full path given
366 (rather than using the value of \fBmhn-storage\fR or the current working
367 directory.)
368 Similarly,
369 if the formatting string starts with a '|',
370 then \fImhn\fR will execute a command which should ultimately store
371 the content.
372 Note that before executing the command,
373 \fImhn\fR will change to the appropriate directory.
374 Also note that if the formatting string starts with a '|',
375 then \fImhn\fR will also honor the a-escape when processing the
376 formatting string.
377
378 .ne 10
379 Example entries might be:
380 .sp
381 .nf
382 .in +.5i
383 mhn-store-text: %m%P.txt
384 mhn-store-audio/basic: | raw2audio -e ulaw -s 8000 -c 1 > %m%P.au
385 mhn-store-application/PostScript: %m%P.ps
386 .in -.5i
387 .fi
388 .sp
389 Further,
390 note that when asked to store a content containing a partial message,
391 \fImhn\fR will try to locate all of the portions and combine them accordingly.
392 Thus,
393 if someone's sent you a message in several parts,
394 you might put them all in their own folder and do:
395 .sp
396 .in +.5i
397 mhn all -store
398 .in -.5i
399 .sp
400 This will store exactly one message,
401 containing the sum of the parts.
402 Note that if \fImhn\fR can not locate each part,
403 it will not store anything.
404
405 Finally,
406 if the `\-auto' switch is given and the content contains information
407 indicating the filename the content should be stored as
408 (and if the filename doesn't begin with a '/'),
409 then the filename from the content will be used instead.
410
411 .Uh "External Access"
412 For contents of type message/external-body,
413 .ne 12
414 \fImhn\fR supports these access-types:
415 .sp
416 .nf
417 .in +.5i
418 afs
419 anon-ftp
420 ftp
421 local-file
422 mail-server
423 .in -.5i
424 .fi
425 .sp
426 For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types,
427 if your system supports a SOCKETs interface to TCP/IP,
428 then \fImhn\fR will use a built-in FTP client.
429 Otherwise,
430 \fImhn\fR will look for the \fBmhn-access-ftp\fR profile entry,
431 .ne 6
432 e.g.,
433 .sp
434 .in +.5i
435 mhn-access-ftp: myftp.sh
436 .in -.5i
437 .sp
438 to determine the pathname of a program to perform the FTP retrieval.
439 .ne 14
440 This program is invoked with these arguments:
441 .sp
442 .nf
443 .in +.5i
444 domain name of FTP-site
445 username
446 password
447 remote directory
448 remote filename
449 local filename
450 \*(lqascii\*(rq or \*(lqbinary\*(rq
451 .in -.5i
452 .fi
453 .sp
454 The program should terminate with a zero-valued exit-status if the
455 retrieval is successful.
456
457 .Uh "The Content Cache"
458 When \fImhn\fR encounters an external content containing a
459 \*(lqContent-ID:\*(rq field,
460 and if the content allows caching,
461 then depending on the caching behavior of \fImhn\fR,
462 the content might be read from or written to a cache.
463
464 The caching behavior of \fImhn\fR is controlled with
465 the `\-rcache' and `\-wcache' switches,
466 which define the policy for reading from,
467 and writing to,
468 the cache, respectively.
469 One of four policies may be specified:
470 \*(lqpublic\*(rq,
471 indicating that \fImhn\fR should make use of a
472 publically-accessible content cache;
473 \*(lqprivate\*(rq,
474 indicating that \fImhn\fR should make use of the user's
475 private content cache;
476 \*(lqnever\*(rq,
477 indicating that \fImhn\fR should never make use of caching;
478 and,
479 \*(lqask\*(rq,
480 indicating that \fImhn\fR should ask the user.
481
482 There are two directories where contents may be cached:
483 the profile entry \fBmhn-cache\fR names a directory containing
484 world-readable contents,
485 and,
486 the profile entry \fBmhn-private-cache\fR names a directory containing
487 private contents.
488 The former should be an absolute (rooted) directory name.
489 .ne 6
490 For example,
491 .sp
492 .in +.5i
493 mhn-cache: /tmp
494 .in -.5i
495 .sp
496 might be used if you didn't care that the cache got wiped after each reboot
497 of the system.
498 The latter is interpreted relative to the user's MH directory,
499 if not rooted,
500 .ne 6
501 e.g.,
502 .sp
503 .in +.5i
504 mhn-private-cache: .cache
505 .in -.5i
506 .sp
507 (which is the default value).
508
509 .Uh "Caching the Contents"
510 When you encounter a content of type message/external-body with access type
511 \*(lqmail-server\*(rq,
512 \fImhn\fR will ask you if may send a message to a mail-server
513 requesting the content,
514 .ne 14
515 e.g.,
516 .sp
517 .nf
518 .in +.5i
519 % show 1
520 Retrieve content by asking mail-server@...
521
522 SEND file
523
524 ? yes
525 mhn: request sent
526 .in -.5i
527 .fi
528 .sp
529 Regardless of your decision,
530 \fImhn\fR can't perform any other processing on the content.
531
532 However,
533 if \fImhn\fR is allowed to request the content,
534 then when it arrives,
535 there should be a top-level \*(lqContent-ID:\*(rq field which
536 corresponds to the value in the original message/external-body content.
537 You should now use the `-cache' switch to tell \fImhn\fR to enter the
538 arriving content into the content cache,
539 .ne 8
540 e.g.,
541 .sp
542 .nf
543 .in +.5i
544 % mhn -cache 2
545 caching message 2 as file ...
546 .in -.5i
547 .fi
548 .sp
549 You can then re-process the original message/external-body content,
550 and \*(lqthe right thing should happen\*(rq,
551 .ne 8
552 e.g.,
553 .sp
554 .nf
555 .in +.5i
556 % show 1
557 \0...
558 .in -.5i
559 .fi
560
561 .Uh "Composing the Contents"
562 The \fImhn\fR program can also be used as a simple editor to aid in
563 composing multi-media messages.
564 When invoked by a \fIwhatnow\fR program,
565 \fImhn\fR will expect the body of the draft to be formatted as an
566 \*(lq\fImhn\fR composition file.\*(rq
567
568 .ne 59
569 The syntax of this is straight-forward:
570 .sp
571 .nf
572 .in +.5i
573    body         ::=     1*(content | EOL)
574
575    content      ::=     directive | plaintext
576
577    directive    ::=     "#" type "/" subtype
578                             0*(";" attribute "=" value)
579                             [ "(" comment ")" ]
580                             [ "<" id ">" ]
581                             [ "[" description "]" ]
582                             [ filename ]
583                             EOL
584
585                       | "#@" type "/" subtype
586                             0*(";" attribute "=" value)
587                             [ "(" comment ")" ]
588                             [ "<" id ">" ]
589                             [ "[" description "]" ]
590                             external-parameters
591                             EOL
592
593                       | "#forw"
594                             [ "<" id ">" ]
595                             [ "[" description "]" ]
596                             [ "+"folder ] [ 0*msg ]
597                             EOL
598
599                       | "#begin"
600                               [ "<" id ">" ]
601                               [ "[" description "]" ]
602                               [   "alternative"
603                                 | "parallel"
604                                 | something-else    ]
605                               EOL
606                             1*body
607                         "#end" EOL
608
609    plaintext    ::=     [ "Content-Description:"
610                               description EOL EOL ]
611                             1*line
612                         [ "#" EOL ]
613
614                       | "#<" type "/" subtype
615                             0*(";" attribute "=" value)
616                             [ "(" comment ")" ]
617                             [ "[" description "]" ]
618                             EOL
619                             1*line
620                         [ "#" EOL ]
621
622    line         ::=     "##" text EOL
623                         -- interpreted as "#"text EOL
624                       | text EOL
625 .in -.5i
626 .fi
627 .sp
628 Basically,
629 the body contains one or more contents.
630 A content consists of either a directive,
631 indicated with a \*(lq#\*(rq as the first character of a line;
632 or,
633 plaintext (one or more lines of text).
634 The continuation character, \*(lq\\\*(lq, may be used to enter a single
635 .ne 11
636 directive on more than one line,
637 e.g.,
638 .sp
639 .nf
640 .in +.5i
641 #@application/octet-stream; \\
642     type=tar; \\
643     x-conversions=compress
644 .in -.5i
645 .fi
646 .sp
647 There are four kinds of directives:
648 \*(lqtype\*(rq directives,
649 which name the type and subtype of the content;
650 \*(lqexternal-type\*(rq directives,
651 which also name the type and subtype of the content;
652 the \*(lqforw\*(rq directive,
653 which is used to forward a digest of messages;
654 and,
655 the \*(lqbegin\*(rq directive,
656 which is used to create a multipart content.
657
658 For the type directives,
659 the user may optionally specify the name of a file containing the
660 contents in \*(lqnative\*(rq (decoded) format.
661 (If the filename starts with the \*(lq|\*(rq character,
662 then this gives a command whose output is captured accordingly.)
663 If a filename is not given,
664 \fImhn\fR will look for information in the user's profile to determine
665 how the different contents should be composed.
666 This is accomplished by consulting a composition string,
667 and executing it under \fB/bin/sh\fR,
668 with the standard output set to the content.
669 .ne 13
670 The composition string may contain these escapes:
671 .sp
672 .nf
673 .in +.5i
674 .ta \w'%P  'u
675 %a      additional arguments
676 %f      filename containing content
677 %F      %f, and stdout is not re-directed
678 %s      subtype
679 .re
680 .in -.5i
681 .fi
682 .sp
683 First,
684 \fImhn\fR will look for an entry of the form:
685 .sp
686 .in +.5i
687 mhn-compose-<type>/<subtype>
688 .in -.5i
689 .sp
690 to determine the command to use to compose the content.
691 If this isn't found,
692 \fImhn\fR will look for an entry of the form:
693 .sp
694 .in +.5i
695 mhn-compose-<type>
696 .in -.5i
697 .sp
698 to determine the composition command.
699 If this isn't found,
700 \fImhn\fR will complain.
701
702 An example entry might be:
703 .sp
704 .in +.5i
705 mhn-compose-audio/basic: record | raw2audio -F
706 .in -.5i
707 .sp
708 Because commands like these will vary,
709 depending on the display environment used for login,
710 composition strings for different contents should probably be put in
711 the file specified by the \fB$MHN\fR environment variable,
712 instead of directly in your user profile.
713
714 The external-type directives are used to provide a reference to a content,
715 rather than enclosing the contents itself.
716 Hence,
717 instead of providing a filename as with the type directives,
718 external-parameters are supplied.
719 These look like regular parameters,
720 .ne 15
721 so they must be separated accordingly,
722 e.g.,
723 .sp
724 .nf
725 .in +.5i
726 #@application/octet-stream; \\
727     type=tar; \\
728     x-conversions=compress [] \\
729     access-type=anon-ftp; \\
730     name="mh-mime.tar.Z"; \\
731     directory="mrose/mh-mime"; \\
732     site="ftp.ics.uci.edu"
733 .in -.5i
734 .fi
735 .sp
736 By specifying \*(lq[]\*(rq,
737 an empty description string is given,
738 and the start of the external-parameters is identified.
739 .ne 19
740 These parameters are of the form:
741 .sp
742 .nf
743 .in +.5i
744 .ta \w'access-type=  'u
745 access-type=    usually \fIanon-ftp\fR or \fImail-server\fR
746 name=   filename
747 permission=     read-only or read-write
748 site=   hostname
749 directory=      directoryname (optional)
750 mode=   usually \fIascii\fR or \fIimage\fR (optional)
751 size=   number of octets
752 server= mailbox
753 subject=        subject to send
754 body=   command to send for retrieval
755 .re
756 .in -.5i
757 .fi
758 .sp
759
760 For the forw directive,
761 the user may optionally specify the name of the folder and which
762 messages are to be forwarded.
763 if a folder is not given,
764 it defaults to the current folder.
765 Similarly,
766 if a message is not given,
767 it defaults to the current message.
768 Hence,
769 the forw directive is similar to the \fIforw\fR\0(1) command,
770 except that the former uses the MIME rules for encapsulation
771 rather than those specified in RFC 934.
772 Usage of the `\-rfc934mode' switch indicates whether \fImhn\fR should
773 attempt to utilize the encapsulation rules in such a way as to appear
774 that RFC 934 is being used.
775 If given,
776 then RFC 934-compliant user-agents should be able to burst the message on
777 reception\0--\0providing that the messages being encapsulated do not
778 contain encapsulated messages themselves.
779 The drawback of this approach is that the encapsulations are generated
780 by placing an extra newline at the end of the body of each message.
781
782 For the begin directive,
783 the user must specify at least one content between
784 the begin and end pairs.
785
786 For all of these directives,
787 the user may include a brief description of the content between
788 the \*(lq[\*(rq character and the \*(lq]\*(rq character.
789 By default,
790 \fImhn\fR will generate a unique \*(lqContent-ID:\*(rq for each directive;
791 however,
792 the user may override this by defining the ID using the
793 \*(lq<\*(rq and \*(lq>\*(rq characters.
794 Putting this all together,
795 .ne 15
796 here is a brief example of what a user's components file might look like:
797 .sp
798 .nf
799 .in +.5i
800 To:
801 cc:
802 Subject:
803 --------
804 #audio/basic [Flint phone]  \\
805     |raw2audio -F < /home/mrose/lib/multi-media/flint.au
806 #image/gif   [MTR's photo] \\
807                     /home/mrose/lib/multi-media/mrose.gif
808 .in -.5i
809 .fi
810 .sp
811 For a later example,
812 we'll call this components file \fImhncomps\fR.
813
814 As noted earlier,
815 in addition to directives,
816 plaintext can be present.
817 Plaintext is gathered,
818 until a directive is found or the draft is exhausted,
819 and this is made to form a text content.
820 If the plaintext must contain a \*(lq#\*(rq at the beginning of a line,
821 simply double it,
822 .ne 6
823 e.g.,
824 .sp
825 .in +.5i
826 ##when sent, this line will start with only one #
827 .in -.5i
828 .sp
829 If you want to end the plaintext prior to a directive,
830 e.g.,
831 to have two plaintext contents adjacent,
832 simply insert a line containing a single \*(lq#\*(rq character,
833 .ne 10
834 e.g.,
835 .sp
836 .nf
837 .in +.5i
838 this is the first content
839 #
840 and this is the second
841 .in -.5i
842 .fi
843 .sp
844 Finally,
845 if the plaintext starts with a line of the form:
846 .sp
847 .in +.5i
848 Content-Description: text
849 .in -.5i
850 .sp
851 then this will be used to describe the plaintext content.
852 \fBNOTE WELL:\fR you must follow this line with a blank line before
853 starting your text.
854
855 By default,
856 plaintext is captured as a text/plain content.
857 You can override this by starting the plaintext with \*(lq#<\*(rq
858 followed by a content-type specification,
859 .ne 11
860 e.g.,
861 .sp
862 .nf
863 .in +.5i
864 #<text/richtext
865 this content will be tagged as text/richtext
866 #
867 and this content will be tagged as text/plain
868 .in -.5i
869 .fi
870 .sp
871 Note that if you use the \*(lq#<\*(rq plaintext-form,
872 then the content-description must be on the same line which identifies
873 the content type of the plaintext.
874
875 If \fImhn\fR is successful,
876 it renames the original draft to start with the \*(lq,\*(rq character
877 and end with the string \*(lq.orig\*(rq,
878 e.g.,
879 if you are editing the file \*(lqdraft\*(rq,
880 it will be renamed to \*(lq,draft.orig\*(rq.
881 This allows you to easily recover the \fImhn\fR composition file.
882
883 If the `-check' switch is given,
884 \fImhn\fR will associate an integrity check with each content.
885
886 .Uh "Automatic Composition"
887 Note that MH will not invoke \fImhn\fR automatically,
888 unless you add this line to your \&.mh\(ruprofile file:
889 .sp
890 .in +.5i
891 automhnproc: mhn
892 .in -.5i
893 .sp
894 Otherwise,
895 you must specifically give the command
896 .sp
897 .in +.5i
898 What now? edit mhn
899 .in -.5i
900 .sp
901 prior to sending the draft.
902
903 You can easily tailor MH to help you remember to do this.
904 .ne 10
905 Suppose you have these lines in your profile:
906 .sp
907 .nf
908 .in +.5i
909 mcomp:          -editor mprompter -form mhncomps
910 mprompter:      -noprepend -norapid
911 mprompter-next: mhn
912 .in -.5i
913 .fi
914 .sp
915 where \fImcomp\fR is a link to \fIcomp\fR\0(1),
916 and \fImprompter\fR is a link to \fIprompter\fR\0(1).
917 Then to send a message using the \fImhncomps\fR components file above,
918 .ne 26
919 the sequence is:
920 .sp
921 .nf
922 .in +.5i
923 % \fBmcomp\fR
924 To: \fBuser@host\fR
925 cc:
926 Subject: \fBmulti-media message\fR
927 --------
928 #audio/basic [Flint phone]  \\
929     |raw2audio -F < /home/mrose/lib/multi-media/flint.au
930 #image/gif   [MTR's photo] \\
931                     /home/mrose/lib/multi-media/mrose.gif
932
933 --------Enter additional text
934
935 \fBThis message contains three contents.\fR
936 \fB<CTRL-D>\fR
937 --------
938
939 What now? \fBedit\fR (this invokes \fImhn\fR)
940
941 What now? \fBsend\fR
942 .in -.5i
943 .fi
944 .sp
945 You have to remember to type the additional edit command,
946 but it should be fairly obvious from the interaction.
947
948 Finally,
949 you should consider adding this line to your profile:
950 .sp
951 .in +.5i
952 lproc: show
953 .in -.5i
954 .sp
955 This way,
956 if you decide to \fBlist\fR after invoking \fImhn\fR as your editor,
957 the command
958 .sp
959 .in +.5i
960 What now? list
961 .in -.5i
962 .sp
963 will work as you expect.
964
965 .Uh "Sending Files via Mail"
966 When you want to send a bunch of files to someone,
967 you can run the \fIviamail\fR shell script,
968 which is similar the tarmail command:
969 .sp
970 .in +.5i
971 /opt/mh-6.8.5/lib/viamail mailpath \*(lqsubject\*(rq files\0...
972 .in -.5i
973 .sp
974 \fIviamail\fR will archive the directories/files you name with \fItar\fR\0(1),
975 and then mail the compressed archive to the `mailpath' with the given
976 `subject'.
977 The archive will be automatically split up into as many messages as
978 necessary in order to get past most mailers.
979
980 Sometimes you want \fIviamail\fR to pause after posting a partial message.
981 This is usually the case when you are running \fIsendmail\fR and
982 expect to generate a lot of partial messages.
983 If the first argument given to \fIviamail\fR starts with a dash,
984 then it is interpreted as the number of seconds to pause in between postings,
985 .ne 6
986 e.g.,
987 .sp
988 .in +.5i
989 /opt/mh-6.8.5/lib/viamail -300 mailpath \*(lqsubject\*(rq files\0...
990 .in -.5i
991 .sp
992 will pause 5 minutes in between each posting.
993
994 When these messages are received,
995 invoke \fImhn\fR once,
996 with the list of messages,
997 and the `\-store' command.
998 The \fImhn\fR program will then store exactly one message containing the
999 archive.
1000 You can then use `\-show' to find out what's inside;
1001 possibly  followed by `\-store' to write the archive to a file where you
1002 .ne 26
1003 can subsequently uncompress and untar it, e.g.,
1004 .sp
1005 .nf
1006 .in +.5i
1007 % mhn -list all
1008  msg part  type/subtype             size description
1009    1       message/partial           47K part 1 of 4
1010    2       message/partial           47K part 2 of 4
1011    3       message/partial           47K part 3 of 4
1012    4       message/partial           18K part 4 of 4
1013 % mhn -store all
1014 % mhn -list -verbose last
1015  msg part  type/subtype             size description
1016    5       application/octet-stream 118K
1017              (extract with uncompress | tar xvpf -)
1018              type=tar
1019              x-conversions=compress
1020 % mhn -show last
1021  msg part  type/subtype             size description
1022    5       application/octet-stream 118K
1023 -- headers of message, followed by \fItar\fR listing appears here
1024 % mhn -store last
1025 % uncompress < 5.tar.Z | tar xvpf -
1026 .in -.5i
1027 .fi
1028 .sp
1029 Alternately,
1030 by using the `\-auto' switch,
1031 \fImhn\fR will automatically do the extraction for you,
1032 .ne 26
1033 e.g.,
1034 .sp
1035 .nf
1036 .in +.5i
1037 % mhn -list all
1038  msg part  type/subtype             size description
1039    1       message/partial           47K part 1 of 4
1040    2       message/partial           47K part 2 of 4
1041    3       message/partial           47K part 3 of 4
1042    4       message/partial           18K part 4 of 4
1043 % mhn -store all
1044 % mhn -list -verbose last
1045  msg part  type/subtype             size description
1046    5       application/octet-stream 118K
1047              (extract with uncompress | tar xvpf -)
1048              type=tar
1049              x-conversions=compress
1050 % mhn -show last
1051  msg part  type/subtype             size description
1052    5       application/octet-stream 118K
1053 -- headers of message, followed by \fItar\fR listing appears here
1054 % mhn -store -auto last
1055 -- \fItar\fR listing appears here as files are extracted
1056 .in -.5i
1057 .fi
1058 .sp
1059 As the second \fItar\fR listing is generated,
1060 the files are extracted.
1061 A prudent user will never put `\-auto' in the \&.mh\(ruprofile file.
1062 The correct procedure is to first use `\-show',
1063 to find out what will be extracted.
1064 Then \fImhn\fR can be invoked with  `\-store' and `\-auto' to perform
1065 the extraction.
1066
1067 .Uh "User Environment"
1068 Because the display environment in which \fImhn\fR operates may vary
1069 for a user,
1070 \fImhn\fR will look for the environment variable \fB$MHN\fR.
1071 If present,
1072 this specifies the name of an additional user profile which should be read.
1073 Hence,
1074 when a user logs in on a particular display device,
1075 this environment variable should be set to refer to a file containing
1076 definitions useful for the display device.
1077 Normally,
1078 only entries of the form
1079 .sp
1080 .in +.5i
1081 mhn-show-<type>/<subtype>
1082 .br
1083 mhn-show-<type>
1084 .in -.5i
1085 .sp
1086 need be present.
1087 Finally,
1088 \fImhn\fR will attempt to consult one other additional user profile,
1089 .ne 6
1090 e.g.,
1091 .sp
1092 .in +.5i
1093 /opt/mh-6.8.5/lib/mhn_defaults
1094 .in -.5i
1095 .sp
1096 which is created automatically during MH installation.
1097 .Fi
1098 ^$HOME/\&.mh\(ruprofile~^The user profile
1099 ^$MHN~^Additional profile entries
1100 ^/opt/mh-6.8.5/lib/mhn_defaults~^System-default profile entries
1101 ^/opt/mh-6.8.5/lib/mhl.headers~^The headers template
1102 .Pr
1103 ^Path:~^To determine the user's MH directory
1104 .Ps
1105 ^Current\-Folder:~^To find the default current folder
1106 .Ps
1107 ^mhlproc:~^Default program to display message headers
1108 .Ps
1109 ^mhn-access-ftp:~^Program to retrieve contents via FTP
1110 .Ps
1111 ^mhn-cache~^Public directory to store cached external contents
1112 .Ps
1113 ^mhn-charset-<charset>~^Template for environment to render character sets
1114 .Ps
1115 ^mhn-compose-<type>*~^Template for composing contents
1116 .Ps
1117 ^mhn-private-cache~^Personal directory to store cached external contents
1118 .Ps
1119 ^mhn-show-<type>*~^Template for displaying contents
1120 .Ps
1121 ^mhn-storage~^Directory to store contents
1122 .Ps
1123 ^mhn-store-<type>*~^Template for storing contents
1124 .Ps
1125 ^moreproc:~^Default program to display text/plain content
1126 .Sa
1127 mhl(1)
1128 .br
1129 \fIMIME: Mechanisms for Specifying and Describing the Format of
1130 Internet Message Bodies\fR
1131 (RFC 1521),
1132 .br
1133 \fIProposed Standard for Message Encapsulation\fR
1134 (RFC 934).
1135 .De
1136 `+folder' defaults to the current folder
1137 .Ds
1138 `msgs' defaults to cur
1139 .Ds
1140 `\-noauto'
1141 .Ds
1142 `\-nocache'
1143 .Ds
1144 `\-nocheck'
1145 .Ds
1146 `\-noebcdicsafe'
1147 .Ds
1148 `\-form\0mhl.headers'
1149 .Ds
1150 `\-headers'
1151 .Ds
1152 `\-pause'
1153 .Ds
1154 `\-rcache\0ask'
1155 .Ds
1156 `\-realsize'
1157 .Ds
1158 `\-rfc934mode'
1159 .Ds
1160 `\-noserialonly'
1161 .Ds
1162 `\-show'
1163 .Ds
1164 `\-noverbose'
1165 .Ds
1166 `\-wcache\0ask'
1167 .Co
1168 If a folder is given,
1169 it will become the current folder.
1170 The last message selected will become the current message.
1171 .Bu
1172 Partial messages contained within a multipart content are not reassembled
1173 with the `\-store' switch.
1174 .En