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 ascending
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
233 switches. Since the last of multiple
237 on the command line will override any in a profile entry.
238 .SS "Unseen Sequence"
239 If the profile entry \*(lqUnseen\-Sequence\*(rq is present and
242 will remove each of the messages shown from each sequence named by
244 .SS "Checking the Contents"
249 to check each content for an integrity checksum. If a content has such
250 a checksum (specified as a Content-MD5 header field), then
252 will attempt to verify the integrity of the content.
253 .SS "Showing the Contents"
254 The headers of each message are displayed with the
258 using the standard format file,
260 You may specify an alternative format file with the
263 switch. If the format file
265 is specified, then the display of the message headers is suppressed.
267 Next, the contents are extracted from the message and are stored in
268 a temporary file. Usually, the name of the temporary file is the
269 word \*(lqmhshow\*(rq followed by a string of characters. Occasionally,
270 the method used to display a content (described next), requires that
271 the file end in a specific suffix. For example, the
273 command (part of the StarOffice package) can be used to display
274 Microsoft Word content, but it uses the suffix to determine how to display
275 the file. If no suffix is present, the file is not correctly loaded.
276 Similarly, older versions of the
278 command append a \*(lq.ps\*(rq suffix to the filename if one was missing.
279 As a result, these cannot be used to read the default temporary file.
281 To get around this, your profile can contain lines of the form:
284 mhshow-suffix-<type>/<subtype>: <suffix>
290 mhshow-suffix-<type>: <suffix>
293 to specify a suffix which can be automatically added to the temporary
294 file created for a specific content type. For example, the following
295 lines might appear in your profile:
299 mhshow-suffix-text: .txt
300 mhshow-suffix-application/msword: .doc
301 mhshow-suffix-application/PostScript: .ps
305 to automatically append a suffix to the temporary files.
307 The method used to display the different contents in the messages bodies
308 will be determined by a \*(lqdisplay string\*(rq. To find the display
311 will first search your profile for an entry of the form:
314 mhshow-show-<type>/<subtype>
319 will search for an entry of the form:
325 to determine the display string.
327 If a display string is found, any escapes (given below) will be expanded.
328 The result will be executed under \*(lq/bin/sh\*(rq, with the standard input
331 The display string may contain the following escapes:
336 %a Insert parameters from Content-Type field
337 %{parameter} Insert the parameter value from the Content-Type field
338 %f Insert filename containing content
339 %F %f, and stdin is terminal not content
340 %l display listing prior to displaying content
341 %s Insert content subtype
342 %d Insert content description
343 %% Insert the character %
348 will execute at most one display string at any given time, and wait
349 for the current display string to finish execution before executing
350 the next display string.
352 The {parameter} escape is typically used in a command line argument
353 that should only be present if it has a non-null value. Its value
354 will be wrapped with single quotes if the escape is not so wrapped.
355 Shell parameter expansion can construct the argument only when it is
360 mhshow-show-text/html: charset=%{charset};
361 w3m ${charset:+-I $charset} -T text/html %F
365 That example also shows the use of indentation to signify continuation:
366 the two text lines combine to form a single entry. Note that when
367 dealing with text that has been converted internally by
369 the \*(lqcharset\*(rq parameter will reflect the target character set
370 of the text, rather than the original character set in the message.
372 Note that if the content being displayed is multipart, but not one of
373 the subtypes listed above, then the f- and F-escapes expand to multiple
374 filenames, one for each subordinate content. Furthermore, stdin is not
375 redirected from the terminal to the content.
377 If a display string is not found,
379 behaves as if these profile entries were supplied and supported:
383 mhshow-show-text/plain: %lmoreproc %F
384 mhshow-show-message/rfc822: %lshow -file %F
388 Note that \*(lqmoreproc\*(rq is not supported in user profile display
391 If a subtype of type text doesn't have a profile entry, it will be
392 treated as text/plain.
395 has default methods for handling multipart messages of subtype
396 mixed, alternative, parallel, and digest. Any unknown subtype of type
397 multipart (without a profile entry), will be treated as multipart/mixed.
399 If none of these apply, then
401 will check to see if the message has an application/octet-stream content
402 with parameter \*(lqtype=tar\*(rq.
405 will use an appropriate command. If not,
409 Example entries might be:
413 mhshow-show-audio/basic: raw2audio 2>/dev/null | play
414 mhshow-show-image: xv %f
415 mhshow-show-application/PostScript: lpr -Pps
419 If an f- or F-escape is not quoted with single quotes, its expansion
420 will be wrapped with single quotes.
424 will process each message serially\0--\0it won't start showing the next
425 message until all the commands executed to display the current message
427 .SS "Showing Alternate Character Sets"
432 then all text/plain parts of the message(s) will be displayed using
433 the character set of the current locale. See
435 for how to determine whether your
437 installation includes
439 support. To convert text parts other than text/plain, or if
443 an external program can be used, as described next.
445 Because a content of type text might be in a non-ASCII character
448 encounters a \*(lqcharset\*(rq parameter for this content, it checks
449 if your terminal can display this character set natively.
451 checks this by examining the current character set defined by the
453 environment variables. If the value of the locale character set is equal
454 to the value of the charset parameter, then
457 display this content without any additional setup. If the locale is not
460 will assume a value of \*(lqUS-ASCII\*(rq.
461 If the character set cannot be displayed natively, then
463 will look for an entry of the form:
466 mhshow-charset-<charset>
469 which should contain a command creating an environment to render
470 the character set. This command string should containing a single
471 \*(lq%s\*(rq, which will be filled-in with the command to display the
474 Example entries might be:
477 mhshow-charset-iso-8859-1: xterm -fn '-*-*-medium-r-normal-*-*-120-*-*-c-*-iso8859-*' -e %s
483 mhshow-charset-iso-8859-1: '%s'
486 The first example tells
490 and load the appropriate character set for that message content.
494 that your pager (or other program handling that content type) can
495 handle that character set, and that no special processing is
498 Note that many pagers strip off the high-order bit, or have problems
499 displaying text with the high-order bit set. However, the pager
501 has support for single-octet character sets. For example, messages
502 encoded in the ISO-8859-1 character set can be viewed using
504 with these environment variable settings:
514 The first setting tells
516 to use the ISO-8859-1 definition to determine whether a character is
517 \*(lqnormal\*(rq, \*(lqcontrol\*(lq, or \*(lqbinary\*(rq.
518 The second setting tells
520 not to warn you if it encounters a file that has non-ASCII characters.
525 and it will get called automatically. (To handle other single-octet
526 character sets, look at the
528 manual entry for information about the LESSCHARDEF environment variable.)
529 .SS "Messages of Type message/partial"
531 cannot directly display messages of type partial.
532 You must first reassemble them into a normal message using
537 .SS "External Access"
538 For contents of type message/external-body,
540 supports these access-types:
554 For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types,
556 will look for the \*(lqnmh-access-ftp\*(rq profile entry, e.g.,
559 nmh-access-ftp: myftp.sh
562 to determine the pathname of a program to perform the FTP retrieval.
564 This program is invoked with these arguments:
568 domain name of FTP-site
574 \*(lqascii\*(rq or \*(lqbinary\*(rq
578 The program should terminate with an exit status of zero if the
579 retrieval is successful, and a non-zero exit status otherwise.
581 For the \*(lqurl\*(rq access-type,
583 will look for the \*(lqnmh-access-url\*(rq profile entry. See
586 .SS "The Content Cache"
589 encounters an external content containing a \*(lqContent-ID:\*(rq field,
590 and if the content allows caching, then depending on the caching behavior of
592 the content might be read from or written to a cache.
594 The caching behavior of
596 is controlled with the
600 switches, which define the policy for reading from, and writing to, the cache,
601 respectively. One of four policies may be specified: \*(lqpublic\*(rq,
604 should make use of a publicly-accessible content cache; \*(lqprivate\*(rq,
607 should make use of the user's private content cache;
608 \*(lqnever\*(rq, indicating that
610 should never make use of caching; and, \*(lqask\*(rq, indicating that
614 There are two directories where contents may be cached: the profile entry
615 \*(lqnmh-cache\*(rq names a directory containing world-readable contents, and,
616 the profile entry \*(lqnmh-private-cache\*(rq names a directory containing
617 private contents. The former should be an absolute (rooted) directory name.
625 might be used if you didn't care that the cache got wiped after each
626 reboot of the system. The latter is interpreted relative to the user's
627 nmh directory, if not rooted, e.g.,
630 nmh-private-cache: .cache
633 (which is the default value).
634 .SS "User Environment"
635 Because the display environment in which
637 operates may vary for different machines,
639 will look for the environment variable MHSHOW. If present, this specifies
640 the name of an additional user profile which should be read.
641 Hence, when a user logs in on a particular display device, this environment
642 variable should be set to refer to a file containing definitions useful
643 for the given display device.
644 Normally, only entries that deal with the methods to display different
645 content type and subtypes
649 mhshow-show-<type>/<subtype>
654 need be present in this additional profile. Finally,
656 will attempt to consult
659 %nmhetcdir%/mhn.defaults
662 which is created automatically during
666 See "Profile Lookup" in
668 for the profile search order, and for how duplicate entries are treated.
669 .SS Content-Type Marker
671 will display a marker containing information about the part being displayed
672 next. The default marker can be changed using the
674 switch to specify a file containing
676 instructions to use when displaying the content marker. A copy of the
677 default markform can be found in %nmhetcdir%/mhshow.marker, for
678 reference. In addition to the normal set of
680 instructions, the following
682 escapes are supported:
686 .ta \w'cdispo-<PARAM> 'u +\w'Returns 'u
687 .I "Escape Returns Description"
688 part string MIME part number
689 content\-type string MIME Content\-Type of part
690 description string Content\-Description header
691 disposition string Content disposition (attachment or inline)
692 ctype-<PARAM> string Value of <PARAM> from Content\-Type header
693 cdispo-<PARAM> string Value of <PARAM> from
694 Content\-Disposition header
695 %(size) integer The size of the decoded part, in bytes
696 %(unseen) boolean Returns true for suppressed parts
698 In this context, the %(unseen) function indicates whether
700 has decided to not display a particular part due to the
706 All MIME parameters and the \*(lqContent-Description\*(rq header will have
707 RFC 2231 decoding applied and be converted to the local character set.
710 looks for all format files and mhn.defaults in multiple locations:
711 absolute pathnames are accessed directly, tilde expansion is done on
712 usernames, and files are searched for in the user's
714 directory, as specified in their profile. If not found there, the directory
715 .RI \*(lq %nmhetcdir% \*(rq
720 .ta \w'%nmhetcdir%/ExtraBigFileName 'u
721 ^$HOME/.mh_profile~^The user profile
722 ^$MHSHOW~^Additional profile entries
723 ^%nmhetcdir%/mhn.defaults~^System default MIME profile entries
724 ^%nmhetcdir%/mhl.headers~^The headers template
725 ^%nmhetcdir%/mhshow.marker~^Example content marker
726 ^%nmhetcdir%/mhshow.header~^Example message separator header
728 .SH "PROFILE COMPONENTS"
732 .ta \w'ExtraBigProfileName 'u
733 ^Path:~^To determine the user's nmh directory
734 ^Current\-Folder:~^To find the default current folder
735 ^Unseen\-Sequence:~^To name sequences denoting unseen messages
736 ^mhlproc:~^Default program to display message headers
737 ^nmh-access-ftp:~^Program to retrieve contents via FTP
738 ^nmh-access-url:~^Program to retrieve contents via HTTP
739 ^nmh-cache~^Public directory to store cached external contents
740 ^nmh-private-cache~^Personal directory to store cached external contents
741 ^mhshow-charset-<charset>~^Template for environment to render character sets
742 ^mhshow-show-<type>*~^Template for displaying contents
743 ^moreproc:~^Default program to display text/plain content
755 .RB ` +folder "' defaults to the current folder"
756 .RB ` msgs "' defaults to cur"
761 .RB ` \-form\ mhl.headers '
762 .RB ` \-rcache\ ask '
763 .RB ` \-wcache\ ask '
766 If a folder is given, it will become the current folder. The last
767 message selected will become the current message.
projects / nmh / blob