5 .\" include the -mh macro file
8 .TH MHSHOW %manext1% MH.6.8 [%nmhversion%]
10 mhshow \- display MIME messages
14 mhshow \%[+folder] \%[msgs] \%[\-file file]
16 \%[\-part number]... \%[\-type content]...
18 \%[\-serialonly] \%[\-noserialonly]
19 \%[\-pause] \%[\-nopause]
21 \%[\-check] \%[\-nocheck]
24 \%[\-rcache policy] \%[\-wcache policy]
26 \%[\-verbose] \%[\-noverbose]
27 \%[\-version] \%[\-help]
31 The \fImhshow\fR command display contents of a MIME (multi-media)
32 message or collection of messages.
34 \fImhshow\fR manipulates multi-media messages as specified in
35 RFC\-2045 thru RFC\-2049. Currently \fImhshow\fR only supports
36 encodings in message bodies, and does not support the encoding of
37 message headers as specified in RFC\-2047.
39 By default \fImhshow\fR will display all parts of a multipart
40 message. By using the `\-part' and `\-type' switches, you may
41 limit the scope of \fImhshow\fR to particular subparts (of a
42 multipart content) and/or particular content types.
44 The option `\-file\ file' directs \fImhshow\fR to use the specified file as
45 the source message, rather than a message from a folder. If you specify
46 this file as \*(lq-\*(rq, then \fImhshow\fR will accept the source message
47 on the standard input. Note that the file, or input from standard input
48 should be a validly formatted message, just like any other \fInmh\fR
49 message. It should \fBNOT\fR be in mail drop format (to convert a file in
50 mail drop format to a folder of \fInmh\fR messages, see \fIinc\fR\0(1)).
52 A part specification consists of a series of numbers separated by dots.
53 For example, in a multipart content containing three parts, these
54 would be named as 1, 2, and 3, respectively. If part 2 was also a
55 multipart content containing two parts, these would be named as 2.1 and
56 2.2, respectively. Note that the `\-part' switch is effective for only
57 messages containing a multipart content. If a message has some other
58 kind of content, or if the part is itself another multipart content, the
59 `\-part' switch will not prevent the content from being acted upon.
61 A content specification consists of a content type and a subtype.
62 The initial list of \*(lqstandard\*(rq content types and subtypes can
63 be found in RFC\-2046.
65 A list of commonly used contents is briefly reproduced here:
73 multipart mixed, alternative, digest, parallel
74 message rfc822, partial, external-body
75 application octet-stream, postscript
83 A legal MIME message must contain a subtype specification.
85 To specify a content, regardless of its subtype, just use the
86 name of the content, e.g., \*(lqaudio\*(rq. To specify a specific
87 subtype, separate the two with a slash, e.g., \*(lqaudio/basic\*(rq.
88 Note that regardless of the values given to the `\-type' switch, a
89 multipart content (of any subtype listed above) is always acted upon.
90 Further note that if the `\-type' switch is used, and it is desirable to
91 act on a message/external-body content, then the `\-type' switch must
92 be used twice: once for message/external-body and once for the content
93 externally referenced.
97 If the profile entry \*(lqUnseen\-Sequence\*(rq is present and
98 non\-empty, then \fImhshow\fR will remove each of the messages shown
99 from each sequence named by the profile entry.
101 .Uh "Checking the Contents"
102 The `\-check' switch tells \fImhshow\fR to check each content for an
103 integrity checksum. If a content has such a checksum (specified as a
104 Content-MD5 header field), then \fImhshow\fR will attempt to verify the
105 integrity of the content.
107 .Uh "Showing the Contents"
108 The headers of each message are displayed with the \fImhlproc\fR
109 (usually \fImhl\fR), using the standard format file \fImhl.headers\fR.
110 You may specify an alternate format file with the `\-form formfile'
111 switch. If the format file \fImhl.null\fR is specified, then the display
112 of the message headers is suppressed.
114 The method used to display the different contents in the messages bodies
115 will be determined by a \*(lqdisplay string\*(rq. To find the display
116 string, \fImhshow\fR will first search your profile for an entry of the
120 mhshow-show-<type>/<subtype>
123 to determine the display string. If this isn't found, \fImhshow\fR
124 will search for an entry of the form:
130 to determine the display string.
132 If a display string is found, any escapes (given below) will be expanded.
133 The result will be executed under \fB/bin/sh\fR, with the standard input
136 The display string may contain the following escapes:
141 %a Insert parameters from Content-Type field
142 %e exclusive execution
143 %f Insert filename containing content
144 %F %e, %f, and stdin is terminal not content
145 %l display listing prior to displaying content
146 %p %l, and ask for confirmation
147 %s Insert content subtype
148 %d Insert content description
149 %% Insert the character %
155 For those display strings containing the e- or F-escape, \fImhshow\fR will
156 execute at most one of these at any given time. Although the F-escape
157 expands to be the filename containing the content, the e-escape has no
158 expansion as far as the shell is concerned.
160 When the p-escape prompts for confirmation, typing INTR (usually
161 control-C) will tell \fImhshow\fR not to display that content.
162 The p-escape can be disabled by specifying the switch `\-nopause'.
163 Further, when \fImhshow\fR is display a content, typing QUIT (usually
164 control-\\) will tell \fImhshow\fR to wrap things up immediately.
166 Note that if the content being displayed is multipart, but not one of
167 the subtypes listed above, then the f- and F-escapes expand to multiple
168 filenames, one for each subordinate content. Further, stdin is not
169 redirected from the terminal to the content.
171 If a display string is not found, \fImhshow\fR has several default values:
175 mhshow-show-text/plain: %pmoreproc '%F'
176 mhshow-show-message/rfc822: %pshow -file '%F'
180 If a subtype of type text doesn't have a profile entry, it will be
181 treated as text/plain.
183 \fImhshow\fR has default methods for handling multipart messages of subtype
184 mixed, alternative, parallel, and digest. Any unknown subtype of type
185 multipart (without a profile entry), will be treated as multipart/mixed.
187 If none of these apply, then \fImhshow\fR will check to see if the message
188 has an application/octet-stream content with parameter \*(lqtype=tar\*(rq.
189 If so, \fImhshow\fR will use an appropriate command. If not, \fImhshow\fR
193 Example entries might be:
197 mhshow-show-audio/basic: raw2audio 2>/dev/null | play
198 mhshow-show-image: xv '%f'
199 mhshow-show-application/PostScript: lpr -Pps
203 Note that when using the f- or F-escape, it's a good idea to use
204 single-quotes around the escape. This prevents misinterpretation by
205 the shell of any funny characters that might be present in the filename.
207 Finally, \fImhshow\fR will process each message serially\0--\0it won't start
208 showing the next message until all the commands executed to display the
209 current message have terminated. In the case of a multipart content
210 (of any subtype listed above), the content contains advice indicating if
211 the parts should be displayed serially or in parallel. Because this may
212 cause confusion, particularly on uni-window displays, the `\-serialonly'
213 switch can be given to tell \fImhshow\fR to never display parts in parallel.
215 .Uh "Showing Alternate Character Sets"
216 Because a content of type text might be in a non-ASCII character
217 set, when \fImhshow\fR encounters a \*(lqcharset\*(rq parameter for
218 this content, it checks if your terminal can display this character
219 set natively. \fIMhn\fR checks this by examining the the environment
220 variable MM_CHARSET. If the value of this environment variable is equal
221 to the value of the charset parameter, then \fImhshow\fR assumes it can
222 display this content without any additional setup. If this environment
223 variable is not set, \fImhshow\fR will assume a value of \*(lqUS-ASCII\*(rq.
224 If the character set cannot be displayed natively, then \fImhshow\fR will
225 look for an entry of the form:
228 mhshow-charset-<charset>
231 which should contain a command creating an environment to render
232 the character set. This command string should containing a single
233 \*(lq%s\*(rq, which will be filled-in with the command to display the
236 Example entries might be:
239 mhshow-charset-iso-8859-1: xterm -fn '-*-*-medium-r-normal-*-*-120-*-*-c-*-iso8859-*' -e %s
243 mhshow-charset-iso-8859-1: '%s'
246 The first example tells \fImhshow\fR to start \fIxterm\fR and load the
247 appropriate character set for that message content. The second example
248 tells \fImhshow\fR that your pager (or other program handling that content
249 type) can handle that character set, and that no special processing is
252 Note that many pagers strip off the high-order bit or have problems
253 displaying text with the high-order bit set. However, the pager
254 \fIless\fR has support for single-octet character sets. The source
255 to \fIless\fR is available on many ftp sites carrying free software.
256 In order to view messages sent in the ISO-8859-1 character set using
259 put these lines in your \&.login file:
263 setenv LESSCHARSET latin1
268 The first line tells \fIless\fR to use the ISO-8859-1 definition for
269 determining whether a character is \*(lqnormal\*(rq, \*(lqcontrol\*(lq,
270 or \*(lqbinary\*(rq. The second line tells \fIless\fR not to warn you
271 if it encounters a file that has non-ASCII characters. Then, simply
272 set the \fBmoreproc\fR profile entry to \fIless\fR, and it will get
273 called automatically. (To handle other single-octet character sets,
274 look at the \fIless\fR\0(1) manual entry for information about the
275 \fBLESSCHARDEF\fR environment variable.)
277 .Uh "Messages of Type message/partial"
278 \fImhshow\fR cannot directly display messages of type partial.
279 You must reassemble them first into a normal message using
280 \fImhstore\fR. Check the man page for \fImhstore\fR for details.
282 .Uh "External Access"
283 For contents of type message/external-body,
285 \fImhshow\fR supports these access-types:
297 For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types,
298 \fImhshow\fR will look for the \fBnmh-access-ftp\fR
304 nmh-access-ftp: myftp.sh
307 to determine the pathname of a program to perform the FTP retrieval.
309 This program is invoked with these arguments:
313 domain name of FTP-site
319 \*(lqascii\*(rq or \*(lqbinary\*(rq
323 The program should terminate with an exit status of zero if the
324 retrieval is successful, and a non-zero exit status otherwise.
326 If this entry is not provided, then \fImhshow\fR will use a simple
327 built-in FTP client to perform the retrieval.
329 .Uh "The Content Cache"
330 When \fImhshow\fR encounters an external content containing a
331 \*(lqContent-ID:\*(rq field, and if the content allows caching, then
332 depending on the caching behavior of \fImhshow\fR, the content might be
333 read from or written to a cache.
335 The caching behavior of \fImhshow\fR is controlled with the `\-rcache'
336 and `\-wcache' switches, which define the policy for reading from,
337 and writing to, the cache, respectively. One of four policies may be
338 specified: \*(lqpublic\*(rq, indicating that \fImhshow\fR should make use
339 of a publically-accessible content cache; \*(lqprivate\*(rq, indicating
340 that \fImhshow\fR should make use of the user's private content cache;
341 \*(lqnever\*(rq, indicating that \fImhshow\fR should never make use of
342 caching; and, \*(lqask\*(rq, indicating that \fImhshow\fR should ask
345 There are two directories where contents may be cached: the profile entry
346 \fBnmh-cache\fR names a directory containing world-readable contents, and,
347 the profile entry \fBnmh-private-cache\fR names a directory containing
348 private contents. The former should be an absolute (rooted) directory
357 might be used if you didn't care that the cache got wiped after each
358 reboot of the system. The latter is interpreted relative to the user's
359 nmh directory, if not rooted,
364 nmh-private-cache: .cache
367 (which is the default value).
369 .Uh "User Environment"
370 Because the display environment in which \fImhshow\fR operates may vary for
371 different machines, \fImhshow\fR will look for the environment variable
372 \fB$MHSHOW\fR. If present, this specifies the name of an additional
373 user profile which should be read. Hence, when a user logs in on a
374 particular display device, this environment variable should be set to
375 refer to a file containing definitions useful for the given display device.
376 Normally, only entries that deal with the methods to display different
377 content type and subtypes
380 mhshow-show-<type>/<subtype>
385 need be present in this additional profile.
387 \fImhshow\fR will attempt to consult one other additional user profile,
392 %etcdir%/mhn.defaults
395 which is created automatically during nmh installation.
397 ^$HOME/\&.mh\(ruprofile~^The user profile
398 ^$MHSHOW~^Additional profile entries
399 ^%etcdir%/mhn.defaults~^System default MIME profile entries
400 ^%etcdir%/mhl.headers~^The headers template
402 ^Path:~^To determine the user's nmh directory
404 ^Current\-Folder:~^To find the default current folder
406 ^Unseen\-Sequence:~^To name sequences denoting unseen messages
408 ^mhlproc:~^Default program to display message headers
410 ^nmh-access-ftp:~^Program to retrieve contents via FTP
412 ^nmh-cache~^Public directory to store cached external contents
414 ^nmh-private-cache~^Personal directory to store cached external contents
416 ^mhshow-charset-<charset>~^Template for environment to render character sets
418 ^mhshow-show-<type>*~^Template for displaying contents
420 ^moreproc:~^Default program to display text/plain content
422 mhbuild(1), mhl(1), mhlist(1), mhstore(1), sendfiles(1)
426 \fIProposed Standard for Message Encapsulation\fR,
430 \fIMultipurpose Internet Mail Extensions (MIME) Part One:
432 Format of Internet Message Bodies\fR,
436 \fIMultipurpose Internet Mail Extensions (MIME) Part Two:
442 \fIMultipurpose Internet Mail Extensions (MIME) Part Three:
444 Message Header Extensions for Non-ASCII Text\fR,
448 \fIMultipurpose Internet Mail Extensions (MIME) Part Four:
450 Registration Procedures\fR,
454 \fIMultipurpose Internet Mail Extensions (MIME) Part Five:
456 Conformance Criteria and Examples\fR.
458 `+folder' defaults to the current folder
460 `msgs' defaults to cur
478 If a folder is given, it will become the current folder. The last
479 message selected will become the current message.