1 .TH MHSHOW %manext1% "March 16, 2014" "%nmhversion%"
6 mhshow \- display MIME messages
27 .RB [ \-check " | " \-nocheck ]
34 command display contents of a MIME (multi-media)
35 message or collection of messages.
38 manipulates multi-media messages as specified in
39 RFC 2045 to RFC 2049. Currently
42 encodings in message bodies, and does not support the encoding of
43 message headers as specified in RFC 2047.
47 will display all parts of a multipart
55 to particular subparts (of a
56 multipart content) and/or particular content types.
63 to use the specified file as
64 the source message, rather than a message from a folder. If you specify
65 this file as \*(lq-\*(rq, then
67 will accept the source message
68 on the standard input. Note that the file, or input from standard input
69 should be a validly formatted message, just like any other
73 be in mail drop format (to convert a file in
74 mail drop format to a folder of
79 A part specification consists of a series of numbers separated by dots.
80 For example, in a multipart content containing three parts, these
81 would be named as 1, 2, and 3, respectively. If part 2 was also a
82 multipart content containing two parts, these would be named as 2.1 and
83 2.2, respectively. Note that the
85 switch is effective for only
86 messages containing a multipart content. If a message has some other
87 kind of content, or if the part is itself another multipart content, the
89 switch will not prevent the content from being acted upon.
91 A content specification consists of a content type and a subtype.
92 The initial list of \*(lqstandard\*(rq content types and subtypes can
95 A list of commonly used contents is briefly reproduced here:
103 multipart mixed, alternative, digest, parallel
104 message rfc822, partial, external-body
105 application octet-stream, postscript
112 A legal MIME message must contain a subtype specification.
114 To specify a content, regardless of its subtype, just use the
115 name of the content, e.g., \*(lqaudio\*(rq. To specify a specific
116 subtype, separate the two with a slash, e.g., \*(lqaudio/basic\*(rq.
117 Note that regardless of the values given to the `\-type' switch, a
118 multipart content (of any subtype listed above) is always acted upon.
119 Further note that if the `\-type' switch is used, and it is desirable to
120 act on a message/external-body content, then the `\-type' switch must
121 be used twice: once for message/external-body and once for the content
122 externally referenced.
123 .SS "Unseen Sequence"
124 If the profile entry \*(lqUnseen\-Sequence\*(rq is present and
127 will remove each of the messages shown
128 from each sequence named by the profile entry.
129 .SS "Checking the Contents"
134 to check each content for an
135 integrity checksum. If a content has such a checksum (specified as a
136 Content-MD5 header field), then
138 will attempt to verify the
139 integrity of the content.
140 .SS "Showing the Contents"
141 The headers of each message are displayed with the
145 using the standard format file
147 You may specify an alternate format file with the
150 switch. If the format file
152 is specified, then the display
153 of the message headers is suppressed.
155 Next, the contents are extracted from the message and are stored in
156 a temporary file. Usually, the name of the temporary file is the
157 word \*(lqmhshow\*(rq followed by a string of characters. Occasionally,
158 the method used to display a content (described next), requires that
159 the file end in a specific suffix. For example, the
161 command (part of the StarOffice package) can be used to display
162 Microsoft Word content, but it uses the suffix to determine how to display
163 the file. If no suffix is present, the file is not correctly loaded.
164 Similarily, older versions of the
166 command append a \*(lq.ps\*(rq suffix to
167 the filename if one was missing. As a result, these cannot be used to read
168 the default temporary file.
170 To get around this, your profile can contain lines of the form:
173 mhshow-suffix-<type>/<subtype>: <suffix>
179 mhshow-suffix-<type>: <suffix>
182 to specify a suffix which can be automatically added to the temporary
183 file created for a specific content type. For example, the following
184 lines might appear in your profile:
188 mhshow-suffix-text: .txt
189 mhshow-suffix-application/msword: .doc
190 mhshow-suffix-application/PostScript: .ps
194 to automatically append a suffix to the temporary files.
196 The method used to display the different contents in the messages bodies
197 will be determined by a \*(lqdisplay string\*(rq. To find the display
200 will first search your profile for an entry of the form:
203 mhshow-show-<type>/<subtype>
206 to determine the display string. If this isn't found,
208 will search for an entry of the form:
214 to determine the display string.
216 If a display string is found, any escapes (given below) will be expanded.
217 The result will be executed under
218 \*(lq/bin/sh\*(rq, with the standard input
221 The display string may contain the following escapes:
226 %a Insert parameters from Content-Type field
227 %{parameter} Insert the parameter value from the Content-Type field
228 %f Insert filename containing content
229 %F %f, and stdin is terminal not content
230 %l display listing prior to displaying content
231 %s Insert content subtype
232 %d Insert content description
233 %% Insert the character %
239 execute at most one display string at any given time, and wait for the
240 current display string to finish execution before executing the next
243 The {parameter} escape is typically used in a command line argument
244 that should only be present if it has a non-null value. Its value
245 will be wrapped with single quotes if the escape is not so wrapped.
246 Shell parameter expansion can construct the argument only when it is
251 mhshow-show-text/html: charset=%{charset};
252 w3m ${charset:+-I $charset} -T text/html %F
256 That example also shows the use of indentation to signify continuation:
257 the two text lines combine to form a single entry. Note that when
258 dealing with text that has been converted internally by
260 the \*(lqcharset\*(rq parameter will reflect the target character set
261 of the text, rather than the original character set in the message.
263 Note that if the content being displayed is multipart, but not one of
264 the subtypes listed above, then the f- and F-escapes expand to multiple
265 filenames, one for each subordinate content. Further, stdin is not
266 redirected from the terminal to the content.
268 If a display string is not found,
270 behaves as if these profile entries were supplied and supported:
274 mhshow-show-text/plain: %lmoreproc %F
275 mhshow-show-message/rfc822: %lshow -file %F
279 Note that \*(lqmoreproc\*(rq is not supported in user profile display
282 If a subtype of type text doesn't have a profile entry, it will be
283 treated as text/plain.
286 has default methods for handling multipart messages of subtype
287 mixed, alternative, parallel, and digest. Any unknown subtype of type
288 multipart (without a profile entry), will be treated as multipart/mixed.
290 If none of these apply, then
292 will check to see if the message
293 has an application/octet-stream content with parameter \*(lqtype=tar\*(rq.
296 will use an appropriate command. If not,
300 Example entries might be:
304 mhshow-show-audio/basic: raw2audio 2>/dev/null | play
305 mhshow-show-image: xv %f
306 mhshow-show-application/PostScript: lpr -Pps
310 If an f- or F-escape is not quoted with single quotes, its expansion
311 will be wrapped with single quotes.
315 will process each message serially\0--\0it won't start
316 showing the next message until all the commands executed to display the
317 current message have terminated.
318 .SS "Showing Alternate Character Sets"
323 then all text/plain parts of the message(s) will be displayed using
324 the character set of the current locale. See the
326 man page for how determine whether your
328 installation includes
330 support. To convert text parts other
331 than text/plain, or if
335 an external program can be used, as described next.
337 Because a content of type text might be in a non-ASCII character
340 encounters a \*(lqcharset\*(rq parameter for
341 this content, it checks if your terminal can display this character
344 checks this by examining the current character set defined by the
346 environment variables.
347 If the value of the locale character set is equal
348 to the value of the charset parameter, then
351 display this content without any additional setup. If the locale is not
354 will assume a value of \*(lqUS-ASCII\*(rq.
355 If the character set cannot be displayed natively, then
357 will look for an entry of the form:
360 mhshow-charset-<charset>
363 which should contain a command creating an environment to render
364 the character set. This command string should containing a single
365 \*(lq%s\*(rq, which will be filled-in with the command to display the
368 Example entries might be:
371 mhshow-charset-iso-8859-1: xterm -fn '-*-*-medium-r-normal-*-*-120-*-*-c-*-iso8859-*' -e %s
377 mhshow-charset-iso-8859-1: '%s'
380 The first example tells
385 appropriate character set for that message content. The second example
388 that your pager (or other program handling that content
389 type) can handle that character set, and that no special processing is
392 Note that many pagers strip off the high-order bit or have problems
393 displaying text with the high-order bit set. However, the pager
395 has support for single-octet character sets. For example, messages
396 encoded in the ISO-8859-1 character set can be view using
398 with these environment variable settings:
408 The first setting tells
410 to use the ISO-8859-1 definition for
411 determining whether a character is \*(lqnormal\*(rq, \*(lqcontrol\*(lq,
412 or \*(lqbinary\*(rq. The second setting tells
415 if it encounters a file that has non-ASCII characters. Then, simply
421 called automatically. (To handle other single-octet character sets,
424 manual entry for information about the
426 environment variable.)
427 .SS "Messages of Type message/partial"
429 cannot directly display messages of type partial.
430 You must reassemble them first into a normal message using
432 Check the man page for
435 .SS "External Access"
436 For contents of type message/external-body,
438 supports these access-types:
453 For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types,
455 will look for the \*(lqnmh-access-ftp\*(rq
459 nmh-access-ftp: myftp.sh
462 to determine the pathname of a program to perform the FTP retrieval.
464 This program is invoked with these arguments:
468 domain name of FTP-site
474 \*(lqascii\*(rq or \*(lqbinary\*(rq
478 The program should terminate with an exit status of zero if the
479 retrieval is successful, and a non-zero exit status otherwise.
481 For the \*(lqurl\*(rq access\-type,
483 will look for the \*(lqnmh-access-url\*(rq
488 .SS "The Content Cache"
491 encounters an external content containing a
492 \*(lqContent-ID:\*(rq field, and if the content allows caching, then
493 depending on the caching behavior of
495 the content might be read from or written to a cache.
497 The caching behavior of
499 is controlled with the
503 switches, which define the policy for reading from,
504 and writing to, the cache, respectively. One of four policies may be
505 specified: \*(lqpublic\*(rq, indicating that
508 of a publically-accessible content cache; \*(lqprivate\*(rq, indicating
511 should make use of the user's private content cache;
512 \*(lqnever\*(rq, indicating that
514 should never make use of
515 caching; and, \*(lqask\*(rq, indicating that
519 There are two directories where contents may be cached: the profile entry
520 \*(lqnmh-cache\*(rq names a directory containing world-readable contents, and,
521 the profile entry \*(lqnmh-private-cache\*(rq names a directory containing
522 private contents. The former should be an absolute (rooted) directory
531 might be used if you didn't care that the cache got wiped after each
532 reboot of the system. The latter is interpreted relative to the user's
533 nmh directory, if not rooted, e.g.,
536 nmh-private-cache: .cache
539 (which is the default value).
540 .SS "User Environment"
541 Because the display environment in which
543 operates may vary for
546 will look for the environment variable
548 If present, this specifies the name of an additional
549 user profile which should be read. Hence, when a user logs in on a
550 particular display device, this environment variable should be set to
551 refer to a file containing definitions useful for the given display device.
552 Normally, only entries that deal with the methods to display different
553 content type and subtypes
557 mhshow-show-<type>/<subtype>
562 need be present in this additional profile. Finally,
564 will attempt to consult one other additional user profile,
568 %etcdir%/mhn.defaults
571 which is created automatically during
576 looks for all format files and mhn.defaults in multiple locations:
577 absolute pathnames are accessed directly, tilde expansion is done on
578 usernames, and files are searched for in the user's
580 directory as specified in their profile. If not found there, the directory
581 .RI \*(lq %etcdir% \*(rq
586 .ta \w'%etcdir%/ExtraBigFileName 'u
587 ^$HOME/\&.mh\(ruprofile~^The user profile
588 ^$MHSHOW~^Additional profile entries
589 ^%etcdir%/mhn.defaults~^System default MIME profile entries
590 ^%etcdir%/mhl.headers~^The headers template
592 .SH "PROFILE COMPONENTS"
596 .ta \w'ExtraBigProfileName 'u
597 ^Path:~^To determine the user's nmh directory
598 ^Current\-Folder:~^To find the default current folder
599 ^Unseen\-Sequence:~^To name sequences denoting unseen messages
600 ^mhlproc:~^Default program to display message headers
601 ^nmh-access-ftp:~^Program to retrieve contents via FTP
602 ^nmh-access-url:~^Program to retrieve contents via HTTP
603 ^nmh-cache~^Public directory to store cached external contents
604 ^nmh-private-cache~^Personal directory to store cached external contents
605 ^mhshow-charset-<charset>~^Template for environment to render character sets
606 ^mhshow-show-<type>*~^Template for displaying contents
607 ^moreproc:~^Default program to display text/plain content
619 .RB ` +folder "' defaults to the current folder"
620 .RB ` msgs "' defaults to cur"
622 .RB ` \-form\ mhl.headers '
623 .RB ` \-rcache\ ask '
624 .RB ` \-wcache\ ask '
627 If a folder is given, it will become the current folder. The last
628 message selected will become the current message.
projects / nmh / blob