1 .TH MHSHOW %manext1% 2015-02-08 "%nmhversion%"
6 mhshow \- display nmh MIME messages
26 .RB [ \-concat " | " \-noconcat ]
27 .RB [ \-textonly " | " \-notextonly ]
28 .RB [ \-inlineonly " | " \-noinlineonly ]
29 .RB [ \-header " | " \-noheader ]
38 .RB [ \-check " | " \-nocheck ]
43 command displays contents of a MIME (multi-media) message, or collection
47 manipulates multi-media messages as specified in RFC 2045 to RFC 2049.
50 only supports encodings in message bodies, and does not support the
51 encoding of message headers as specified in RFC 2047.
55 will display only the text parts of a message that are not marked as
56 attachments. This behavior can be changed by the
61 In addition, by using the
66 switches, you may limit and reorder the set of parts to be displayed,
67 based on part number and/or content type.
72 switches will override the default settings of
79 switch controls whether
81 will print a message separator header before each message that it
82 displays. The header format can be controlled using
84 to specify a file containing
86 instructions. A copy of the built-in default headerform can be found
87 in %nmhetcdir%/mhshow.header, for reference.
88 In addition to the normal set of
90 instructions, a "%{folder}" escape provides a string representing
95 will concatenate all content under one pager. If you want each part to
96 be displayed separately, you can override the default behavior with
104 to use the specified file as the source message, rather than a message
105 from a folder. If you specify this file as \*(lq-\*(rq, then
107 will accept the source message on the standard input. Note that the
108 file, or input from standard input, should be a validly formatted message,
113 be in mail drop format (to convert a file in
114 mail drop format to a folder of
121 switch can be given (one or more times) to restrict the set of
122 subparts that will be displayed. (Obviously with no
124 switches, all parts will be considered.) If a
126 switch specifies a specific subpart (i.e., a "leaf" in the tree of
127 MIME parts), then that part will always be displayed. If a
129 switch references a multipart/alternative part, then (in
132 switch) only the default subpart of that multipart will be displayed.
134 A part specification consists of a series of numbers separated by dots.
135 For example, in a multipart content containing three parts, these
136 would be named as 1, 2, and 3, respectively. If part 2 was also a
137 multipart content containing two parts, these would be named as 2.1 and
138 2.2, respectively. Note that the
140 switch is effective only for messages containing a multipart content.
141 If a message has some other kind of content, or if the part is itself
142 another multipart content, the
144 switch will not prevent the content from being acted upon.
148 switch can also be used to restrict (or, when used in conjunction with
150 to further restrict) the display of parts according to content type.
153 switches part will only select the first match from a multipart/alternative,
154 even if there is more than one subpart that matches (one of) the given
161 switches alone will cause either switch to select the part(s) they match.
162 Using them together will select only the part(s) matched by both (sets of)
163 switches. In other words, the result is the intersection, and not the union,
164 of their separate match results.
166 A content specification consists of a content type and a subtype.
167 The initial list of \*(lqstandard\*(rq content types and subtypes can
168 be found in RFC 2046.
170 A list of commonly used contents is briefly reproduced here:
174 .ta \w'application 'u
178 multipart mixed, alternative, digest, parallel
179 message rfc822, partial, external-body
180 application octet-stream, postscript
187 A legal MIME message must contain a subtype specification.
189 To specify a content, regardless of its subtype, just use the
190 name of the content, e.g., \*(lqaudio\*(rq. To specify a specific
191 subtype, separate the two with a slash, e.g., \*(lqaudio/basic\*(rq.
192 Note that regardless of the values given to the
194 switch, a multipart content (of any subtype listed above) is always
195 acted upon. Further note that if the
197 switch is used, and it is desirable to act on a message/external-body
200 switch must be used twice: once for message/external-body and once
201 for the content externally referenced.
206 will select the "best" displayable subpart from multipart/alternative
209 switch can be used (one or more times, in order of descending
210 preference) to let MH know which content types from a
211 multipart/alternative MIME part are preferred by the user, in order to
212 override the default selection for display. For example, mail is
213 often sent containing both plaintext and HTML-formatted versions of
214 the same content, and the HTML version is usually indicated to be the
215 "best" format for viewing. Using \*(lq-prefer text/plain\*(rq will
216 cause the plaintext version to be displayed if possible, but still
217 allow display of the HTML part if there is no plaintext subpart
218 available. Using \*(lq-prefer text/plain -prefer image/png\*(rq
219 would add a preference for PNG images, which might or might not
220 ever appear in the same multipart/alternative section with text/plain.
221 Implementation note: RFC 2046 requires that the subparts
222 of a multipart/alternative be ordered according to "faithfulness to
223 the original content", and MH by default selects the subpart ranked
224 most "faithful" by that ordering. The
226 switch reorders the alternative parts (only internally, never changing
227 the message file) to move the user's preferred part(s) to the "most
228 faithful" position. Thus, when viewed by
230 the ordering of multipart/alternative parts will appear to change when
231 invoked with or without various
234 .SS "Unseen Sequence"
235 If the profile entry \*(lqUnseen\-Sequence\*(rq is present and
238 will remove each of the messages shown from each sequence named by
240 .SS "Checking the Contents"
245 to check each content for an integrity checksum. If a content has such
246 a checksum (specified as a Content-MD5 header field), then
248 will attempt to verify the integrity of the content.
249 .SS "Showing the Contents"
250 The headers of each message are displayed with the
254 using the standard format file,
256 You may specify an alternative format file with the
259 switch. If the format file
261 is specified, then the display of the message headers is suppressed.
263 Next, the contents are extracted from the message and are stored in
264 a temporary file. Usually, the name of the temporary file is the
265 word \*(lqmhshow\*(rq followed by a string of characters. Occasionally,
266 the method used to display a content (described next), requires that
267 the file end in a specific suffix. For example, the
269 command (part of the StarOffice package) can be used to display
270 Microsoft Word content, but it uses the suffix to determine how to display
271 the file. If no suffix is present, the file is not correctly loaded.
272 Similarly, older versions of the
274 command append a \*(lq.ps\*(rq suffix to the filename if one was missing.
275 As a result, these cannot be used to read the default temporary file.
277 To get around this, your profile can contain lines of the form:
280 mhshow-suffix-<type>/<subtype>: <suffix>
286 mhshow-suffix-<type>: <suffix>
289 to specify a suffix which can be automatically added to the temporary
290 file created for a specific content type. For example, the following
291 lines might appear in your profile:
295 mhshow-suffix-text: .txt
296 mhshow-suffix-application/msword: .doc
297 mhshow-suffix-application/PostScript: .ps
301 to automatically append a suffix to the temporary files.
303 The method used to display the different contents in the messages bodies
304 will be determined by a \*(lqdisplay string\*(rq. To find the display
307 will first search your profile for an entry of the form:
310 mhshow-show-<type>/<subtype>
315 will search for an entry of the form:
321 to determine the display string.
323 If a display string is found, any escapes (given below) will be expanded.
324 The result will be executed under \*(lq/bin/sh\*(rq, with the standard input
327 The display string may contain the following escapes:
332 %a Insert parameters from Content-Type field
333 %{parameter} Insert the parameter value from the Content-Type field
334 %f Insert filename containing content
335 %F %f, and stdin is terminal not content
336 %l display listing prior to displaying content
337 %s Insert content subtype
338 %d Insert content description
339 %% Insert the character %
344 will execute at most one display string at any given time, and wait
345 for the current display string to finish execution before executing
346 the next display string.
348 The {parameter} escape is typically used in a command line argument
349 that should only be present if it has a non-null value. Its value
350 will be wrapped with single quotes if the escape is not so wrapped.
351 Shell parameter expansion can construct the argument only when it is
356 mhshow-show-text/html: charset=%{charset};
357 w3m ${charset:+-I $charset} -T text/html %F
361 That example also shows the use of indentation to signify continuation:
362 the two text lines combine to form a single entry. Note that when
363 dealing with text that has been converted internally by
365 the \*(lqcharset\*(rq parameter will reflect the target character set
366 of the text, rather than the original character set in the message.
368 Note that if the content being displayed is multipart, but not one of
369 the subtypes listed above, then the f- and F-escapes expand to multiple
370 filenames, one for each subordinate content. Furthermore, stdin is not
371 redirected from the terminal to the content.
373 If a display string is not found,
375 behaves as if these profile entries were supplied and supported:
379 mhshow-show-text/plain: %lmoreproc %F
380 mhshow-show-message/rfc822: %lshow -file %F
384 Note that \*(lqmoreproc\*(rq is not supported in user profile display
387 If a subtype of type text doesn't have a profile entry, it will be
388 treated as text/plain.
391 has default methods for handling multipart messages of subtype
392 mixed, alternative, parallel, and digest. Any unknown subtype of type
393 multipart (without a profile entry), will be treated as multipart/mixed.
395 If none of these apply, then
397 will check to see if the message has an application/octet-stream content
398 with parameter \*(lqtype=tar\*(rq.
401 will use an appropriate command. If not,
405 Example entries might be:
409 mhshow-show-audio/basic: raw2audio 2>/dev/null | play
410 mhshow-show-image: xv %f
411 mhshow-show-application/PostScript: lpr -Pps
415 If an f- or F-escape is not quoted with single quotes, its expansion
416 will be wrapped with single quotes.
420 will process each message serially\0--\0it won't start showing the next
421 message until all the commands executed to display the current message
423 .SS "Showing Alternate Character Sets"
428 then all text/plain parts of the message(s) will be displayed using
429 the character set of the current locale. See the
431 man page for how to determine whether your
433 installation includes
435 support. To convert text parts other than text/plain, or if
439 an external program can be used, as described next.
441 Because a content of type text might be in a non-ASCII character
444 encounters a \*(lqcharset\*(rq parameter for this content, it checks
445 if your terminal can display this character set natively.
447 checks this by examining the current character set defined by the
449 environment variables. If the value of the locale character set is equal
450 to the value of the charset parameter, then
453 display this content without any additional setup. If the locale is not
456 will assume a value of \*(lqUS-ASCII\*(rq.
457 If the character set cannot be displayed natively, then
459 will look for an entry of the form:
462 mhshow-charset-<charset>
465 which should contain a command creating an environment to render
466 the character set. This command string should containing a single
467 \*(lq%s\*(rq, which will be filled-in with the command to display the
470 Example entries might be:
473 mhshow-charset-iso-8859-1: xterm -fn '-*-*-medium-r-normal-*-*-120-*-*-c-*-iso8859-*' -e %s
479 mhshow-charset-iso-8859-1: '%s'
482 The first example tells
486 and load the appropriate character set for that message content.
490 that your pager (or other program handling that content type) can
491 handle that character set, and that no special processing is
494 Note that many pagers strip off the high-order bit, or have problems
495 displaying text with the high-order bit set. However, the pager
497 has support for single-octet character sets. For example, messages
498 encoded in the ISO-8859-1 character set can be viewed using
500 with these environment variable settings:
510 The first setting tells
512 to use the ISO-8859-1 definition to determine whether a character is
513 \*(lqnormal\*(rq, \*(lqcontrol\*(lq, or \*(lqbinary\*(rq.
514 The second setting tells
516 not to warn you if it encounters a file that has non-ASCII characters.
521 and it will get called automatically. (To handle other single-octet
522 character sets, look at the
524 manual entry for information about the LESSCHARDEF environment variable.)
525 .SS "Messages of Type message/partial"
527 cannot directly display messages of type partial.
528 You must first reassemble them into a normal message using
533 .SS "External Access"
534 For contents of type message/external-body,
536 supports these access-types:
550 For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types,
552 will look for the \*(lqnmh-access-ftp\*(rq profile entry, e.g.,
555 nmh-access-ftp: myftp.sh
558 to determine the pathname of a program to perform the FTP retrieval.
560 This program is invoked with these arguments:
564 domain name of FTP-site
570 \*(lqascii\*(rq or \*(lqbinary\*(rq
574 The program should terminate with an exit status of zero if the
575 retrieval is successful, and a non-zero exit status otherwise.
577 For the \*(lqurl\*(rq access-type,
579 will look for the \*(lqnmh-access-url\*(rq profile entry. See
582 .SS "The Content Cache"
585 encounters an external content containing a \*(lqContent-ID:\*(rq field,
586 and if the content allows caching, then depending on the caching behavior of
588 the content might be read from or written to a cache.
590 The caching behavior of
592 is controlled with the
596 switches, which define the policy for reading from, and writing to, the cache,
597 respectively. One of four policies may be specified: \*(lqpublic\*(rq,
600 should make use of a publicly-accessible content cache; \*(lqprivate\*(rq,
603 should make use of the user's private content cache;
604 \*(lqnever\*(rq, indicating that
606 should never make use of caching; and, \*(lqask\*(rq, indicating that
610 There are two directories where contents may be cached: the profile entry
611 \*(lqnmh-cache\*(rq names a directory containing world-readable contents, and,
612 the profile entry \*(lqnmh-private-cache\*(rq names a directory containing
613 private contents. The former should be an absolute (rooted) directory name.
621 might be used if you didn't care that the cache got wiped after each
622 reboot of the system. The latter is interpreted relative to the user's
623 nmh directory, if not rooted, e.g.,
626 nmh-private-cache: .cache
629 (which is the default value).
630 .SS "User Environment"
631 Because the display environment in which
633 operates may vary for different machines,
635 will look for the environment variable MHSHOW. If present, this specifies
636 the name of an additional user profile which should be read.
637 Hence, when a user logs in on a particular display device, this environment
638 variable should be set to refer to a file containing definitions useful
639 for the given display device.
640 Normally, only entries that deal with the methods to display different
641 content type and subtypes
645 mhshow-show-<type>/<subtype>
650 need be present in this additional profile. Finally,
652 will attempt to consult
655 %nmhetcdir%/mhn.defaults
658 which is created automatically during
662 See "Profile Lookup" in
664 for the profile search order, and for how duplicate entries are treated.
665 .SS Content-Type Marker
667 will display a marker containing information about the part being displayed
668 next. The default marker can be changed using the
670 switch to specify a file containing
672 instructions to use when displaying the content marker. A copy of the
673 default markform can be found in %nmhetcdir%/mhshow.marker, for
674 reference. In addition to the normal set of
676 instructions, the following
678 escapes are supported:
682 .ta \w'cdispo-<PARAM> 'u +\w'Returns 'u
683 .I "Escape Returns Description"
684 part string MIME part number
685 content\-type string MIME Content\-Type of part
686 description string Content\-Description header
687 disposition string Content disposition (attachment or inline)
688 ctype-<PARAM> string Value of <PARAM> from Content\-Type header
689 cdispo-<PARAM> string Value of <PARAM> from
690 Content\-Disposition header
691 %(size) integer The size of the decoded part, in bytes
692 %(unseen) boolean Returns true for suppressed parts
694 In this context, the %(unseen) function indicates whether
696 has decided to not display a particular part due to the
702 All MIME parameters and the \*(lqContent-Description\*(rq header will have
703 RFC 2231 decoding applied and be converted to the local character set.
706 looks for all format files and mhn.defaults in multiple locations:
707 absolute pathnames are accessed directly, tilde expansion is done on
708 usernames, and files are searched for in the user's
710 directory, as specified in their profile. If not found there, the directory
711 .RI \*(lq %nmhetcdir% \*(rq
716 .ta \w'%nmhetcdir%/ExtraBigFileName 'u
717 ^$HOME/.mh_profile~^The user profile
718 ^$MHSHOW~^Additional profile entries
719 ^%nmhetcdir%/mhn.defaults~^System default MIME profile entries
720 ^%nmhetcdir%/mhl.headers~^The headers template
721 ^%nmhetcdir%/mhshow.marker~^Example content marker
722 ^%nmhetcdir%/mhshow.header~^Example message separator header
724 .SH "PROFILE COMPONENTS"
728 .ta \w'ExtraBigProfileName 'u
729 ^Path:~^To determine the user's nmh directory
730 ^Current\-Folder:~^To find the default current folder
731 ^Unseen\-Sequence:~^To name sequences denoting unseen messages
732 ^mhlproc:~^Default program to display message headers
733 ^nmh-access-ftp:~^Program to retrieve contents via FTP
734 ^nmh-access-url:~^Program to retrieve contents via HTTP
735 ^nmh-cache~^Public directory to store cached external contents
736 ^nmh-private-cache~^Personal directory to store cached external contents
737 ^mhshow-charset-<charset>~^Template for environment to render character sets
738 ^mhshow-show-<type>*~^Template for displaying contents
739 ^moreproc:~^Default program to display text/plain content
751 .RB ` +folder "' defaults to the current folder"
752 .RB ` msgs "' defaults to cur"
757 .RB ` \-form\ mhl.headers '
758 .RB ` \-rcache\ ask '
759 .RB ` \-wcache\ ask '
762 If a folder is given, it will become the current folder. The last
763 message selected will become the current message.
projects / nmh / blob