1 .TH MHSHOW %manext1% "March 16, 2014" "%nmhversion%"
6 mhshow \- display MIME messages
21 .RB [ \-pause " | " \-nopause ]
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 to 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
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 the
146 using the standard format file
148 You may specify an alternate format file with the
151 switch. If the format file
153 is specified, then the display
154 of the message headers is suppressed.
156 Next, the contents are extracted from the message and are stored in
157 a temporary file. Usually, the name of the temporary file is the
158 word \*(lqmhshow\*(rq followed by a string of characters. Occasionally,
159 the method used to display a content (described next), requires that
160 the file end in a specific suffix. For example, the
162 command (part of the StarOffice package) can be used to display
163 Microsoft Word content, but it uses the suffix to determine how to display
164 the file. If no suffix is present, the file is not correctly loaded.
165 Similarily, older versions of the
167 command append a \*(lq.ps\*(rq suffix to
168 the filename if one was missing. As a result, these cannot be used to read
169 the default temporary file.
171 To get around this, your profile can contain lines of the form:
174 mhshow-suffix-<type>/<subtype>: <suffix>
180 mhshow-suffix-<type>: <suffix>
183 to specify a suffix which can be automatically added to the temporary
184 file created for a specific content type. For example, the following
185 lines might appear in your profile:
189 mhshow-suffix-text: .txt
190 mhshow-suffix-application/msword: .doc
191 mhshow-suffix-application/PostScript: .ps
195 to automatically append a suffix to the temporary files.
197 The method used to display the different contents in the messages bodies
198 will be determined by a \*(lqdisplay string\*(rq. To find the display
201 will first search your profile for an entry of the form:
204 mhshow-show-<type>/<subtype>
207 to determine the display string. If this isn't found,
209 will search for an entry of the form:
215 to determine the display string.
217 If a display string is found, any escapes (given below) will be expanded.
218 The result will be executed under
219 \*(lq/bin/sh\*(rq, with the standard input
222 The display string may contain the following escapes:
227 %a Insert parameters from Content-Type field
228 %{parameter} Insert the parameter value from the Content-Type field
229 %f Insert filename containing content
230 %F %e, %f, and stdin is terminal not content
231 %l display listing prior to displaying content
232 %p %l, and ask for confirmation
233 %s Insert content subtype
234 %d Insert content description
235 %% Insert the character %
239 For those display strings containing the e- or F-escape,
242 execute at most one of these at any given time. Although the F-escape
243 expands to be the filename containing the content, the e-escape has no
244 expansion as far as the shell is concerned.
246 When the p-escape prompts for confirmation, typing INTR (usually
249 not to display that content.
250 The p-escape can be disabled by specifying the switch
254 is display a content, typing QUIT (usually
255 control-\\) will tell
257 to wrap things up immediately.
259 The {parameter} escape is typically used in a command line argument
260 that should only be present if it has a non-null value. Its value
261 will be wrapped with single quotes if the escape is not so wrapped.
262 Shell parameter expansion can construct the argument only when it is
267 mhshow-show-text/html: charset=%{charset};
268 w3m ${charset:+-I $charset} -T text/html %F
272 That example also shows the use of indentation to signify continuation:
273 the two text lines combine to form a single entry. Note that when
274 dealing with text that has been converted internally by
276 the \*(lqcharset\*(rq parameter will reflect the target character set
277 of the text, rather than the original character set in the message.
279 Note that if the content being displayed is multipart, but not one of
280 the subtypes listed above, then the f- and F-escapes expand to multiple
281 filenames, one for each subordinate content. Further, stdin is not
282 redirected from the terminal to the content.
284 If a display string is not found,
286 behaves as if these profile entries were supplied and supported:
290 mhshow-show-text/plain: %pmoreproc %F
291 mhshow-show-message/rfc822: %pshow -file %F
295 Note that \*(lqmoreproc\*(rq is not supported in user profile display
298 If a subtype of type text doesn't have a profile entry, it will be
299 treated as text/plain.
302 has default methods for handling multipart messages of subtype
303 mixed, alternative, parallel, and digest. Any unknown subtype of type
304 multipart (without a profile entry), will be treated as multipart/mixed.
306 If none of these apply, then
308 will check to see if the message
309 has an application/octet-stream content with parameter \*(lqtype=tar\*(rq.
312 will use an appropriate command. If not,
316 Example entries might be:
320 mhshow-show-audio/basic: raw2audio 2>/dev/null | play
321 mhshow-show-image: xv %f
322 mhshow-show-application/PostScript: lpr -Pps
326 If an f- or F-escape is not quoted with single quotes, its expansion
327 will be wrapped with single quotes.
331 will process each message serially\0--\0it won't start
332 showing the next message until all the commands executed to display the
333 current message have terminated.
334 .SS "Showing Alternate Character Sets"
339 then all text/plain parts of the message(s) will be displayed using
340 the character set of the current locale. See the
342 man page for how determine whether your
344 installation includes
346 support. To convert text parts other
347 than text/plain, or if
351 an external program can be used, as described next.
353 Because a content of type text might be in a non-ASCII character
356 encounters a \*(lqcharset\*(rq parameter for
357 this content, it checks if your terminal can display this character
360 checks this by examining the current character set defined by the
362 environment variables.
363 If the value of the locale character set is equal
364 to the value of the charset parameter, then
367 display this content without any additional setup. If the locale is not
370 will assume a value of \*(lqUS-ASCII\*(rq.
371 If the character set cannot be displayed natively, then
373 will look for an entry of the form:
376 mhshow-charset-<charset>
379 which should contain a command creating an environment to render
380 the character set. This command string should containing a single
381 \*(lq%s\*(rq, which will be filled-in with the command to display the
384 Example entries might be:
387 mhshow-charset-iso-8859-1: xterm -fn '-*-*-medium-r-normal-*-*-120-*-*-c-*-iso8859-*' -e %s
393 mhshow-charset-iso-8859-1: '%s'
396 The first example tells
401 appropriate character set for that message content. The second example
404 that your pager (or other program handling that content
405 type) can handle that character set, and that no special processing is
408 Note that many pagers strip off the high-order bit or have problems
409 displaying text with the high-order bit set. However, the pager
411 has support for single-octet character sets. For example, messages
412 encoded in the ISO-8859-1 character set can be view using
414 with these environment variable settings:
424 The first setting tells
426 to use the ISO-8859-1 definition for
427 determining whether a character is \*(lqnormal\*(rq, \*(lqcontrol\*(lq,
428 or \*(lqbinary\*(rq. The second setting tells
431 if it encounters a file that has non-ASCII characters. Then, simply
437 called automatically. (To handle other single-octet character sets,
440 manual entry for information about the
442 environment variable.)
443 .SS "Messages of Type message/partial"
445 cannot directly display messages of type partial.
446 You must reassemble them first into a normal message using
448 Check the man page for
451 .SS "External Access"
452 For contents of type message/external-body,
454 supports these access-types:
469 For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types,
471 will look for the \*(lqnmh-access-ftp\*(rq
475 nmh-access-ftp: myftp.sh
478 to determine the pathname of a program to perform the FTP retrieval.
480 This program is invoked with these arguments:
484 domain name of FTP-site
490 \*(lqascii\*(rq or \*(lqbinary\*(rq
494 The program should terminate with an exit status of zero if the
495 retrieval is successful, and a non-zero exit status otherwise.
497 For the \*(lqurl\*(rq access\-type,
499 will look for the \*(lqnmh-access-url\*(rq
504 .SS "The Content Cache"
507 encounters an external content containing a
508 \*(lqContent-ID:\*(rq field, and if the content allows caching, then
509 depending on the caching behavior of
511 the content might be read from or written to a cache.
513 The caching behavior of
515 is controlled with the
519 switches, which define the policy for reading from,
520 and writing to, the cache, respectively. One of four policies may be
521 specified: \*(lqpublic\*(rq, indicating that
524 of a publically-accessible content cache; \*(lqprivate\*(rq, indicating
527 should make use of the user's private content cache;
528 \*(lqnever\*(rq, indicating that
530 should never make use of
531 caching; and, \*(lqask\*(rq, indicating that
535 There are two directories where contents may be cached: the profile entry
536 \*(lqnmh-cache\*(rq names a directory containing world-readable contents, and,
537 the profile entry \*(lqnmh-private-cache\*(rq names a directory containing
538 private contents. The former should be an absolute (rooted) directory
547 might be used if you didn't care that the cache got wiped after each
548 reboot of the system. The latter is interpreted relative to the user's
549 nmh directory, if not rooted, e.g.,
552 nmh-private-cache: .cache
555 (which is the default value).
556 .SS "User Environment"
557 Because the display environment in which
559 operates may vary for
562 will look for the environment variable
564 If present, this specifies the name of an additional
565 user profile which should be read. Hence, when a user logs in on a
566 particular display device, this environment variable should be set to
567 refer to a file containing definitions useful for the given display device.
568 Normally, only entries that deal with the methods to display different
569 content type and subtypes
573 mhshow-show-<type>/<subtype>
578 need be present in this additional profile. Finally,
580 will attempt to consult one other additional user profile,
584 %etcdir%/mhn.defaults
587 which is created automatically during
592 looks for all format files and mhn.defaults in multiple locations:
593 absolute pathnames are accessed directly, tilde expansion is done on
594 usernames, and files are searched for in the user's
596 directory as specified in their profile. If not found there, the directory
597 .RI \*(lq %etcdir% \*(rq
602 .ta \w'%etcdir%/ExtraBigFileName 'u
603 ^$HOME/\&.mh\(ruprofile~^The user profile
604 ^$MHSHOW~^Additional profile entries
605 ^%etcdir%/mhn.defaults~^System default MIME profile entries
606 ^%etcdir%/mhl.headers~^The headers template
608 .SH "PROFILE COMPONENTS"
612 .ta \w'ExtraBigProfileName 'u
613 ^Path:~^To determine the user's nmh directory
614 ^Current\-Folder:~^To find the default current folder
615 ^Unseen\-Sequence:~^To name sequences denoting unseen messages
616 ^mhlproc:~^Default program to display message headers
617 ^nmh-access-ftp:~^Program to retrieve contents via FTP
618 ^nmh-access-url:~^Program to retrieve contents via HTTP
619 ^nmh-cache~^Public directory to store cached external contents
620 ^nmh-private-cache~^Personal directory to store cached external contents
621 ^mhshow-charset-<charset>~^Template for environment to render character sets
622 ^mhshow-show-<type>*~^Template for displaying contents
623 ^moreproc:~^Default program to display text/plain content
635 .RB ` +folder "' defaults to the current folder"
636 .RB ` msgs "' defaults to cur"
638 .RB ` \-form\ mhl.headers '
640 .RB ` \-rcache\ ask '
641 .RB ` \-wcache\ ask '
644 If a folder is given, it will become the current folder. The last
645 message selected will become the current message.
projects / nmh / blob