1 .TH MHSHOW %manext1% 2015-02-08 "%nmhversion%"
6 mhshow \- display nmh MIME messages
27 .RB [ \-concat " | " \-noconcat ]
28 .RB [ \-textonly " | " \-notextonly ]
29 .RB [ \-inlineonly " | " \-noinlineonly ]
30 .RB [ \-header " | " \-noheader ]
39 .RB [ \-check " | " \-nocheck ]
44 command displays contents of a MIME (multi-media) message, or collection
48 manipulates multi-media messages as specified in RFC 2045 to RFC 2049.
51 only supports encodings in message bodies, and does not support the
52 encoding of message headers as specified in RFC 2047.
56 will display only the text parts of a message that are not marked as
57 attachments. 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 controls 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 headerform can be found
88 in %nmhetcdir%/mhshow.header, for reference.
89 In addition to the normal set of
91 instructions, a "%{folder}" escape provides a string representing
96 will concatenate all content under one pager. If you want each part to
97 be displayed separately, you can override the default behavior with
105 to use the specified file as the source message, rather than a message
106 from a folder. If you specify this file as \*(lq-\*(rq, then
108 will accept the source message on the standard input. Note that the
109 file, or input from standard input, should be a validly formatted message,
114 be in mail drop format (to convert a file in
115 mail drop format to a folder of
122 switch can be given (one or more times) to restrict the set of
123 subparts that will be displayed. (Obviously with no
125 switches, all parts will be considered.) If a
127 switch specifies a specific subpart (i.e., a "leaf" in the tree of
128 MIME parts), then that part will always be displayed. If a
130 switch references a multipart/alternative part, then (in
133 switch) only the default subpart of that multipart will be displayed.
135 A part specification consists of a series of numbers separated by dots.
136 For example, in a multipart content containing three parts, these
137 would be named as 1, 2, and 3, respectively. If part 2 was also a
138 multipart content containing two parts, these would be named as 2.1 and
139 2.2, respectively. Note that the
141 switch is effective only for messages containing a multipart content.
142 If a message has some other kind of content, or if the part is itself
143 another multipart content, the
145 switch will not prevent the content from being acted upon.
149 switch can also be used to restrict (or, when used in conjunction with
151 to further restrict) the display of parts according to content type.
154 switches part will only select the first match from a multipart/alternative,
155 even if there is more than one subpart that matches (one of) the given
162 switches alone will cause either switch to select the part(s) they match.
163 Using them together will select only the part(s) matched by both (sets of)
164 switches. In other words, the result is the intersection, and not the union,
165 of their separate match results.
167 A content specification consists of a content type and a subtype.
168 The initial list of \*(lqstandard\*(rq content types and subtypes can
169 be found in RFC 2046.
171 A list of commonly used contents is briefly reproduced here:
175 .ta \w'application 'u
179 multipart mixed, alternative, digest, parallel
180 message rfc822, partial, external-body
181 application octet-stream, postscript
188 A legal MIME message must contain a subtype specification.
190 To specify a content, regardless of its subtype, just use the
191 name of the content, e.g., \*(lqaudio\*(rq. To specify a specific
192 subtype, separate the two with a slash, e.g., \*(lqaudio/basic\*(rq.
193 Note that regardless of the values given to the
195 switch, a multipart content (of any subtype listed above) is always
196 acted upon. Further note that if the
198 switch is used, and it is desirable to act on a message/external-body
201 switch must be used twice: once for message/external-body and once
202 for the content externally referenced.
207 will select the "best" displayable subpart from multipart/alternative
210 switch can be used (one or more times, in order of ascending
211 preference) to let MH know which content types from a
212 multipart/alternative MIME part are preferred by the user, in order to
213 override the default selection for display. For example, mail is
214 often sent containing both plaintext and HTML-formatted versions of
215 the same content, and the HTML version is usually indicated to be the
216 "best" format for viewing. Using \*(lq-prefer text/plain\*(rq will
217 cause the plaintext version to be displayed if possible, but still
218 allow display of the HTML part if there is no plaintext subpart
219 available. Using \*(lq-prefer text/plain -prefer image/png\*(rq
220 would add a preference for PNG images, which might or might not
221 ever appear in the same multipart/alternative section with text/plain.
222 Implementation note: RFC 2046 requires that the subparts
223 of a multipart/alternative be ordered according to "faithfulness to
224 the original content", and MH by default selects the subpart ranked
225 most "faithful" by that ordering. The
227 switch reorders the alternative parts (only internally, never changing
228 the message file) to move the user's preferred part(s) to the "most
229 faithful" position. Thus, when viewed by
231 the ordering of multipart/alternative parts will appear to change when
232 invoked with or without various
234 switches. Since the last of multiple
238 on the command line will override any in a profile entry.
242 switch will cancel any previous
245 .SS "Unseen Sequence"
246 If the profile entry \*(lqUnseen\-Sequence\*(rq is present and
249 will remove each of the messages shown from each sequence named by
251 .SS "Checking the Contents"
256 to check each content for an integrity checksum. If a content has such
257 a checksum (specified as a Content-MD5 header field), then
259 will attempt to verify the integrity of the content.
260 .SS "Showing the Contents"
261 The headers of each message are displayed with the
265 using the standard format file,
267 You may specify an alternative format file with the
270 switch. If the format file
272 is specified, then the display of the message headers is suppressed.
274 Next, the contents are extracted from the message and are stored in
275 a temporary file. Usually, the name of the temporary file is the
276 word \*(lqmhshow\*(rq followed by a string of characters. Occasionally,
277 the method used to display a content (described next), requires that
278 the file end in a specific suffix. For example, the
280 command (part of the StarOffice package) can be used to display
281 Microsoft Word content, but it uses the suffix to determine how to display
282 the file. If no suffix is present, the file is not correctly loaded.
283 Similarly, older versions of the
285 command append a \*(lq.ps\*(rq suffix to the filename if one was missing.
286 As a result, these cannot be used to read the default temporary file.
288 To get around this, your profile can contain lines of the form:
291 mhshow-suffix-<type>/<subtype>: <suffix>
297 mhshow-suffix-<type>: <suffix>
300 to specify a suffix which can be automatically added to the temporary
301 file created for a specific content type. For example, the following
302 lines might appear in your profile:
306 mhshow-suffix-text: .txt
307 mhshow-suffix-application/msword: .doc
308 mhshow-suffix-application/PostScript: .ps
312 to automatically append a suffix to the temporary files.
314 The matching with the content type identifier is case-insensitive, both in
315 mhshow-suffix-<type> and mhshow-show-<type> (below) profile entries.
317 The method used to display the different contents in the messages bodies
318 will be determined by a \*(lqdisplay string\*(rq. To find the display
321 will first search your profile for an entry of the form:
324 mhshow-show-<type>/<subtype>
329 will search for an entry of the form:
335 to determine the display string.
337 If a display string is found, any escapes (given below) will be expanded.
338 The result will be executed under \*(lq/bin/sh\*(rq, with the standard input
341 The display string may contain the following escapes:
346 %a Insert parameters from Content-Type field
347 %{parameter} Insert the parameter value from the Content-Type field
348 %f Insert filename containing content
349 %F %f, and stdin is terminal not content
350 %l display listing prior to displaying content
351 %s Insert content subtype
352 %d Insert content description
353 %% Insert the character %
358 will execute at most one display string at any given time, and wait
359 for the current display string to finish execution before executing
360 the next display string.
362 The {parameter} escape is typically used in a command line argument
363 that should only be present if it has a non-null value. It is highly
364 recommended that the entire escape be wrapped in double quotes.
365 Shell parameter expansion can construct the argument only when it is
370 mhshow-show-text/html: charset="%{charset}";
371 w3m ${charset:+-I $charset} -T text/html %F
375 That example also shows the use of indentation to signify continuation:
376 the two text lines combine to form a single entry. Note that when
377 dealing with text that has been converted internally by
379 the \*(lqcharset\*(rq parameter will reflect the target character set
380 of the text, rather than the original character set in the message.
382 Note that if the content being displayed is multipart, but not one of
383 the subtypes listed above, then the f- and F-escapes expand to multiple
384 filenames, one for each subordinate content. Furthermore, stdin is not
385 redirected from the terminal to the content.
387 If a display string is not found,
389 behaves as if these profile entries were supplied and supported:
393 mhshow-show-text/plain: %lmoreproc %F
394 mhshow-show-message/rfc822: %lshow -file %F
398 Note that \*(lqmoreproc\*(rq is not supported in user profile display
401 If a subtype of type text doesn't have a profile entry, it will be
402 treated as text/plain.
405 has default methods for handling multipart messages of subtype
406 mixed, alternative, parallel, and digest. Any unknown subtype of type
407 multipart (without a profile entry), will be treated as multipart/mixed.
409 If none of these apply, then
411 will check to see if the message has an application/octet-stream content
412 with parameter \*(lqtype=tar\*(rq.
415 will use an appropriate command. If not,
419 Example entries might be:
423 mhshow-show-audio/basic: raw2audio 2>/dev/null | play
424 mhshow-show-image: xv %f
425 mhshow-show-application/PostScript: lpr -Pps
429 If an f- or F-escape is not quoted with single quotes, its expansion
430 will be wrapped with single quotes.
434 will process each message serially\0--\0it won't start showing the next
435 message until all the commands executed to display the current message
437 .SS "Showing Alternate Character Sets"
442 then all text/plain parts of the message(s) will be displayed using
443 the character set of the current locale. See
445 for how to determine whether your
447 installation includes
449 support. To convert text parts other than text/plain, or if
453 an external program can be used, as described next.
455 Because a content of type text might be in a non-ASCII character
458 encounters a \*(lqcharset\*(rq parameter for this content, it checks
459 if your terminal can display this character set natively.
461 checks this by examining the current character set defined by the
463 environment variables. 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
500 and load the appropriate character set for that message content.
504 that your pager (or other program handling that content type) can
505 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 viewed using
514 with these environment variable settings:
524 The first setting tells
526 to use the ISO-8859-1 definition to determine whether a character is
527 \*(lqnormal\*(rq, \*(lqcontrol\*(lq, or \*(lqbinary\*(rq.
528 The second setting tells
530 not to warn you if it encounters a file that has non-ASCII characters.
535 and it will get called automatically. (To handle other single-octet
536 character sets, look at the
538 manual entry for information about the LESSCHARDEF environment variable.)
539 .SS "Messages of Type message/partial"
541 cannot directly display messages of type partial.
542 You must first reassemble them into a normal message using
547 .SS "External Access"
548 For contents of type message/external-body,
550 supports these access-types:
564 For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types,
566 will look for the \*(lqnmh-access-ftp\*(rq profile entry, e.g.,
569 nmh-access-ftp: myftp.sh
572 to determine the pathname of a program to perform the FTP retrieval.
574 This program is invoked with these arguments:
578 domain name of FTP-site
584 \*(lqascii\*(rq or \*(lqbinary\*(rq
588 The program should terminate with an exit status of zero if the
589 retrieval is successful, and a non-zero exit status otherwise.
591 For the \*(lqurl\*(rq access-type,
593 will look for the \*(lqnmh-access-url\*(rq profile entry. See
596 .SS "The Content Cache"
599 encounters an external content containing a \*(lqContent-ID:\*(rq field,
600 and if the content allows caching, then depending on the caching behavior of
602 the content might be read from or written to a cache.
604 The caching behavior of
606 is controlled with the
610 switches, which define the policy for reading from, and writing to, the cache,
611 respectively. One of four policies may be specified: \*(lqpublic\*(rq,
614 should make use of a publicly-accessible content cache; \*(lqprivate\*(rq,
617 should make use of the user's private content cache;
618 \*(lqnever\*(rq, indicating that
620 should never make use of caching; and, \*(lqask\*(rq, indicating that
624 There are two directories where contents may be cached: the profile entry
625 \*(lqnmh-cache\*(rq names a directory containing world-readable contents, and,
626 the profile entry \*(lqnmh-private-cache\*(rq names a directory containing
627 private contents. The former should be an absolute (rooted) directory name.
635 might be used if you didn't care that the cache got wiped after each
636 reboot of the system. The latter is interpreted relative to the user's
637 nmh directory, if not rooted, e.g.,
640 nmh-private-cache: .cache
643 (which is the default value).
644 .SS "User Environment"
645 Because the display environment in which
647 operates may vary for different machines,
649 will look for the environment variable MHSHOW. If present, this specifies
650 the name of an additional user profile which should be read.
651 Hence, when a user logs in on a particular display device, this environment
652 variable should be set to refer to a file containing definitions useful
653 for the given display device.
654 Normally, only entries that deal with the methods to display different
655 content type and subtypes
659 mhshow-show-<type>/<subtype>
664 need be present in this additional profile. Finally,
666 will attempt to consult
669 %nmhetcdir%/mhn.defaults
672 which is created automatically during
676 See "Profile Lookup" in
678 for the profile search order, and for how duplicate entries are treated.
679 .SS Content-Type Marker
681 will display a marker containing information about the part being displayed
682 next. The default marker can be changed using the
684 switch to specify a file containing
686 instructions to use when displaying the content marker. A copy of the
687 default markform can be found in %nmhetcdir%/mhshow.marker, for
688 reference. In addition to the normal set of
690 instructions, the following
692 escapes are supported:
696 .ta \w'cdispo-<PARAM> 'u +\w'Returns 'u
697 .I "Escape Returns Description"
698 part string MIME part number
699 content\-type string MIME Content\-Type of part
700 description string Content\-Description header
701 disposition string Content disposition (attachment or inline)
702 ctype-<PARAM> string Value of <PARAM> from Content\-Type header
703 cdispo-<PARAM> string Value of <PARAM> from
704 Content\-Disposition header
705 %(size) integer The size of the decoded part, in bytes
706 %(unseen) boolean Returns true for suppressed parts
708 In this context, the %(unseen) function indicates whether
710 has decided to not display a particular part due to the
716 All MIME parameters and the \*(lqContent-Description\*(rq header will have
717 RFC 2231 decoding applied and be converted to the local character set.
720 looks for all format files and mhn.defaults in multiple locations:
721 absolute pathnames are accessed directly, tilde expansion is done on
722 usernames, and files are searched for in the user's
724 directory, as specified in their profile. If not found there, the directory
725 .RI \*(lq %nmhetcdir% \*(rq
730 .ta \w'%nmhetcdir%/ExtraBigFileName 'u
731 ^$HOME/.mh_profile~^The user profile
732 ^$MHSHOW~^Additional profile entries
733 ^%nmhetcdir%/mhn.defaults~^System default MIME profile entries
734 ^%nmhetcdir%/mhl.headers~^The headers template
735 ^%nmhetcdir%/mhshow.marker~^Example content marker
736 ^%nmhetcdir%/mhshow.header~^Example message separator header
738 .SH "PROFILE COMPONENTS"
742 .ta \w'ExtraBigProfileName 'u
743 ^Path:~^To determine the user's nmh directory
744 ^Current\-Folder:~^To find the default current folder
745 ^Unseen\-Sequence:~^To name sequences denoting unseen messages
746 ^mhlproc:~^Default program to display message headers
747 ^nmh-access-ftp:~^Program to retrieve contents via FTP
748 ^nmh-access-url:~^Program to retrieve contents via HTTP
749 ^nmh-cache~^Public directory to store cached external contents
750 ^nmh-private-cache~^Personal directory to store cached external contents
751 ^mhshow-charset-<charset>~^Template for environment to render character sets
752 ^mhshow-show-<type>*~^Template for displaying contents
753 ^moreproc:~^Default program to display text/plain content
765 .RB ` +folder "' defaults to the current folder"
766 .RB ` msgs "' defaults to cur"
771 .RB ` \-form\ mhl.headers '
772 .RB ` \-rcache\ ask '
773 .RB ` \-wcache\ ask '
776 If a folder is given, it will become the current folder. The last
777 message selected will become the current message.
projects / nmh / blob