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,
111 message. It should NOT be in mail drop format (to convert a file in
112 mail drop format to a folder of
119 switch can be given (one or more times) to restrict the set of
120 subparts that will be displayed. (Obviously with no
122 switches, all parts will be considered.) If a
124 switch specifies a specific subpart (i.e., a "leaf" in the tree of
125 MIME parts), then that part will always be displayed. If a
127 switch references a multipart/alternative part, then (in
130 switch) only the default subpart of that multipart will be displayed.
132 A part specification consists of a series of numbers separated by dots.
133 For example, in a multipart content containing three parts, these
134 would be named as 1, 2, and 3, respectively. If part 2 was also a
135 multipart content containing two parts, these would be named as 2.1 and
136 2.2, respectively. Note that the
138 switch is effective only for messages containing a multipart content.
139 If a message has some other kind of content, or if the part is itself
140 another multipart content, the
142 switch will not prevent the content from being acted upon.
146 switch can also be used to restrict (or, when used in conjunction with
148 to further restrict) the display of parts according to content type.
151 switches part will only select the first match from a multipart/alternative,
152 even if there is more than one subpart that matches (one of) the given
159 switches alone will cause either switch to select the part(s) they match.
160 Using them together will select only the part(s) matched by both (sets of)
161 switches. In other words, the result is the intersection, and not the union,
162 of their separate match results.
164 A content specification consists of a content type and a subtype.
165 The initial list of \*(lqstandard\*(rq content types and subtypes can
166 be found in RFC 2046.
168 A list of commonly used contents is briefly reproduced here:
172 .ta \w'application 'u
176 multipart mixed, alternative, digest, parallel
177 message rfc822, partial, external-body
178 application octet-stream, postscript
185 A legal MIME message must contain a subtype specification.
187 To specify a content, regardless of its subtype, just use the
188 name of the content, e.g., \*(lqaudio\*(rq. To specify a specific
189 subtype, separate the two with a slash, e.g., \*(lqaudio/basic\*(rq.
190 Note that regardless of the values given to the
192 switch, a multipart content (of any subtype listed above) is always
193 acted upon. Further note that if the
195 switch is used, and it is desirable to act on a message/external-body
198 switch must be used twice: once for message/external-body and once
199 for the content externally referenced.
204 will select the "best" displayable subpart from multipart/alternative
207 switch can be used (one or more times, in order of descending
208 preference) to let MH know which content types from a
209 multipart/alternative MIME part are preferred by the user, in order to
210 override the default selection for display. For example, mail is
211 often sent containing both plaintext and HTML-formatted versions of
212 the same content, and the HTML version is usually indicated to be the
213 "best" format for viewing. Using \*(lq-prefer text/plain\*(rq will
214 cause the plaintext version to be displayed if possible, but still
215 allow display of the HTML part if there is no plaintext subpart
216 available. Using \*(lq-prefer text/plain -prefer image/png\*(rq
217 would add a preference for PNG images, which might or might not
218 ever appear in the same multipart/alternative section with text/plain.
219 Implementation note: RFC 2046 requires that the subparts
220 of a multipart/alternative be ordered according to "faithfulness to
221 the original content", and MH by default selects the subpart ranked
222 most "faithful" by that ordering. The
224 switch reorders the alternative parts (only internally, never changing
225 the message file) to move the user's preferred part(s) to the "most
226 faithful" position. Thus, when viewed by
228 the ordering of multipart/alternative parts will appear to change when
229 invoked with or without various
232 .SS "Unseen Sequence"
233 If the profile entry \*(lqUnseen\-Sequence\*(rq is present and
236 will remove each of the messages shown from each sequence named by
238 .SS "Checking the Contents"
243 to check each content for an integrity checksum. If a content has such
244 a checksum (specified as a Content-MD5 header field), then
246 will attempt to verify the integrity of the content.
247 .SS "Showing the Contents"
248 The headers of each message are displayed with the
252 using the standard format file,
254 You may specify an alternative format file with the
257 switch. If the format file
259 is specified, then the display of the message headers is suppressed.
261 Next, the contents are extracted from the message and are stored in
262 a temporary file. Usually, the name of the temporary file is the
263 word \*(lqmhshow\*(rq followed by a string of characters. Occasionally,
264 the method used to display a content (described next), requires that
265 the file end in a specific suffix. For example, the
267 command (part of the StarOffice package) can be used to display
268 Microsoft Word content, but it uses the suffix to determine how to display
269 the file. If no suffix is present, the file is not correctly loaded.
270 Similarly, older versions of the
272 command append a \*(lq.ps\*(rq suffix to the filename if one was missing.
273 As a result, these cannot be used to read the default temporary file.
275 To get around this, your profile can contain lines of the form:
278 mhshow-suffix-<type>/<subtype>: <suffix>
284 mhshow-suffix-<type>: <suffix>
287 to specify a suffix which can be automatically added to the temporary
288 file created for a specific content type. For example, the following
289 lines might appear in your profile:
293 mhshow-suffix-text: .txt
294 mhshow-suffix-application/msword: .doc
295 mhshow-suffix-application/PostScript: .ps
299 to automatically append a suffix to the temporary files.
301 The method used to display the different contents in the messages bodies
302 will be determined by a \*(lqdisplay string\*(rq. To find the display
305 will first search your profile for an entry of the form:
308 mhshow-show-<type>/<subtype>
313 will search for an entry of the form:
319 to determine the display string.
321 If a display string is found, any escapes (given below) will be expanded.
322 The result will be executed under \*(lq/bin/sh\*(rq, with the standard input
325 The display string may contain the following escapes:
330 %a Insert parameters from Content-Type field
331 %{parameter} Insert the parameter value from the Content-Type field
332 %f Insert filename containing content
333 %F %f, and stdin is terminal not content
334 %l display listing prior to displaying content
335 %s Insert content subtype
336 %d Insert content description
337 %% Insert the character %
342 will execute at most one display string at any given time, and wait
343 for the current display string to finish execution before executing
344 the next display string.
346 The {parameter} escape is typically used in a command line argument
347 that should only be present if it has a non-null value. Its value
348 will be wrapped with single quotes if the escape is not so wrapped.
349 Shell parameter expansion can construct the argument only when it is
354 mhshow-show-text/html: charset=%{charset};
355 w3m ${charset:+-I $charset} -T text/html %F
359 That example also shows the use of indentation to signify continuation:
360 the two text lines combine to form a single entry. Note that when
361 dealing with text that has been converted internally by
363 the \*(lqcharset\*(rq parameter will reflect the target character set
364 of the text, rather than the original character set in the message.
366 Note that if the content being displayed is multipart, but not one of
367 the subtypes listed above, then the f- and F-escapes expand to multiple
368 filenames, one for each subordinate content. Furthermore, stdin is not
369 redirected from the terminal to the content.
371 If a display string is not found,
373 behaves as if these profile entries were supplied and supported:
377 mhshow-show-text/plain: %lmoreproc %F
378 mhshow-show-message/rfc822: %lshow -file %F
382 Note that \*(lqmoreproc\*(rq is not supported in user profile display
385 If a subtype of type text doesn't have a profile entry, it will be
386 treated as text/plain.
389 has default methods for handling multipart messages of subtype
390 mixed, alternative, parallel, and digest. Any unknown subtype of type
391 multipart (without a profile entry), will be treated as multipart/mixed.
393 If none of these apply, then
395 will check to see if the message has an application/octet-stream content
396 with parameter \*(lqtype=tar\*(rq.
399 will use an appropriate command. If not,
403 Example entries might be:
407 mhshow-show-audio/basic: raw2audio 2>/dev/null | play
408 mhshow-show-image: xv %f
409 mhshow-show-application/PostScript: lpr -Pps
413 If an f- or F-escape is not quoted with single quotes, its expansion
414 will be wrapped with single quotes.
418 will process each message serially\0--\0it won't start showing the next
419 message until all the commands executed to display the current message
421 .SS "Showing Alternate Character Sets"
426 then all text/plain parts of the message(s) will be displayed using
427 the character set of the current locale. See the
429 man page for how to determine whether your
431 installation includes
433 support. To convert text parts other than text/plain, or if
437 an external program can be used, as described next.
439 Because a content of type text might be in a non-ASCII character
442 encounters a \*(lqcharset\*(rq parameter for this content, it checks
443 if your terminal can display this character set natively.
445 checks this by examining the current character set defined by the
447 environment variables. If the value of the locale character set is equal
448 to the value of the charset parameter, then
451 display this content without any additional setup. If the locale is not
454 will assume a value of \*(lqUS-ASCII\*(rq.
455 If the character set cannot be displayed natively, then
457 will look for an entry of the form:
460 mhshow-charset-<charset>
463 which should contain a command creating an environment to render
464 the character set. This command string should containing a single
465 \*(lq%s\*(rq, which will be filled-in with the command to display the
468 Example entries might be:
471 mhshow-charset-iso-8859-1: xterm -fn '-*-*-medium-r-normal-*-*-120-*-*-c-*-iso8859-*' -e %s
477 mhshow-charset-iso-8859-1: '%s'
480 The first example tells
484 and load the appropriate character set for that message content.
488 that your pager (or other program handling that content type) can
489 handle that character set, and that no special processing is
492 Note that many pagers strip off the high-order bit, or have problems
493 displaying text with the high-order bit set. However, the pager
495 has support for single-octet character sets. For example, messages
496 encoded in the ISO-8859-1 character set can be viewed using
498 with these environment variable settings:
508 The first setting tells
510 to use the ISO-8859-1 definition to determine whether a character is
511 \*(lqnormal\*(rq, \*(lqcontrol\*(lq, or \*(lqbinary\*(rq.
512 The second setting tells
514 not to warn you if it encounters a file that has non-ASCII characters.
519 and it will get called automatically. (To handle other single-octet
520 character sets, look at the
522 manual entry for information about the LESSCHARDEF environment variable.)
523 .SS "Messages of Type message/partial"
525 cannot directly display messages of type partial.
526 You must first reassemble them into a normal message using
531 .SS "External Access"
532 For contents of type message/external-body,
534 supports these access-types:
548 For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types,
550 will look for the \*(lqnmh-access-ftp\*(rq profile entry, e.g.,
553 nmh-access-ftp: myftp.sh
556 to determine the pathname of a program to perform the FTP retrieval.
558 This program is invoked with these arguments:
562 domain name of FTP-site
568 \*(lqascii\*(rq or \*(lqbinary\*(rq
572 The program should terminate with an exit status of zero if the
573 retrieval is successful, and a non-zero exit status otherwise.
575 For the \*(lqurl\*(rq access-type,
577 will look for the \*(lqnmh-access-url\*(rq profile entry. See
580 .SS "The Content Cache"
583 encounters an external content containing a \*(lqContent-ID:\*(rq field,
584 and if the content allows caching, then depending on the caching behavior of
586 the content might be read from or written to a cache.
588 The caching behavior of
590 is controlled with the
594 switches, which define the policy for reading from, and writing to, the cache,
595 respectively. One of four policies may be specified: \*(lqpublic\*(rq,
598 should make use of a publicly-accessible content cache; \*(lqprivate\*(rq,
601 should make use of the user's private content cache;
602 \*(lqnever\*(rq, indicating that
604 should never make use of caching; and, \*(lqask\*(rq, indicating that
608 There are two directories where contents may be cached: the profile entry
609 \*(lqnmh-cache\*(rq names a directory containing world-readable contents, and,
610 the profile entry \*(lqnmh-private-cache\*(rq names a directory containing
611 private contents. The former should be an absolute (rooted) directory name.
619 might be used if you didn't care that the cache got wiped after each
620 reboot of the system. The latter is interpreted relative to the user's
621 nmh directory, if not rooted, e.g.,
624 nmh-private-cache: .cache
627 (which is the default value).
628 .SS "User Environment"
629 Because the display environment in which
631 operates may vary for different machines,
633 will look for the environment variable MHSHOW. If present, this specifies
634 the name of an additional user profile which should be read.
635 Hence, when a user logs in on a particular display device, this environment
636 variable should be set to refer to a file containing definitions useful
637 for the given display device.
638 Normally, only entries that deal with the methods to display different
639 content type and subtypes
643 mhshow-show-<type>/<subtype>
648 need be present in this additional profile. Finally,
650 will attempt to consult
653 %nmhetcdir%/mhn.defaults
656 which is created automatically during
660 See "Profile Lookup" in
662 for the profile search order, and for how duplicate entries are treated.
663 .SS Content-Type Marker
665 will display a marker containing information about the part being displayed
666 next. The default marker can be changed using the
668 switch to specify a file containing
670 instructions to use when displaying the content marker. A copy of the
671 default markform can be found in %nmhetcdir%/mhshow.marker, for
672 reference. In addition to the normal set of
674 instructions, the following
676 escapes are supported:
680 .ta \w'cdispo-<PARAM> 'u +\w'Returns 'u
681 .I "Escape Returns Description"
682 part string MIME part number
683 content\-type string MIME Content\-Type of part
684 description string Content\-Description header
685 disposition string Content disposition (attachment or inline)
686 ctype-<PARAM> string Value of <PARAM> from Content\-Type header
687 cdispo-<PARAM> string Value of <PARAM> from
688 Content\-Disposition header
689 %(size) integer The size of the decoded part, in bytes
690 %(unseen) boolean Returns true for suppressed parts
692 In this context, the %(unseen) function indicates whether
694 has decided to not display a particular part due to the
700 All MIME parameters and the \*(lqContent-Description\*(rq header will have
701 RFC 2231 decoding applied and be converted to the local character set.
704 looks for all format files and mhn.defaults in multiple locations:
705 absolute pathnames are accessed directly, tilde expansion is done on
706 usernames, and files are searched for in the user's
708 directory, as specified in their profile. If not found there, the directory
709 .RI \*(lq %nmhetcdir% \*(rq
714 .ta \w'%nmhetcdir%/ExtraBigFileName 'u
715 ^$HOME/.mh_profile~^The user profile
716 ^$MHSHOW~^Additional profile entries
717 ^%nmhetcdir%/mhn.defaults~^System default MIME profile entries
718 ^%nmhetcdir%/mhl.headers~^The headers template
719 ^%nmhetcdir%/mhshow.marker~^Example content marker
720 ^%nmhetcdir%/mhshow.header~^Example message separator header
722 .SH "PROFILE COMPONENTS"
726 .ta \w'ExtraBigProfileName 'u
727 ^Path:~^To determine the user's nmh directory
728 ^Current\-Folder:~^To find the default current folder
729 ^Unseen\-Sequence:~^To name sequences denoting unseen messages
730 ^mhlproc:~^Default program to display message headers
731 ^nmh-access-ftp:~^Program to retrieve contents via FTP
732 ^nmh-access-url:~^Program to retrieve contents via HTTP
733 ^nmh-cache~^Public directory to store cached external contents
734 ^nmh-private-cache~^Personal directory to store cached external contents
735 ^mhshow-charset-<charset>~^Template for environment to render character sets
736 ^mhshow-show-<type>*~^Template for displaying contents
737 ^moreproc:~^Default program to display text/plain content
749 .RB ` +folder "' defaults to the current folder"
750 .RB ` msgs "' defaults to cur"
755 .RB ` \-form\ mhl.headers '
756 .RB ` \-rcache\ ask '
757 .RB ` \-wcache\ ask '
760 If a folder is given, it will become the current folder. The last
761 message selected will become the current message.
projects / nmh / blob