1 .TH MHSHOW %manext1% "April 9, 2014" "%nmhversion%"
6 mhshow \- display MIME messages
21 .RB [ \-concat " | " \-noconcat ]
22 .RB [ \-textonly " | " \-notextonly ]
23 .RB [ \-inlineonly " | " \-noinlineonly ]
32 .RB [ \-check " | " \-nocheck ]
39 command display contents of a MIME (multi-media)
40 message or collection of messages.
43 manipulates multi-media messages as specified in
44 RFC 2045 to RFC 2049. Currently
47 encodings in message bodies, and does not support the encoding of
48 message headers as specified in RFC 2047.
52 will display only text parts of a message that are not marked as attachments.
53 This behavior can be changed by the
58 In addition, by using the
63 further limit the scope of
65 to particular subparts (of a
66 multipart content) and/or particular content types. The inclusion of any
70 switches will override the default settings of
77 will concatenate all content under one pager. If you which each part to
78 displayed separately, you can override the default behavior with
86 to use the specified file as
87 the source message, rather than a message from a folder. If you specify
88 this file as \*(lq-\*(rq, then
90 will accept the source message
91 on the standard input. Note that the file, or input from standard input
92 should be a validly formatted message, just like any other
96 be in mail drop format (to convert a file in
97 mail drop format to a folder of
102 A part specification consists of a series of numbers separated by dots.
103 For example, in a multipart content containing three parts, these
104 would be named as 1, 2, and 3, respectively. If part 2 was also a
105 multipart content containing two parts, these would be named as 2.1 and
106 2.2, respectively. Note that the
108 switch is effective for only
109 messages containing a multipart content. If a message has some other
110 kind of content, or if the part is itself another multipart content, the
112 switch will not prevent the content from being acted upon.
114 A content specification consists of a content type and a subtype.
115 The initial list of \*(lqstandard\*(rq content types and subtypes can
116 be found in RFC 2046.
118 A list of commonly used contents is briefly reproduced here:
122 .ta \w'application 'u
126 multipart mixed, alternative, digest, parallel
127 message rfc822, partial, external-body
128 application octet-stream, postscript
135 A legal MIME message must contain a subtype specification.
137 To specify a content, regardless of its subtype, just use the
138 name of the content, e.g., \*(lqaudio\*(rq. To specify a specific
139 subtype, separate the two with a slash, e.g., \*(lqaudio/basic\*(rq.
140 Note that regardless of the values given to the `\-type' switch, a
141 multipart content (of any subtype listed above) is always acted upon.
142 Further note that if the `\-type' switch is used, and it is desirable to
143 act on a message/external-body content, then the `\-type' switch must
144 be used twice: once for message/external-body and once for the content
145 externally referenced.
146 .SS "Unseen Sequence"
147 If the profile entry \*(lqUnseen\-Sequence\*(rq is present and
150 will remove each of the messages shown
151 from each sequence named by the profile entry.
152 .SS "Checking the Contents"
157 to check each content for an
158 integrity checksum. If a content has such a checksum (specified as a
159 Content-MD5 header field), then
161 will attempt to verify the
162 integrity of the content.
163 .SS "Showing the Contents"
164 The headers of each message are displayed with the
168 using the standard format file
170 You may specify an alternate format file with the
173 switch. If the format file
175 is specified, then the display
176 of the message headers is suppressed.
178 Next, the contents are extracted from the message and are stored in
179 a temporary file. Usually, the name of the temporary file is the
180 word \*(lqmhshow\*(rq followed by a string of characters. Occasionally,
181 the method used to display a content (described next), requires that
182 the file end in a specific suffix. For example, the
184 command (part of the StarOffice package) can be used to display
185 Microsoft Word content, but it uses the suffix to determine how to display
186 the file. If no suffix is present, the file is not correctly loaded.
187 Similarily, older versions of the
189 command append a \*(lq.ps\*(rq suffix to
190 the filename if one was missing. As a result, these cannot be used to read
191 the default temporary file.
193 To get around this, your profile can contain lines of the form:
196 mhshow-suffix-<type>/<subtype>: <suffix>
202 mhshow-suffix-<type>: <suffix>
205 to specify a suffix which can be automatically added to the temporary
206 file created for a specific content type. For example, the following
207 lines might appear in your profile:
211 mhshow-suffix-text: .txt
212 mhshow-suffix-application/msword: .doc
213 mhshow-suffix-application/PostScript: .ps
217 to automatically append a suffix to the temporary files.
219 The method used to display the different contents in the messages bodies
220 will be determined by a \*(lqdisplay string\*(rq. To find the display
223 will first search your profile for an entry of the form:
226 mhshow-show-<type>/<subtype>
229 to determine the display string. If this isn't found,
231 will search for an entry of the form:
237 to determine the display string.
239 If a display string is found, any escapes (given below) will be expanded.
240 The result will be executed under
241 \*(lq/bin/sh\*(rq, with the standard input
244 The display string may contain the following escapes:
249 %a Insert parameters from Content-Type field
250 %{parameter} Insert the parameter value from the Content-Type field
251 %f Insert filename containing content
252 %F %f, and stdin is terminal not content
253 %l display listing prior to displaying content
254 %s Insert content subtype
255 %d Insert content description
256 %% Insert the character %
262 execute at most one display string at any given time, and wait for the
263 current display string to finish execution before executing the next
266 The {parameter} escape is typically used in a command line argument
267 that should only be present if it has a non-null value. Its value
268 will be wrapped with single quotes if the escape is not so wrapped.
269 Shell parameter expansion can construct the argument only when it is
274 mhshow-show-text/html: charset=%{charset};
275 w3m ${charset:+-I $charset} -T text/html %F
279 That example also shows the use of indentation to signify continuation:
280 the two text lines combine to form a single entry. Note that when
281 dealing with text that has been converted internally by
283 the \*(lqcharset\*(rq parameter will reflect the target character set
284 of the text, rather than the original character set in the message.
286 Note that if the content being displayed is multipart, but not one of
287 the subtypes listed above, then the f- and F-escapes expand to multiple
288 filenames, one for each subordinate content. Further, stdin is not
289 redirected from the terminal to the content.
291 If a display string is not found,
293 behaves as if these profile entries were supplied and supported:
297 mhshow-show-text/plain: %lmoreproc %F
298 mhshow-show-message/rfc822: %lshow -file %F
302 Note that \*(lqmoreproc\*(rq is not supported in user profile display
305 If a subtype of type text doesn't have a profile entry, it will be
306 treated as text/plain.
309 has default methods for handling multipart messages of subtype
310 mixed, alternative, parallel, and digest. Any unknown subtype of type
311 multipart (without a profile entry), will be treated as multipart/mixed.
313 If none of these apply, then
315 will check to see if the message
316 has an application/octet-stream content with parameter \*(lqtype=tar\*(rq.
319 will use an appropriate command. If not,
323 Example entries might be:
327 mhshow-show-audio/basic: raw2audio 2>/dev/null | play
328 mhshow-show-image: xv %f
329 mhshow-show-application/PostScript: lpr -Pps
333 If an f- or F-escape is not quoted with single quotes, its expansion
334 will be wrapped with single quotes.
338 will process each message serially\0--\0it won't start
339 showing the next message until all the commands executed to display the
340 current message have terminated.
341 .SS "Showing Alternate Character Sets"
346 then all text/plain parts of the message(s) will be displayed using
347 the character set of the current locale. See the
349 man page for how determine whether your
351 installation includes
353 support. To convert text parts other
354 than text/plain, or if
358 an external program can be used, as described next.
360 Because a content of type text might be in a non-ASCII character
363 encounters a \*(lqcharset\*(rq parameter for
364 this content, it checks if your terminal can display this character
367 checks this by examining the current character set defined by the
369 environment variables.
370 If the value of the locale character set is equal
371 to the value of the charset parameter, then
374 display this content without any additional setup. If the locale is not
377 will assume a value of \*(lqUS-ASCII\*(rq.
378 If the character set cannot be displayed natively, then
380 will look for an entry of the form:
383 mhshow-charset-<charset>
386 which should contain a command creating an environment to render
387 the character set. This command string should containing a single
388 \*(lq%s\*(rq, which will be filled-in with the command to display the
391 Example entries might be:
394 mhshow-charset-iso-8859-1: xterm -fn '-*-*-medium-r-normal-*-*-120-*-*-c-*-iso8859-*' -e %s
400 mhshow-charset-iso-8859-1: '%s'
403 The first example tells
408 appropriate character set for that message content. The second example
411 that your pager (or other program handling that content
412 type) can handle that character set, and that no special processing is
415 Note that many pagers strip off the high-order bit or have problems
416 displaying text with the high-order bit set. However, the pager
418 has support for single-octet character sets. For example, messages
419 encoded in the ISO-8859-1 character set can be view using
421 with these environment variable settings:
431 The first setting tells
433 to use the ISO-8859-1 definition for
434 determining whether a character is \*(lqnormal\*(rq, \*(lqcontrol\*(lq,
435 or \*(lqbinary\*(rq. The second setting tells
438 if it encounters a file that has non-ASCII characters. Then, simply
444 called automatically. (To handle other single-octet character sets,
447 manual entry for information about the
449 environment variable.)
450 .SS "Messages of Type message/partial"
452 cannot directly display messages of type partial.
453 You must reassemble them first into a normal message using
455 Check the man page for
458 .SS "External Access"
459 For contents of type message/external-body,
461 supports these access-types:
476 For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types,
478 will look for the \*(lqnmh-access-ftp\*(rq
482 nmh-access-ftp: myftp.sh
485 to determine the pathname of a program to perform the FTP retrieval.
487 This program is invoked with these arguments:
491 domain name of FTP-site
497 \*(lqascii\*(rq or \*(lqbinary\*(rq
501 The program should terminate with an exit status of zero if the
502 retrieval is successful, and a non-zero exit status otherwise.
504 For the \*(lqurl\*(rq access\-type,
506 will look for the \*(lqnmh-access-url\*(rq
511 .SS "The Content Cache"
514 encounters an external content containing a
515 \*(lqContent-ID:\*(rq field, and if the content allows caching, then
516 depending on the caching behavior of
518 the content might be read from or written to a cache.
520 The caching behavior of
522 is controlled with the
526 switches, which define the policy for reading from,
527 and writing to, the cache, respectively. One of four policies may be
528 specified: \*(lqpublic\*(rq, indicating that
531 of a publically-accessible content cache; \*(lqprivate\*(rq, indicating
534 should make use of the user's private content cache;
535 \*(lqnever\*(rq, indicating that
537 should never make use of
538 caching; and, \*(lqask\*(rq, indicating that
542 There are two directories where contents may be cached: the profile entry
543 \*(lqnmh-cache\*(rq names a directory containing world-readable contents, and,
544 the profile entry \*(lqnmh-private-cache\*(rq names a directory containing
545 private contents. The former should be an absolute (rooted) directory
554 might be used if you didn't care that the cache got wiped after each
555 reboot of the system. The latter is interpreted relative to the user's
556 nmh directory, if not rooted, e.g.,
559 nmh-private-cache: .cache
562 (which is the default value).
563 .SS "User Environment"
564 Because the display environment in which
566 operates may vary for
569 will look for the environment variable
571 If present, this specifies the name of an additional
572 user profile which should be read. Hence, when a user logs in on a
573 particular display device, this environment variable should be set to
574 refer to a file containing definitions useful for the given display device.
575 Normally, only entries that deal with the methods to display different
576 content type and subtypes
580 mhshow-show-<type>/<subtype>
585 need be present in this additional profile. Finally,
587 will attempt to consult
590 %etcdir%/mhn.defaults
593 which is created automatically during
597 See "Profile Lookup" in
599 for the profile search order, and for how duplicate entries are treated.
600 .SS Content\-Type Marker
602 will display a marker containing information about the part being displayed
603 next. The default marker can be changed using the
605 switch to specify a file containing
607 instructions to use when displaying the content marker. In addition to
610 instructions, the following
612 escapes are supported:
616 .ta \w'cdispo-<PARAM> 'u +\w'Returns 'u
617 .I "Escape Returns Description"
618 part string MIME part number
619 content\-type string MIME Content\-Type of part
620 description string Content\-Description header
621 disposition string Content disposition (attachment or inline)
622 ctype-<PARAM> string Value of <PARAM> from Content\-Type header
623 cdispo-<PARAM> string Value of <PARAM> from
624 Content\-Disposition header
625 %(size) integer The size of the decoded part, in bytes
626 %(unseen) boolean Returns true for suppressed parts
628 In this context, the %(unseen) function indicates whether
630 has decided to not display a particular part due to the
636 All MIME parameters and the \*(lqContent-Description\*(rq header will have
637 RFC 2231 decoding applied and be converted
638 to the local character set.
642 looks for all format files and mhn.defaults in multiple locations:
643 absolute pathnames are accessed directly, tilde expansion is done on
644 usernames, and files are searched for in the user's
646 directory as specified in their profile. If not found there, the directory
647 .RI \*(lq %etcdir% \*(rq
652 .ta \w'%etcdir%/ExtraBigFileName 'u
653 ^$HOME/\&.mh\(ruprofile~^The user profile
654 ^$MHSHOW~^Additional profile entries
655 ^%etcdir%/mhn.defaults~^System default MIME profile entries
656 ^%etcdir%/mhl.headers~^The headers template
657 ^%etcdir%/mhshow.marker~^Example content marker
659 .SH "PROFILE COMPONENTS"
663 .ta \w'ExtraBigProfileName 'u
664 ^Path:~^To determine the user's nmh directory
665 ^Current\-Folder:~^To find the default current folder
666 ^Unseen\-Sequence:~^To name sequences denoting unseen messages
667 ^mhlproc:~^Default program to display message headers
668 ^nmh-access-ftp:~^Program to retrieve contents via FTP
669 ^nmh-access-url:~^Program to retrieve contents via HTTP
670 ^nmh-cache~^Public directory to store cached external contents
671 ^nmh-private-cache~^Personal directory to store cached external contents
672 ^mhshow-charset-<charset>~^Template for environment to render character sets
673 ^mhshow-show-<type>*~^Template for displaying contents
674 ^moreproc:~^Default program to display text/plain content
686 .RB ` +folder "' defaults to the current folder"
687 .RB ` msgs "' defaults to cur"
692 .RB ` \-form\ mhl.headers '
693 .RB ` \-rcache\ ask '
694 .RB ` \-wcache\ ask '
697 If a folder is given, it will become the current folder. The last
698 message selected will become the current message.
projects / nmh / blob