1 .TH MHSHOW %manext1% "March 24, 2016" "%nmhversion%"
6 mhshow \- display MIME messages
26 .RB [ \-concat " | " \-noconcat ]
27 .RB [ \-textonly " | " \-notextonly ]
28 .RB [ \-inlineonly " | " \-noinlineonly ]
29 .RB [ \-header " | " \-noheader ]
38 .RB [ \-check " | " \-nocheck ]
43 command display contents of a MIME (multi-media)
44 message or collection of messages.
47 manipulates multi-media messages as specified in
48 RFC 2045 to RFC 2049. Currently
51 encodings in message bodies, and does not support the encoding of
52 message headers as specified in RFC 2047.
56 will display only text parts of a message that are not marked as attachments.
57 This behavior can be changed by the
62 In addition, by using the
67 switches, you may limit and reorder the set of parts to be displayed,
68 based on part number and/or content type.
73 switches will override the default settings of
80 switch control whether
82 will print a message separator header before each message that it
83 displays. The header format can be controlled using
85 to specify a file containing
87 instructions. A copy of the built-in default
88 headerform can be found in %nmhetcdir%/mhshow.header, for reference.
89 In addition to the normal set of
91 instructions, a "%{folder}" escape provides a
92 string representing the current folder.
96 will concatenate all content under one pager. If you want each part to
97 displayed separately, you can override the default behavior with
105 to use the specified file as
106 the source message, rather than a message from a folder. If you specify
107 this file as \*(lq-\*(rq, then
109 will accept the source message
110 on the standard input. Note that the file, or input from standard input
111 should be a validly formatted message, just like any other
115 be in mail drop format (to convert a file in
116 mail drop format to a folder of
123 switch can be used (one or more times) to restrict the
124 set of subparts that will be displayed. (Obviously with no
126 switches, all parts will be considered.) If a
128 switch specifies a specific subpart (i.e., a "leaf" in the tree of
129 MIME parts), then that part will always be displayed. If a
131 switch references a multipart/alternative part, then (in
134 switch) only the default subpart of that multipart will be displayed.
136 A part specification consists of a series of numbers separated by dots.
137 For example, in a multipart content containing three parts, these
138 would be named as 1, 2, and 3, respectively. If part 2 was also a
139 multipart content containing two parts, these would be named as 2.1 and
140 2.2, respectively. Note that the
142 switch is effective only for
143 messages containing a multipart content. If a message has some other
144 kind of content, or if the part is itself another multipart content, the
146 switch will not prevent the content from being acted upon.
150 switch can also be used to restrict (or, when used in conjunction with
152 to further restrict) the display of parts according to content type.
155 switches part will only select the first match
156 from a multipart/alternative, even if there is more than one
157 subpart that matches (one of) the given content type(s).
163 switches alone will cause either to select
164 the part(s) they match. Using them together will select only
165 the part(s) matched by both (sets of) switches. In other
166 words, the result is the intersection, and not the union, of their
167 separate match results.
169 A content specification consists of a content type and a subtype.
170 The initial list of \*(lqstandard\*(rq content types and subtypes can
171 be found in RFC 2046.
173 A list of commonly used contents is briefly reproduced here:
177 .ta \w'application 'u
181 multipart mixed, alternative, digest, parallel
182 message rfc822, partial, external-body
183 application octet-stream, postscript
190 A legal MIME message must contain a subtype specification.
192 To specify a content, regardless of its subtype, just use the
193 name of the content, e.g., \*(lqaudio\*(rq. To specify a specific
194 subtype, separate the two with a slash, e.g., \*(lqaudio/basic\*(rq.
195 Note that regardless of the values given to the
198 multipart content (of any subtype listed above) is always acted upon.
199 Further note that if the
201 switch is used, and it is desirable to
202 act on a message/external-body content, then the
205 be used twice: once for message/external-body and once for the content
206 externally referenced.
211 will select the "best" displayable subpart from
212 multipart/alternative content. The
214 switch can be used (one or more times, in order of descending
215 preference) to let MH know which content types from a
216 multipart/alternative MIME part are preferred by the user, in order to
217 override the default selection for display. For example, mail is
218 often sent containing both plaintext and HTML-formatted versions of
219 the same content, and the HTML version is usually indicated to be the
220 "best" format for viewing. Using \*(lq-prefer text/plain\*(rq will
221 cause the plaintext version to be displayed if possible, but still
222 allow display of the HTML part if there is no plaintext subpart
223 available. Using \*(lq-prefer text/plain -prefer image/png\*(rq
224 would add a preference for PNG images, which might or might not
225 ever appear in the same multipart/alternative section with text/plain.
226 Implementation note: RFC 2046 requires that the subparts
227 of a multipart/alternative be ordered according to "faithfulness to
228 the original content", and MH by default selects the subpart ranked
229 most "faithful" by that ordering. The
231 switch reorders the alternative parts (only internally, never changing
232 the message file) to move the user's preferred part(s) to the "most
233 faithful" position. Thus, when viewed by
235 the ordering of multipart/alternative parts will appear to change when
236 invoked with or without various
239 .SS "Unseen Sequence"
240 If the profile entry \*(lqUnseen\-Sequence\*(rq is present and
243 will remove each of the messages shown
244 from each sequence named by the profile entry.
245 .SS "Checking the Contents"
250 to check each content for an
251 integrity checksum. If a content has such a checksum (specified as a
252 Content-MD5 header field), then
254 will attempt to verify the
255 integrity of the content.
256 .SS "Showing the Contents"
257 The headers of each message are displayed with the
261 using the standard format file
263 You may specify an alternate format file with the
266 switch. If the format file
268 is specified, then the display
269 of the message headers is suppressed.
271 Next, the contents are extracted from the message and are stored in
272 a temporary file. Usually, the name of the temporary file is the
273 word \*(lqmhshow\*(rq followed by a string of characters. Occasionally,
274 the method used to display a content (described next), requires that
275 the file end in a specific suffix. For example, the
277 command (part of the StarOffice package) can be used to display
278 Microsoft Word content, but it uses the suffix to determine how to display
279 the file. If no suffix is present, the file is not correctly loaded.
280 Similarly, older versions of the
282 command append a \*(lq.ps\*(rq suffix to
283 the filename if one was missing. As a result, these cannot be used to read
284 the default temporary file.
286 To get around this, your profile can contain lines of the form:
289 mhshow-suffix-<type>/<subtype>: <suffix>
295 mhshow-suffix-<type>: <suffix>
298 to specify a suffix which can be automatically added to the temporary
299 file created for a specific content type. For example, the following
300 lines might appear in your profile:
304 mhshow-suffix-text: .txt
305 mhshow-suffix-application/msword: .doc
306 mhshow-suffix-application/PostScript: .ps
310 to automatically append a suffix to the temporary files.
312 The method used to display the different contents in the messages bodies
313 will be determined by a \*(lqdisplay string\*(rq. To find the display
316 will first search your profile for an entry of the form:
319 mhshow-show-<type>/<subtype>
322 to determine the display string. If this isn't found,
324 will search for an entry of the form:
330 to determine the display string.
332 If a display string is found, any escapes (given below) will be expanded.
333 The result will be executed under
334 \*(lq/bin/sh\*(rq, with the standard input
337 The display string may contain the following escapes:
342 %a Insert parameters from Content-Type field
343 %{parameter} Insert the parameter value from the Content-Type field
344 %f Insert filename containing content
345 %F %f, and stdin is terminal not content
346 %l display listing prior to displaying content
347 %s Insert content subtype
348 %d Insert content description
349 %% Insert the character %
355 execute at most one display string at any given time, and wait for the
356 current display string to finish execution before executing the next
359 The {parameter} escape is typically used in a command line argument
360 that should only be present if it has a non-null value. Its value
361 will be wrapped with single quotes if the escape is not so wrapped.
362 Shell parameter expansion can construct the argument only when it is
367 mhshow-show-text/html: charset=%{charset};
368 w3m ${charset:+-I $charset} -T text/html %F
372 That example also shows the use of indentation to signify continuation:
373 the two text lines combine to form a single entry. Note that when
374 dealing with text that has been converted internally by
376 the \*(lqcharset\*(rq parameter will reflect the target character set
377 of the text, rather than the original character set in the message.
379 Note that if the content being displayed is multipart, but not one of
380 the subtypes listed above, then the f- and F-escapes expand to multiple
381 filenames, one for each subordinate content. Further, stdin is not
382 redirected from the terminal to the content.
384 If a display string is not found,
386 behaves as if these profile entries were supplied and supported:
390 mhshow-show-text/plain: %lmoreproc %F
391 mhshow-show-message/rfc822: %lshow -file %F
395 Note that \*(lqmoreproc\*(rq is not supported in user profile display
398 If a subtype of type text doesn't have a profile entry, it will be
399 treated as text/plain.
402 has default methods for handling multipart messages of subtype
403 mixed, alternative, parallel, and digest. Any unknown subtype of type
404 multipart (without a profile entry), will be treated as multipart/mixed.
406 If none of these apply, then
408 will check to see if the message
409 has an application/octet-stream content with parameter \*(lqtype=tar\*(rq.
412 will use an appropriate command. If not,
416 Example entries might be:
420 mhshow-show-audio/basic: raw2audio 2>/dev/null | play
421 mhshow-show-image: xv %f
422 mhshow-show-application/PostScript: lpr -Pps
426 If an f- or F-escape is not quoted with single quotes, its expansion
427 will be wrapped with single quotes.
431 will process each message serially\0--\0it won't start
432 showing the next message until all the commands executed to display the
433 current message have terminated.
434 .SS "Showing Alternate Character Sets"
439 then all text/plain parts of the message(s) will be displayed using
440 the character set of the current locale. See the
442 man page for how determine whether your
444 installation includes
446 support. To convert text parts other
447 than text/plain, or if
451 an external program can be used, as described next.
453 Because a content of type text might be in a non-ASCII character
456 encounters a \*(lqcharset\*(rq parameter for
457 this content, it checks if your terminal can display this character
460 checks this by examining the current character set defined by the
462 environment variables.
463 If the value of the locale character set is equal
464 to the value of the charset parameter, then
467 display this content without any additional setup. If the locale is not
470 will assume a value of \*(lqUS-ASCII\*(rq.
471 If the character set cannot be displayed natively, then
473 will look for an entry of the form:
476 mhshow-charset-<charset>
479 which should contain a command creating an environment to render
480 the character set. This command string should containing a single
481 \*(lq%s\*(rq, which will be filled-in with the command to display the
484 Example entries might be:
487 mhshow-charset-iso-8859-1: xterm -fn '-*-*-medium-r-normal-*-*-120-*-*-c-*-iso8859-*' -e %s
493 mhshow-charset-iso-8859-1: '%s'
496 The first example tells
501 appropriate character set for that message content. The second example
504 that your pager (or other program handling that content
505 type) can handle that character set, and that no special processing is
508 Note that many pagers strip off the high-order bit or have problems
509 displaying text with the high-order bit set. However, the pager
511 has support for single-octet character sets. For example, messages
512 encoded in the ISO-8859-1 character set can be view using
514 with these environment variable settings:
524 The first setting tells
526 to use the ISO-8859-1 definition for
527 determining whether a character is \*(lqnormal\*(rq, \*(lqcontrol\*(lq,
528 or \*(lqbinary\*(rq. The second setting tells
531 if it encounters a file that has non-ASCII characters. Then, simply
537 called automatically. (To handle other single-octet character sets,
540 manual entry for information about the
542 environment variable.)
543 .SS "Messages of Type message/partial"
545 cannot directly display messages of type partial.
546 You must reassemble them first into a normal message using
548 Check the man page for
551 .SS "External Access"
552 For contents of type message/external-body,
554 supports these access-types:
569 For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types,
571 will look for the \*(lqnmh-access-ftp\*(rq
575 nmh-access-ftp: myftp.sh
578 to determine the pathname of a program to perform the FTP retrieval.
580 This program is invoked with these arguments:
584 domain name of FTP-site
590 \*(lqascii\*(rq or \*(lqbinary\*(rq
594 The program should terminate with an exit status of zero if the
595 retrieval is successful, and a non-zero exit status otherwise.
597 For the \*(lqurl\*(rq access\-type,
599 will look for the \*(lqnmh-access-url\*(rq
604 .SS "The Content Cache"
607 encounters an external content containing a
608 \*(lqContent-ID:\*(rq field, and if the content allows caching, then
609 depending on the caching behavior of
611 the content might be read from or written to a cache.
613 The caching behavior of
615 is controlled with the
619 switches, which define the policy for reading from,
620 and writing to, the cache, respectively. One of four policies may be
621 specified: \*(lqpublic\*(rq, indicating that
624 of a publically-accessible content cache; \*(lqprivate\*(rq, indicating
627 should make use of the user's private content cache;
628 \*(lqnever\*(rq, indicating that
630 should never make use of
631 caching; and, \*(lqask\*(rq, indicating that
635 There are two directories where contents may be cached: the profile entry
636 \*(lqnmh-cache\*(rq names a directory containing world-readable contents, and,
637 the profile entry \*(lqnmh-private-cache\*(rq names a directory containing
638 private contents. The former should be an absolute (rooted) directory
647 might be used if you didn't care that the cache got wiped after each
648 reboot of the system. The latter is interpreted relative to the user's
649 nmh directory, if not rooted, e.g.,
652 nmh-private-cache: .cache
655 (which is the default value).
656 .SS "User Environment"
657 Because the display environment in which
659 operates may vary for
662 will look for the environment variable
664 If present, this specifies the name of an additional
665 user profile which should be read. Hence, when a user logs in on a
666 particular display device, this environment variable should be set to
667 refer to a file containing definitions useful for the given display device.
668 Normally, only entries that deal with the methods to display different
669 content type and subtypes
673 mhshow-show-<type>/<subtype>
678 need be present in this additional profile. Finally,
680 will attempt to consult
683 %nmhetcdir%/mhn.defaults
686 which is created automatically during
690 See "Profile Lookup" in
692 for the profile search order, and for how duplicate entries are treated.
693 .SS Content\-Type Marker
695 will display a marker containing information about the part being displayed
696 next. The default marker can be changed using the
698 switch to specify a file containing
700 instructions to use when displaying the content marker. A copy of the
701 default markform can be found in %nmhetcdir%/mhshow.marker, for
702 reference. In addition to the normal set of
704 instructions, the following
706 escapes are supported:
710 .ta \w'cdispo-<PARAM> 'u +\w'Returns 'u
711 .I "Escape Returns Description"
712 part string MIME part number
713 content\-type string MIME Content\-Type of part
714 description string Content\-Description header
715 disposition string Content disposition (attachment or inline)
716 ctype-<PARAM> string Value of <PARAM> from Content\-Type header
717 cdispo-<PARAM> string Value of <PARAM> from
718 Content\-Disposition header
719 %(size) integer The size of the decoded part, in bytes
720 %(unseen) boolean Returns true for suppressed parts
722 In this context, the %(unseen) function indicates whether
724 has decided to not display a particular part due to the
730 All MIME parameters and the \*(lqContent-Description\*(rq header will have
731 RFC 2231 decoding applied and be converted
732 to the local character set.
736 looks for all format files and mhn.defaults in multiple locations:
737 absolute pathnames are accessed directly, tilde expansion is done on
738 usernames, and files are searched for in the user's
740 directory as specified in their profile. If not found there, the directory
741 .RI \*(lq %nmhetcdir% \*(rq
746 .ta \w'%nmhetcdir%/ExtraBigFileName 'u
747 ^$HOME/\&.mh\(ruprofile~^The user profile
748 ^$MHSHOW~^Additional profile entries
749 ^%nmhetcdir%/mhn.defaults~^System default MIME profile entries
750 ^%nmhetcdir%/mhl.headers~^The headers template
751 ^%nmhetcdir%/mhshow.marker~^Example content marker
752 ^%nmhetcdir%/mhshow.header~^Example message separator header
754 .SH "PROFILE COMPONENTS"
758 .ta \w'ExtraBigProfileName 'u
759 ^Path:~^To determine the user's nmh directory
760 ^Current\-Folder:~^To find the default current folder
761 ^Unseen\-Sequence:~^To name sequences denoting unseen messages
762 ^mhlproc:~^Default program to display message headers
763 ^nmh-access-ftp:~^Program to retrieve contents via FTP
764 ^nmh-access-url:~^Program to retrieve contents via HTTP
765 ^nmh-cache~^Public directory to store cached external contents
766 ^nmh-private-cache~^Personal directory to store cached external contents
767 ^mhshow-charset-<charset>~^Template for environment to render character sets
768 ^mhshow-show-<type>*~^Template for displaying contents
769 ^moreproc:~^Default program to display text/plain content
781 .RB ` +folder "' defaults to the current folder"
782 .RB ` msgs "' defaults to cur"
787 .RB ` \-form\ mhl.headers '
788 .RB ` \-rcache\ ask '
789 .RB ` \-wcache\ ask '
792 If a folder is given, it will become the current folder. The last
793 message selected will become the current message.
projects / nmh / blob