4 .TH MHSHOW %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
6 mhshow \- display MIME messages
21 .RB [ \-serialonly " | " \-noserialonly ]
28 .RB [ \-check " | " \-nocheck ]
35 command display contents of a MIME (multi-media)
36 message or collection of messages.
39 manipulates multi-media messages as specified in
40 RFC\-2045 thru RFC\-2049. Currently
43 encodings in message bodies, and does not support the encoding of
44 message headers as specified in RFC\-2047.
48 will display all parts of a multipart
56 to particular subparts (of a
57 multipart content) and/or particular content types.
64 to use the specified file as
65 the source message, rather than a message from a folder. If you specify
66 this file as \*(lq-\*(rq, then
68 will accept the source message
69 on the standard input. Note that the file, or input from standard input
70 should be a validly formatted message, just like any other
74 be in mail drop format (to convert a file in
75 mail drop format to a folder of
80 A part specification consists of a series of numbers separated by dots.
81 For example, in a multipart content containing three parts, these
82 would be named as 1, 2, and 3, respectively. If part 2 was also a
83 multipart content containing two parts, these would be named as 2.1 and
84 2.2, respectively. Note that the
86 switch is effective for only
87 messages containing a multipart content. If a message has some other
88 kind of content, or if the part is itself another multipart content, the
90 switch will not prevent the content from being acted upon.
92 A content specification consists of a content type and a subtype.
93 The initial list of \*(lqstandard\*(rq content types and subtypes can
94 be found in RFC\-2046.
96 A list of commonly used contents is briefly reproduced here:
100 .ta \w'application 'u
104 multipart mixed, alternative, digest, parallel
105 message rfc822, partial, external-body
106 application octet-stream, postscript
113 A legal MIME message must contain a subtype specification.
115 To specify a content, regardless of its subtype, just use the
116 name of the content, e.g., \*(lqaudio\*(rq. To specify a specific
117 subtype, separate the two with a slash, e.g., \*(lqaudio/basic\*(rq.
118 Note that regardless of the values given to the `\-type' switch, a
119 multipart content (of any subtype listed above) is always acted upon.
120 Further note that if the `\-type' switch is used, and it is desirable to
121 act on a message/external-body content, then the `\-type' switch must
122 be used twice: once for message/external-body and once for the content
123 externally referenced.
124 .SS "Unseen Sequence"
125 If the profile entry \*(lqUnseen\-Sequence\*(rq is present and
128 will remove each of the messages shown
129 from each sequence named by the profile entry.
130 .SS "Checking the Contents"
135 to check each content for an
136 integrity checksum. If a content has such a checksum (specified as a
137 Content-MD5 header field), then
139 will attempt to verify the
140 integrity of the content.
141 .SS "Showing the Contents"
142 The headers of each message are displayed with
144 using the standard format file
146 You may specify an alternate format file with the
149 switch. If the format file
151 is specified, then the display
152 of the message headers is suppressed.
154 Next, the contents are extracted from the message and are stored in
155 a temporary file. Usually, the name of the temporary file is the
156 word \*(lqmhshow\*(rq followed by a string of characters. Occasionally,
157 the method used to display a content (described next), requires that
158 the file end in a specific suffix. For example, the
160 command (part of the StarOffice package) can be used to display
161 Microsoft Word content, but it uses the suffix to determine how to display
162 the file. If no suffix is present, the file is not correctly loaded.
163 Similarily, older versions of the
165 command append a \*(lq.ps\*(rq suffix to
166 the filename if one was missing. As a result, these cannot be used to read
167 the default temporary file.
169 To get around this, your profile can contain lines of the form:
172 mhshow-suffix-<type>/<subtype>: <suffix>
178 mhshow-suffix-<type>: <suffix>
181 to specify a suffix which can be automatically added to the temporary
182 file created for a specific content type. For example, the following
183 lines might appear in your profile:
187 mhshow-suffix-text: .txt
188 mhshow-suffix-application/msword: .doc
189 mhshow-suffix-application/PostScript: .ps
193 to automatically append a suffix to the temporary files.
195 The method used to display the different contents in the messages bodies
196 will be determined by a \*(lqdisplay string\*(rq. To find the display
199 will first search your profile for an entry of the form:
202 mhshow-show-<type>/<subtype>
205 to determine the display string. If this isn't found,
207 will search for an entry of the form:
213 to determine the display string.
215 If a display string is found, any escapes (given below) will be expanded.
216 The result will be executed under
217 \*(lq/bin/sh\*(rq, with the standard input
220 The display string may contain the following escapes:
225 %a Insert parameters from Content-Type field
226 %e exclusive execution
227 %f Insert filename containing content
228 %F %e, %f, and stdin is terminal not content
229 %l display listing prior to displaying content
231 %s Insert content subtype
232 %d Insert content description
233 %% Insert the character %
237 For those display strings containing the e- or F-escape,
240 execute at most one of these at any given time. Although the F-escape
241 expands to be the filename containing the content, the e-escape has no
242 expansion as far as the shell is concerned.
246 is display a content, typing QUIT (usually
247 control-\\) will tell
249 to wrap things up immediately.
251 Note that if the content being displayed is multipart, but not one of
252 the subtypes listed above, then the f- and F-escapes expand to multiple
253 filenames, one for each subordinate content. Further, stdin is not
254 redirected from the terminal to the content.
256 If a display string is not found,
258 has the following default values:
262 mhshow-show-text/plain: %l<defaultpager> '%F'
263 mhshow-show-message/rfc822: %lshow \-file '%F'
267 If a subtype of type text doesn't have a profile entry, it will be
268 treated as text/plain.
271 has default methods for handling multipart messages of subtype
272 mixed, alternative, parallel, and digest. Any unknown subtype of type
273 multipart (without a profile entry), will be treated as multipart/mixed.
275 If none of these apply, then
277 will check to see if the message
278 has an application/octet-stream content with parameter \*(lqtype=tar\*(rq.
281 will use an appropriate command. If not,
285 Example entries might be:
289 mhshow-show-audio/basic: raw2audio 2>/dev/null | play
290 mhshow-show-image: xv '%f'
291 mhshow-show-application/PostScript: lpr -Pps
295 Note that when using the f- or F-escape, it's a good idea to use
296 single-quotes around the escape. This prevents misinterpretation by
297 the shell of any funny characters that might be present in the filename.
301 will process each message serially\0--\0it won't start
302 showing the next message until all the commands executed to display the
303 current message have terminated. In the case of a multipart content
304 (of any subtype listed above), the content contains advice indicating if
305 the parts should be displayed serially or in parallel. Because this may
306 cause confusion, particularly on uni-window displays, the
308 switch can be given to tell
310 to never display parts in parallel.
311 .SS "Showing Alternate Character Sets"
312 Because a content of type text might be in a non-ASCII character
315 encounters a \*(lqcharset\*(rq parameter for
316 this content, it checks if your terminal can display this character
319 checks this by examining the the environment
322 If the value of this environment variable is equal
323 to the value of the charset parameter, then
326 display this content without any additional setup. If this environment
329 will assume a value of \*(lqUS-ASCII\*(rq.
330 If the character set cannot be displayed natively, then
332 will look for an entry of the form:
335 mhshow-charset-<charset>
338 which should contain a command creating an environment to render
339 the character set. This command string should containing a single
340 \*(lq%s\*(rq, which will be filled-in with the command to display the
343 Example entries might be:
346 mhshow-charset-iso-8859-1: xterm -fn '-*-*-medium-r-normal-*-*-120-*-*-c-*-iso8859-*' -e %s
352 mhshow-charset-iso-8859-1: '%s'
355 The first example tells
360 appropriate character set for that message content. The second example
363 that your pager (or other program handling that content
364 type) can handle that character set, and that no special processing is
367 Note that many pagers strip off the high-order bit or have problems
368 displaying text with the high-order bit set. However, the pager
370 has support for single-octet character sets. The source
373 is available on many ftp sites carrying free software.
374 In order to view messages sent in the ISO-8859-1 character set using
377 put these lines in your
383 setenv LESSCHARSET latin1
390 to use the ISO-8859-1 definition for
391 determining whether a character is \*(lqnormal\*(rq, \*(lqcontrol\*(lq,
392 or \*(lqbinary\*(rq. The second line tells
395 if it encounters a file that has non-ASCII characters. Then,
401 called automatically. (To handle other single-octet character sets,
404 manual entry for information about the
406 environment variable.)
407 .SS "Messages of Type message/partial"
409 cannot directly display messages of type partial.
410 You must reassemble them first into a normal message using
412 Check the man page for
415 .SS "External Access"
416 For contents of type message/external-body,
418 supports these access-types:
431 For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types,
433 will look for the \*(lqnmh-access-ftp\*(rq
437 nmh-access-ftp: myftp.sh
440 to determine the pathname of a program to perform the FTP retrieval.
442 This program is invoked with these arguments:
446 domain name of FTP-site
452 \*(lqascii\*(rq or \*(lqbinary\*(rq
456 The program should terminate with an exit status of zero if the
457 retrieval is successful, and a non-zero exit status otherwise.
458 .SS "The Content Cache"
461 encounters an external content containing a
462 \*(lqContent-ID:\*(rq field, and if the content allows caching, then
463 depending on the caching behavior of
465 the content might be read from or written to a cache.
467 The caching behavior of
469 is controlled with the
473 switches, which define the policy for reading from,
474 and writing to, the cache, respectively. One of four policies may be
475 specified: \*(lqpublic\*(rq, indicating that
478 of a publically-accessible content cache; \*(lqprivate\*(rq, indicating
481 should make use of the user's private content cache;
482 \*(lqnever\*(rq, indicating that
484 should never make use of
485 caching; and, \*(lqask\*(rq, indicating that
489 There are two directories where contents may be cached: the profile entry
490 \*(lqnmh-cache\*(rq names a directory containing world-readable contents, and,
491 the profile entry \*(lqnmh-private-cache\*(rq names a directory containing
492 private contents. The former should be an absolute (rooted) directory
501 might be used if you didn't care that the cache got wiped after each
502 reboot of the system. The private cache is interpreted relative to the user's
503 mail storage, if not rooted, e.g.,
506 nmh-private-cache: .cache
509 (which is the default value).
510 .SS "User Environment"
511 Because the display environment in which
513 operates may vary for
516 will look for the environment variable
518 If present, this specifies the name of an additional
519 user profile which should be read. Hence, when a user logs in on a
520 particular display device, this environment variable should be set to
521 refer to a file containing definitions useful for the given display device.
522 Normally, only entries that deal with the methods to display different
523 content type and subtypes
527 mhshow-show-<type>/<subtype>
532 need be present in this additional profile. Finally,
534 will attempt to consult one other additional user profile,
538 %etcdir%/mhn.defaults
541 which is created automatically during
548 .ta \w'%etcdir%/ExtraBigFileName 'u
549 ^$HOME/.mmh/profile~^The user profile
550 ^$MHSHOW~^Additional profile entries
551 ^%etcdir%/mhn.defaults~^System default MIME profile entries
552 ^%etcdir%/mhl.headers~^The headers template
555 .SH "PROFILE COMPONENTS"
559 .ta \w'ExtraBigProfileName 'u
560 ^Path:~^To determine the user's mail storage
561 ^Current\-Folder:~^To find the default current folder
562 ^Unseen\-Sequence:~^To name sequences denoting unseen messages
563 ^nmh-access-ftp:~^Program to retrieve contents via FTP
564 ^nmh-cache~^Public directory to store cached external contents
565 ^nmh-private-cache~^Personal directory to store cached external contents
566 ^mhshow-charset-<charset>~^Template for environment to render character sets
567 ^mhshow-show-<type>*~^Template for displaying contents
568 ^Pager:~^Default program to display text/plain content
572 mhbuild(1), mhl(1), mhlist(1), mhstore(1), sendfiles(1)
576 .RB ` +folder "' defaults to the current folder"
577 .RB ` msgs "' defaults to cur"
579 .RB ` \-form mhl.headers '
582 .RB ` \-noserialonly '
588 If a folder is given, it will become the current folder. The last
589 message selected will become the current message.