Add an AC_PREREQ so we don't just fail with an obscure error message if
[mmh] / man / mhshow.man
1 .\"
2 .\" %nmhwarning%
3 .\" $Id$
4 .\"
5 .TH MHSHOW %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
6 .SH NAME
7 mhshow \- display MIME messages
8 .SH SYNOPSIS
9 .HP 5
10 .na
11 .B mhshow
12 .RI [ +folder ]
13 .RI [ msgs ]
14 .RB [ \-file
15 .IR file ]
16 .RB [ \-part
17 .IR number ]
18 \&...
19 .RB [ \-type
20 .IR content ]
21 \&...
22 .RB [ \-serialonly " | " \-noserialonly ]
23 .RB [ \-pause " | " \-nopause ]
24 .RB [ \-form
25 .IR formfile ]
26 .RB [ \-rcache
27 .IR policy ]
28 .RB [ \-wcache
29 .IR policy ]
30 .RB [ \-check " | " \-nocheck ]
31 .RB [ \-version ]
32 .RB [ \-help ]
33 .ad
34 .SH DESCRIPTION
35 The
36 .B mhshow
37 command display contents of a MIME (multi-media)
38 message or collection of messages.
39 .PP
40 .B mhshow
41 manipulates multi-media messages as specified in
42 RFC\-2045 thru RFC\-2049.  Currently
43 .B mhshow
44 only supports
45 encodings in message bodies, and does not support the encoding of
46 message headers as specified in RFC\-2047.
47 .PP
48 By default
49 .B mhshow
50 will display all parts of a multipart
51 message.  By using the
52 .B \-part
53 and
54 .B \-type
55 switches, you may
56 limit the scope of
57 .B mhshow
58 to particular subparts (of a
59 multipart content) and/or particular content types.
60 .PP
61 The option
62 .B \-file
63 .I file
64 directs
65 .B mhshow
66 to use the specified file as
67 the source message, rather than a message from a folder.  If you specify
68 this file as \*(lq-\*(rq, then
69 .B mhshow
70 will accept the source message
71 on the standard input.  Note that the file, or input from standard input
72 should be a validly formatted message, just like any other
73 .B nmh
74 message.  It should
75 .B NOT
76 be in mail drop format (to convert a file in
77 mail drop format to a folder of
78 .B nmh
79 messages, see
80 .BR inc (1)).
81 .PP
82 A part specification consists of a series of numbers separated by dots.
83 For example, in a multipart content containing three parts, these
84 would be named as 1, 2, and 3, respectively.  If part 2 was also a
85 multipart content containing two parts, these would be named as 2.1 and
86 2.2, respectively.  Note that the
87 .B \-part
88 switch is effective for only
89 messages containing a multipart content.  If a message has some other
90 kind of content, or if the part is itself another multipart content, the
91 .B \-part
92 switch will not prevent the content from being acted upon.
93 .PP
94 A content specification consists of a content type and a subtype.
95 The initial list of \*(lqstandard\*(rq content types and subtypes can
96 be found in RFC\-2046.
97 .PP
98 A list of commonly used contents is briefly reproduced here:
99 .PP
100 .RS 5
101 .nf
102 .ta \w'application  'u
103 Type    Subtypes
104 ----    --------
105 text    plain, enriched
106 multipart       mixed, alternative, digest, parallel
107 message rfc822, partial, external-body
108 application     octet-stream, postscript
109 image   jpeg, gif, png
110 audio   basic
111 video   mpeg
112 .fi
113 .RE
114 .PP
115 A legal MIME message must contain a subtype specification.
116 .PP
117 To specify a content, regardless of its subtype, just use the
118 name of the content, e.g., \*(lqaudio\*(rq.  To specify a specific
119 subtype, separate the two with a slash, e.g., \*(lqaudio/basic\*(rq.
120 Note that regardless of the values given to the `\-type' switch, a
121 multipart content (of any subtype listed above) is always acted upon.
122 Further note that if the `\-type' switch is used, and it is desirable to
123 act on a message/external-body content, then the `\-type' switch must
124 be used twice: once for message/external-body and once for the content
125 externally referenced.
126 .SS "Unseen Sequence"
127 If the profile entry \*(lqUnseen\-Sequence\*(rq is present and
128 non\-empty, then
129 .B mhshow
130 will remove each of the messages shown
131 from each sequence named by the profile entry.
132 .SS "Checking the Contents"
133 The
134 .B \-check
135 switch tells
136 .B mhshow
137 to check each content for an
138 integrity checksum.  If a content has such a checksum (specified as a
139 Content-MD5 header field), then
140 .B mhshow
141 will attempt to verify the
142 integrity of the content.
143 .SS "Showing the Contents"
144 The headers of each message are displayed with the
145 .I mhlproc
146 (usually
147 .BR mhl ),
148 using the standard format file
149 .IR mhl.headers .
150 You may specify an alternate format file with the
151 .B \-form
152 .I formfile
153 switch.  If the format file
154 .I mhl.null
155 is specified, then the display
156 of the message headers is suppressed.
157 .PP
158 Next, the contents are extracted from the message and are stored in
159 a temporary file.  Usually, the name of the temporary file is the
160 word \*(lqmhshow\*(rq followed by a string of characters.  Occasionally,
161 the method used to display a content (described next), requires that
162 the file end in a specific suffix.  For example, the
163 .B soffice
164 command (part of the StarOffice package) can be used to display
165 Microsoft Word content, but it uses the suffix to determine how to display
166 the file.  If no suffix is present, the file is not correctly loaded.
167 Similarily, older versions of the
168 .B gs
169 command append a \*(lq.ps\*(rq suffix to
170 the filename if one was missing.  As a result, these cannot be used to read
171 the default temporary file.
172 .PP
173 To get around this, your profile can contain lines of the form:
174 .PP
175 .RS 5
176 mhshow-suffix-<type>/<subtype>: <suffix>
177 .RE
178 .PP
179 or
180 .PP
181 .RS 5
182 mhshow-suffix-<type>: <suffix>
183 .RE
184 .PP
185 to specify a suffix which can be automatically added to the temporary
186 file created for a specific content type.  For example, the following
187 lines might appear in your profile:
188 .PP
189 .RS 5
190 .nf
191 mhshow-suffix-text: .txt
192 mhshow-suffix-application/msword: .doc
193 mhshow-suffix-application/PostScript: .ps
194 .fi
195 .RE
196 .PP
197 to automatically append a suffix to the temporary files.
198 .PP
199 The method used to display the different contents in the messages bodies
200 will be determined by a \*(lqdisplay string\*(rq.  To find the display
201 string,
202 .B mhshow
203 will first search your profile for an entry of the form:
204 .PP
205 .RS 5
206 mhshow-show-<type>/<subtype>
207 .RE
208 .PP
209 to determine the display string.  If this isn't found,
210 .B mhshow
211 will search for an entry of the form:
212 .PP
213 .RS 5
214 mhshow-show-<type>
215 .RE
216 .PP
217 to determine the display string.
218 .PP
219 If a display string is found, any escapes (given below) will be expanded.
220 The result will be executed under
221 \*(lq/bin/sh\*(rq, with the standard input
222 set to the content.
223 .PP
224 The display string may contain the following escapes:
225 .PP
226 .RS 5
227 .nf
228 .ta \w'%F  'u
229 %a      Insert parameters from Content-Type field
230 %e      exclusive execution
231 %f      Insert filename containing content
232 %F      %e, %f, and stdin is terminal not content
233 %l      display listing prior to displaying content
234 %p      %l, and ask for confirmation
235 %s      Insert content subtype
236 %d      Insert content description
237 %%      Insert the character %
238 .fi
239 .RE
240 .PP
241 For those display strings containing the e- or F-escape,
242 .B mhshow
243 will
244 execute at most one of these at any given time.  Although the F-escape
245 expands to be the filename containing the content, the e-escape has no
246 expansion as far as the shell is concerned.
247 .PP
248 When the p-escape prompts for confirmation, typing INTR (usually
249 control-C) will tell
250 .B mhshow
251 not to display that content.
252 The p-escape can be disabled by specifying the switch
253 .BR \-nopause .
254 Further, when
255 .B mhshow
256 is display a content, typing QUIT (usually
257 control-\\) will tell
258 .B mhshow
259 to wrap things up immediately.
260 .PP
261 Note that if the content being displayed is multipart, but not one of
262 the subtypes listed above, then the f- and F-escapes expand to multiple
263 filenames, one for each subordinate content.  Further, stdin is not
264 redirected from the terminal to the content.
265 .PP
266 If a display string is not found,
267 .B mhshow
268 has several default values:
269 .PP
270 .RS 5
271 .nf
272 mhshow-show-text/plain: %pmoreproc '%F'
273 mhshow-show-message/rfc822: %pshow -file '%F'
274 .fi
275 .RE
276 .PP
277 If a subtype of type text doesn't have a profile entry, it will be
278 treated as text/plain.
279 .PP
280 .B mhshow
281 has default methods for handling multipart messages of subtype
282 mixed, alternative, parallel, and digest.  Any unknown subtype of type
283 multipart (without a profile entry), will be treated as multipart/mixed.
284 .PP
285 If none of these apply, then
286 .B mhshow
287 will check to see if the message
288 has an application/octet-stream content with parameter \*(lqtype=tar\*(rq.
289 If so,
290 .B mhshow
291 will use an appropriate command.  If not,
292 .B mhshow
293 will complain.
294 .PP
295 Example entries might be:
296 .PP
297 .RS 5
298 .nf
299 mhshow-show-audio/basic: raw2audio 2>/dev/null | play
300 mhshow-show-image: xv '%f'
301 mhshow-show-application/PostScript: lpr -Pps
302 .fi
303 .RE
304 .PP
305 Note that when using the f- or F-escape, it's a good idea to use
306 single-quotes around the escape.  This prevents misinterpretation by
307 the shell of any funny characters that might be present in the filename.
308 .PP
309 Finally,
310 .B mhshow
311 will process each message serially\0--\0it won't start
312 showing the next message until all the commands executed to display the
313 current message have terminated.  In the case of a multipart content
314 (of any subtype listed above), the content contains advice indicating if
315 the parts should be displayed serially or in parallel.  Because this may
316 cause confusion, particularly on uni-window displays, the
317 .B \-serialonly
318 switch can be given to tell
319 .B mhshow
320 to never display parts in parallel.
321 .SS "Showing Alternate Character Sets"
322 Because a content of type text might be in a non-ASCII character
323 set, when
324 .B mhshow
325 encounters a \*(lqcharset\*(rq parameter for
326 this content, it checks if your terminal can display this character
327 set natively.
328 .B mhn
329 checks this by examining the the environment
330 variable
331 .BR $MM_CHARSET .
332 If the value of this environment variable is equal
333 to the value of the charset parameter, then
334 .B mhshow
335 assumes it can
336 display this content without any additional setup.  If this environment
337 variable is not set,
338 .B mhshow
339 will assume a value of \*(lqUS-ASCII\*(rq.
340 If the character set cannot be displayed natively, then
341 .B mhshow
342 will look for an entry of the form:
343 .PP
344 .RS 5
345 mhshow-charset-<charset>
346 .RE
347 .PP
348 which should contain a command creating an environment to render
349 the character set.  This command string should containing a single
350 \*(lq%s\*(rq, which will be filled-in with the command to display the
351 content.
352 .PP
353 Example entries might be:
354 .PP
355 .RS 5
356 mhshow-charset-iso-8859-1: xterm -fn '-*-*-medium-r-normal-*-*-120-*-*-c-*-iso8859-*' -e %s
357 .RE
358 .PP
359 or
360 .PP
361 .RS 5
362 mhshow-charset-iso-8859-1: '%s'
363 .RE
364 .PP
365 The first example tells
366 .B mhshow
367 to start
368 .B xterm
369 and load the
370 appropriate character set for that message content.  The second example
371 tells
372 .B mhshow
373 that your pager (or other program handling that content
374 type) can handle that character set, and that no special processing is
375 needed beforehand.
376 .PP
377 Note that many pagers strip off the high-order bit or have problems
378 displaying text with the high-order bit set.  However, the pager
379 .B less
380 has support for single-octet character sets.  The source
381 to
382 .B less
383 is available on many ftp sites carrying free software.
384 In order to view messages sent in the ISO-8859-1 character set using
385 .BR less ,
386 .PP
387 put these lines in your
388 .I \&.login
389 file:
390 .PP
391 .RS 5
392 .nf
393 setenv LESSCHARSET latin1
394 setenv LESS "-f"
395 .fi
396 .RE
397 .PP
398 The first line tells
399 .B less
400 to use the ISO-8859-1 definition for
401 determining whether a character is \*(lqnormal\*(rq, \*(lqcontrol\*(lq,
402 or \*(lqbinary\*(rq.  The second line tells
403 .B less
404 not to warn you
405 if it encounters a file that has non-ASCII characters.  Then, simply
406 set the
407 .I moreproc
408 profile entry to
409 .BR less ,
410 and it will get
411 called automatically.  (To handle other single-octet character sets,
412 look at the
413 .BR less (1)
414 manual entry for information about the
415 .B $LESSCHARDEF
416 environment variable.)
417 .SS "Messages of Type message/partial"
418 .B mhshow
419 cannot directly display messages of type partial.
420 You must reassemble them first into a normal message using
421 .BR mhstore .
422 Check the man page for
423 .BR mhstore (1)
424 for details.
425 .SS "External Access"
426 For contents of type message/external-body,
427 .B mhshow
428 supports these access-types:
429 .PP
430 .IP \(bu 4
431 afs
432 .IP \(bu 4
433 anon-ftp
434 .IP \(bu 4
435 ftp
436 .IP \(bu 4
437 local-file
438 .IP \(bu 4
439 mail-server
440 .PP
441 For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types,
442 .B mhshow
443 will look for the \*(lqnmh-access-ftp\*(rq
444 profile entry, e.g.,
445 .PP
446 .RS 5
447 nmh-access-ftp: myftp.sh
448 .RE
449 .PP
450 to determine the pathname of a program to perform the FTP retrieval.
451 .PP
452 This program is invoked with these arguments:
453 .PP
454 .RS 5
455 .nf
456 domain name of FTP-site
457 username
458 password
459 remote directory
460 remote filename
461 local filename
462 \*(lqascii\*(rq or \*(lqbinary\*(rq
463 .fi
464 .RE
465 .PP
466 The program should terminate with an exit status of zero if the
467 retrieval is successful, and a non-zero exit status otherwise.
468 .PP
469 If this entry is not provided, then
470 .B mhshow
471 will use a simple
472 built-in FTP client to perform the retrieval.
473 .SS "The Content Cache"
474 When
475 .B mhshow
476 encounters an external content containing a
477 \*(lqContent-ID:\*(rq field, and if the content allows caching, then
478 depending on the caching behavior of
479 .BR mhshow ,
480 the content might be read from or written to a cache.
481 .PP
482 The caching behavior of
483 .B mhshow
484 is controlled with the
485 .B \-rcache
486 and
487 .B \-wcache
488 switches, which define the policy for reading from,
489 and writing to, the cache, respectively.  One of four policies may be
490 specified: \*(lqpublic\*(rq, indicating that
491 .B mhshow
492 should make use
493 of a publically-accessible content cache; \*(lqprivate\*(rq, indicating
494 that
495 .B mhshow
496 should make use of the user's private content cache;
497 \*(lqnever\*(rq, indicating that
498 .B mhshow
499 should never make use of
500 caching; and, \*(lqask\*(rq, indicating that
501 .B mhshow
502 should ask the user.
503 .PP
504 There are two directories where contents may be cached: the profile entry
505 \*(lqnmh-cache\*(rq names a directory containing world-readable contents, and,
506 the profile entry \*(lqnmh-private-cache\*(rq names a directory containing
507 private contents.  The former should be an absolute (rooted) directory
508 name.
509 .PP
510 For example,
511 .PP
512 .RS 5
513 nmh-cache: /tmp
514 .RE
515 .PP
516 might be used if you didn't care that the cache got wiped after each
517 reboot of the system.  The latter is interpreted relative to the user's
518 nmh directory, if not rooted, e.g.,
519 .PP
520 .RS 5
521 nmh-private-cache: .cache
522 .RE
523 .PP
524 (which is the default value).
525 .SS "User Environment"
526 Because the display environment in which
527 .B mhshow
528 operates may vary for
529 different machines,
530 .B mhshow
531 will look for the environment variable
532 .BE $MHSHOW .
533 If present, this specifies the name of an additional
534 user profile which should be read.  Hence, when a user logs in on a
535 particular display device, this environment variable should be set to
536 refer to a file containing definitions useful for the given display device.
537 Normally, only entries that deal with the methods to display different
538 content type and subtypes
539 .PP
540 .RS 5
541 .nf
542 mhshow-show-<type>/<subtype>
543 mhshow-show-<type>
544 .fi
545 .RE
546 .PP
547 need be present in this additional profile. Finally,
548 .B mhshow
549 will attempt to consult one other additional user profile,
550 e.g.,
551 .PP
552 .RS 5
553 %etcdir%/mhn.defaults
554 .RE
555 .PP
556 which is created automatically during
557 .B nmh
558 installation.
559
560 .SH FILES
561 .fc ^ ~
562 .nf
563 .ta \w'%etcdir%/ExtraBigFileName  'u
564 ^$HOME/\&.mh\(ruprofile~^The user profile
565 ^$MHSHOW~^Additional profile entries
566 ^%etcdir%/mhn.defaults~^System default MIME profile entries
567 ^%etcdir%/mhl.headers~^The headers template
568 .fi
569
570 .SH "PROFILE COMPONENTS"
571 .fc ^ ~
572 .nf
573 .ta 2.4i
574 .ta \w'ExtraBigProfileName  'u
575 ^Path:~^To determine the user's nmh directory
576 ^Current\-Folder:~^To find the default current folder
577 ^Unseen\-Sequence:~^To name sequences denoting unseen messages
578 ^mhlproc:~^Default program to display message headers
579 ^nmh-access-ftp:~^Program to retrieve contents via FTP
580 ^nmh-cache~^Public directory to store cached external contents
581 ^nmh-private-cache~^Personal directory to store cached external contents
582 ^mhshow-charset-<charset>~^Template for environment to render character sets
583 ^mhshow-show-<type>*~^Template for displaying contents
584 ^moreproc:~^Default program to display text/plain content
585 .fi
586
587 .SH "SEE ALSO"
588 mhbuild(1), mhl(1), mhlist(1), mhstore(1), sendfiles(1)
589
590 .SH DEFAULTS
591 .nf
592 .RB ` +folder "' defaults to the current folder"
593 .RB ` msgs "' defaults to cur"
594 .RB ` \-nocheck '
595 .RB ` \-form mhl.headers '
596 .RB ` \-pause '
597 .RB ` \-rcache ask '
598 .RB ` \-realsize '
599 .RB ` \-noserialonly '
600 .RB ` \-noverbose '
601 .RB ` \-wcache ask '
602 .fi
603
604 .SH CONTEXT
605 If a folder is given, it will become the current folder.  The last
606 message selected will become the current message.