1 .TH MHSHOW %manext1% "March 16, 2014" "%nmhversion%"
6 mhshow \- display MIME messages
21 .RB [ \-serialonly " | " \-noserialonly ]
22 .RB [ \-pause " | " \-nopause ]
29 .RB [ \-check " | " \-nocheck ]
36 command display contents of a MIME (multi-media)
37 message or collection of messages.
40 manipulates multi-media messages as specified in
41 RFC 2045 to RFC 2049. Currently
44 encodings in message bodies, and does not support the encoding of
45 message headers as specified in RFC 2047.
49 will display all parts of a multipart
57 to particular subparts (of a
58 multipart content) and/or particular content types.
65 to use the specified file as
66 the source message, rather than a message from a folder. If you specify
67 this file as \*(lq-\*(rq, then
69 will accept the source message
70 on the standard input. Note that the file, or input from standard input
71 should be a validly formatted message, just like any other
75 be in mail drop format (to convert a file in
76 mail drop format to a folder of
81 A part specification consists of a series of numbers separated by dots.
82 For example, in a multipart content containing three parts, these
83 would be named as 1, 2, and 3, respectively. If part 2 was also a
84 multipart content containing two parts, these would be named as 2.1 and
85 2.2, respectively. Note that the
87 switch is effective for only
88 messages containing a multipart content. If a message has some other
89 kind of content, or if the part is itself another multipart content, the
91 switch will not prevent the content from being acted upon.
93 A content specification consists of a content type and a subtype.
94 The initial list of \*(lqstandard\*(rq content types and subtypes can
97 A list of commonly used contents is briefly reproduced here:
101 .ta \w'application 'u
105 multipart mixed, alternative, digest, parallel
106 message rfc822, partial, external-body
107 application octet-stream, postscript
114 A legal MIME message must contain a subtype specification.
116 To specify a content, regardless of its subtype, just use the
117 name of the content, e.g., \*(lqaudio\*(rq. To specify a specific
118 subtype, separate the two with a slash, e.g., \*(lqaudio/basic\*(rq.
119 Note that regardless of the values given to the `\-type' switch, a
120 multipart content (of any subtype listed above) is always acted upon.
121 Further note that if the `\-type' switch is used, and it is desirable to
122 act on a message/external-body content, then the `\-type' switch must
123 be used twice: once for message/external-body and once for the content
124 externally referenced.
125 .SS "Unseen Sequence"
126 If the profile entry \*(lqUnseen\-Sequence\*(rq is present and
129 will remove each of the messages shown
130 from each sequence named by the profile entry.
131 .SS "Checking the Contents"
136 to check each content for an
137 integrity checksum. If a content has such a checksum (specified as a
138 Content-MD5 header field), then
140 will attempt to verify the
141 integrity of the content.
142 .SS "Showing the Contents"
143 The headers of each message are displayed with the
147 using the standard format file
149 You may specify an alternate format file with the
152 switch. If the format file
154 is specified, then the display
155 of the message headers is suppressed.
157 Next, the contents are extracted from the message and are stored in
158 a temporary file. Usually, the name of the temporary file is the
159 word \*(lqmhshow\*(rq followed by a string of characters. Occasionally,
160 the method used to display a content (described next), requires that
161 the file end in a specific suffix. For example, the
163 command (part of the StarOffice package) can be used to display
164 Microsoft Word content, but it uses the suffix to determine how to display
165 the file. If no suffix is present, the file is not correctly loaded.
166 Similarily, older versions of the
168 command append a \*(lq.ps\*(rq suffix to
169 the filename if one was missing. As a result, these cannot be used to read
170 the default temporary file.
172 To get around this, your profile can contain lines of the form:
175 mhshow-suffix-<type>/<subtype>: <suffix>
181 mhshow-suffix-<type>: <suffix>
184 to specify a suffix which can be automatically added to the temporary
185 file created for a specific content type. For example, the following
186 lines might appear in your profile:
190 mhshow-suffix-text: .txt
191 mhshow-suffix-application/msword: .doc
192 mhshow-suffix-application/PostScript: .ps
196 to automatically append a suffix to the temporary files.
198 The method used to display the different contents in the messages bodies
199 will be determined by a \*(lqdisplay string\*(rq. To find the display
202 will first search your profile for an entry of the form:
205 mhshow-show-<type>/<subtype>
208 to determine the display string. If this isn't found,
210 will search for an entry of the form:
216 to determine the display string.
218 If a display string is found, any escapes (given below) will be expanded.
219 The result will be executed under
220 \*(lq/bin/sh\*(rq, with the standard input
223 The display string may contain the following escapes:
228 %a Insert parameters from Content-Type field
229 %{parameter} Insert the parameter value from the Content-Type field
230 %e exclusive execution
231 %f Insert filename containing content
232 %F %e, %f, and stdin is terminal not content
233 %l display listing prior to displaying content
234 %p %l, and ask for confirmation
235 %s Insert content subtype
236 %d Insert content description
237 %% Insert the character %
241 For those display strings containing the e- or F-escape,
244 execute at most one of these at any given time. Although the F-escape
245 expands to be the filename containing the content, the e-escape has no
246 expansion as far as the shell is concerned.
248 When the p-escape prompts for confirmation, typing INTR (usually
251 not to display that content.
252 The p-escape can be disabled by specifying the switch
256 is display a content, typing QUIT (usually
257 control-\\) will tell
259 to wrap things up immediately.
261 The {parameter} escape is typically used in a command line argument
262 that should only be present if it has a non-null value. Its value
263 will be wrapped with single quotes if the escape is not so wrapped.
264 Shell parameter expansion can construct the argument only when it is
269 mhshow-show-text/html: charset=%{charset};
270 w3m ${charset:+-I $charset} -T text/html %F
274 That example also shows the use of indentation to signify continuation:
275 the two text lines combine to form a single entry. Note that when
276 dealing with text that has been converted internally by
278 the \*(lqcharset\*(rq parameter will reflect the target character set
279 of the text, rather than the original character set in the message.
281 Note that if the content being displayed is multipart, but not one of
282 the subtypes listed above, then the f- and F-escapes expand to multiple
283 filenames, one for each subordinate content. Further, stdin is not
284 redirected from the terminal to the content.
286 If a display string is not found,
288 behaves as if these profile entries were supplied and supported:
292 mhshow-show-text/plain: %pmoreproc %F
293 mhshow-show-message/rfc822: %pshow -file %F
297 Note that \*(lqmoreproc\*(rq is not supported in user profile display
300 If a subtype of type text doesn't have a profile entry, it will be
301 treated as text/plain.
304 has default methods for handling multipart messages of subtype
305 mixed, alternative, parallel, and digest. Any unknown subtype of type
306 multipart (without a profile entry), will be treated as multipart/mixed.
308 If none of these apply, then
310 will check to see if the message
311 has an application/octet-stream content with parameter \*(lqtype=tar\*(rq.
314 will use an appropriate command. If not,
318 Example entries might be:
322 mhshow-show-audio/basic: raw2audio 2>/dev/null | play
323 mhshow-show-image: xv %f
324 mhshow-show-application/PostScript: lpr -Pps
328 If an f- or F-escape is not quoted with single quotes, its expansion
329 will be wrapped with single quotes.
333 will process each message serially\0--\0it won't start
334 showing the next message until all the commands executed to display the
335 current message have terminated. In the case of a multipart content
336 (of any subtype listed above), the content contains advice indicating if
337 the parts should be displayed serially or in parallel. Because this may
338 cause confusion, particularly on uni-window displays, the
340 switch can be given to tell
342 to never display parts in parallel.
343 .SS "Showing Alternate Character Sets"
348 then all text/plain parts of the message(s) will be displayed using
349 the character set of the current locale. See the
351 man page for how determine whether your
353 installation includes
355 support. To convert text parts other
356 than text/plain, or if
360 an external program can be used, as described next.
362 Because a content of type text might be in a non-ASCII character
365 encounters a \*(lqcharset\*(rq parameter for
366 this content, it checks if your terminal can display this character
369 checks this by examining the current character set defined by the
371 environment variables.
372 If the value of the locale character set is equal
373 to the value of the charset parameter, then
376 display this content without any additional setup. If the locale is not
379 will assume a value of \*(lqUS-ASCII\*(rq.
380 If the character set cannot be displayed natively, then
382 will look for an entry of the form:
385 mhshow-charset-<charset>
388 which should contain a command creating an environment to render
389 the character set. This command string should containing a single
390 \*(lq%s\*(rq, which will be filled-in with the command to display the
393 Example entries might be:
396 mhshow-charset-iso-8859-1: xterm -fn '-*-*-medium-r-normal-*-*-120-*-*-c-*-iso8859-*' -e %s
402 mhshow-charset-iso-8859-1: '%s'
405 The first example tells
410 appropriate character set for that message content. The second example
413 that your pager (or other program handling that content
414 type) can handle that character set, and that no special processing is
417 Note that many pagers strip off the high-order bit or have problems
418 displaying text with the high-order bit set. However, the pager
420 has support for single-octet character sets. For example, messages
421 encoded in the ISO-8859-1 character set can be view using
423 with these environment variable settings:
433 The first setting tells
435 to use the ISO-8859-1 definition for
436 determining whether a character is \*(lqnormal\*(rq, \*(lqcontrol\*(lq,
437 or \*(lqbinary\*(rq. The second setting tells
440 if it encounters a file that has non-ASCII characters. Then, simply
446 called automatically. (To handle other single-octet character sets,
449 manual entry for information about the
451 environment variable.)
452 .SS "Messages of Type message/partial"
454 cannot directly display messages of type partial.
455 You must reassemble them first into a normal message using
457 Check the man page for
460 .SS "External Access"
461 For contents of type message/external-body,
463 supports these access-types:
478 For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types,
480 will look for the \*(lqnmh-access-ftp\*(rq
484 nmh-access-ftp: myftp.sh
487 to determine the pathname of a program to perform the FTP retrieval.
489 This program is invoked with these arguments:
493 domain name of FTP-site
499 \*(lqascii\*(rq or \*(lqbinary\*(rq
503 The program should terminate with an exit status of zero if the
504 retrieval is successful, and a non-zero exit status otherwise.
506 For the \*(lqurl\*(rq access\-type,
508 will look for the \*(lqnmh-access-url\*(rq
513 .SS "The Content Cache"
516 encounters an external content containing a
517 \*(lqContent-ID:\*(rq field, and if the content allows caching, then
518 depending on the caching behavior of
520 the content might be read from or written to a cache.
522 The caching behavior of
524 is controlled with the
528 switches, which define the policy for reading from,
529 and writing to, the cache, respectively. One of four policies may be
530 specified: \*(lqpublic\*(rq, indicating that
533 of a publically-accessible content cache; \*(lqprivate\*(rq, indicating
536 should make use of the user's private content cache;
537 \*(lqnever\*(rq, indicating that
539 should never make use of
540 caching; and, \*(lqask\*(rq, indicating that
544 There are two directories where contents may be cached: the profile entry
545 \*(lqnmh-cache\*(rq names a directory containing world-readable contents, and,
546 the profile entry \*(lqnmh-private-cache\*(rq names a directory containing
547 private contents. The former should be an absolute (rooted) directory
556 might be used if you didn't care that the cache got wiped after each
557 reboot of the system. The latter is interpreted relative to the user's
558 nmh directory, if not rooted, e.g.,
561 nmh-private-cache: .cache
564 (which is the default value).
565 .SS "User Environment"
566 Because the display environment in which
568 operates may vary for
571 will look for the environment variable
573 If present, this specifies the name of an additional
574 user profile which should be read. Hence, when a user logs in on a
575 particular display device, this environment variable should be set to
576 refer to a file containing definitions useful for the given display device.
577 Normally, only entries that deal with the methods to display different
578 content type and subtypes
582 mhshow-show-<type>/<subtype>
587 need be present in this additional profile. Finally,
589 will attempt to consult one other additional user profile,
593 %etcdir%/mhn.defaults
596 which is created automatically during
601 looks for all format files and mhn.defaults in multiple locations:
602 absolute pathnames are accessed directly, tilde expansion is done on
603 usernames, and files are searched for in the user's
605 directory as specified in their profile. If not found there, the directory
606 .RI \*(lq %etcdir% \*(rq
611 .ta \w'%etcdir%/ExtraBigFileName 'u
612 ^$HOME/\&.mh\(ruprofile~^The user profile
613 ^$MHSHOW~^Additional profile entries
614 ^%etcdir%/mhn.defaults~^System default MIME profile entries
615 ^%etcdir%/mhl.headers~^The headers template
617 .SH "PROFILE COMPONENTS"
621 .ta \w'ExtraBigProfileName 'u
622 ^Path:~^To determine the user's nmh directory
623 ^Current\-Folder:~^To find the default current folder
624 ^Unseen\-Sequence:~^To name sequences denoting unseen messages
625 ^mhlproc:~^Default program to display message headers
626 ^nmh-access-ftp:~^Program to retrieve contents via FTP
627 ^nmh-access-url:~^Program to retrieve contents via HTTP
628 ^nmh-cache~^Public directory to store cached external contents
629 ^nmh-private-cache~^Personal directory to store cached external contents
630 ^mhshow-charset-<charset>~^Template for environment to render character sets
631 ^mhshow-show-<type>*~^Template for displaying contents
632 ^moreproc:~^Default program to display text/plain content
644 .RB ` +folder "' defaults to the current folder"
645 .RB ` msgs "' defaults to cur"
647 .RB ` \-form\ mhl.headers '
649 .RB ` \-rcache\ ask '
650 .RB ` \-noserialonly '
651 .RB ` \-wcache\ ask '
654 If a folder is given, it will become the current folder. The last
655 message selected will become the current message.
projects / nmh / blob