1MHSHOW(1) General Commands Manual MHSHOW(1)
2
6 mhshow - display nmh MIME messages
7
9 mhshow [-help] [-version] [+folder] [msgs] [-file file] [-part number]
10 ... [-type content] ... [-prefer content] ... [-noprefer]
11 [-concat | -noconcat] [-textonly | -notextonly] [-inlineonly |
12 -noinlineonly] [-header | -noheader] [-form formfile] [-markform
13 formfile] [-rcache policy] [-wcache policy] [-check | -nocheck]
14
16 The mhshow command displays contents of a MIME (multi-media) message,
17 or collection of messages.
18 mhshow manipulates multi-media messages as specified in RFC 2045 to RFC
20 2049. Currently mhshow only supports encodings in message bodies, and
21 does not support the encoding of message headers as specified in RFC
22 2047.
23 By default, mhshow will display only the text parts of a message that
25 are not marked as attachments. This behavior can be changed by the
26 -notextonly and -noinlineonly switches. In addition, by using the
27 -part, -type, and -prefer switches, you may limit and reorder the set
28 of parts to be displayed, based on part number and/or content type.
29 The inclusion of any -part or -type switches will override the default
30 settings of -textonly and -inlineonly.
31 The -header switch controls whether mhshow will print a message separa‐
33 tor header before each message that it displays. The header format can
34 be controlled using -headerform, to specify a file containing mh-for‐
35 mat(5) instructions. A copy of the built-in default headerform can be
36 found in /etc/nmh/mhshow.header, for reference. In addition to the
37 normal set of mh-format(5) instructions, a "%{folder}" escape provides
38 a string representing the current folder.
39 By default, mhshow will concatenate all content under one pager. If
41 you want each part to be displayed separately, you can override the
42 default behavior with -noconcat.
43 The -file file switch directs mhshow to use the specified file as the
45 source message, rather than a message from a folder. If you specify
46 this file as “-”, then mhshow will accept the source message on the
47 standard input. Note that the file, or input from standard input,
48 should be a validly formatted message, just like any other nmh message.
49 It should not be in mail drop format (to convert a file in mail drop
50 format to a folder of nmh messages, see inc(1)).
51 The -part switch can be given (one or more times) to restrict the set
53 of subparts that will be displayed. (Obviously with no -part switches,
54 all parts will be considered.) If a -part switch specifies a specific
55 subpart (i.e., a "leaf" in the tree of MIME parts), then that part will
56 always be displayed. If a -part switch references a multipart/alterna‐
57 tive part, then (in the absence of a -type switch) only the default
58 subpart of that multipart will be displayed.
59 A part specification consists of a series of numbers separated by dots.
61 For example, in a multipart content containing three parts, these would
62 be named as 1, 2, and 3, respectively. If part 2 was also a multipart
63 content containing two parts, these would be named as 2.1 and 2.2,
64 respectively. Note that the -part switch is effective only for mes‐
65 sages containing a multipart content. If a message has some other kind
66 of content, or if the part is itself another multipart content, the
67 -part switch will not prevent the content from being acted upon.
68 The -type switch can also be used to restrict (or, when used in con‐
70 junction with -part, to further restrict) the display of parts accord‐
71 ing to content type. One or more -type switches part will only select
72 the first match from a multipart/alternative, even if there is more
73 than one subpart that matches (one of) the given content type(s).
74 Using either -part or -type switches alone will cause either switch to
76 select the part(s) they match. Using them together will select only
77 the part(s) matched by both (sets of) switches. In other words, the
78 result is the intersection, and not the union, of their separate match
79 results.
80 A content specification consists of a content type and a subtype. The
82 initial list of “standard” content types and subtypes can be found in
83 RFC 2046.
84 A list of commonly used contents is briefly reproduced here:
86 Type Subtypes
88 ---- --------
89 text plain, enriched
90 multipart mixed, alternative, digest, parallel
91 message rfc822, partial, external-body
92 application octet-stream, postscript
93 image jpeg, gif, png
94 audio basic
95 video mpeg
96 A legal MIME message must contain a subtype specification.
98 To specify a content, regardless of its subtype, just use the name of
100 the content, e.g., “audio”. To specify a specific subtype, separate
101 the two with a slash, e.g., “audio/basic”. Note that regardless of the
102 values given to the -type switch, a multipart content (of any subtype
103 listed above) is always acted upon. Further note that if the -type
104 switch is used, and it is desirable to act on a message/external-body
105 content, then the -type switch must be used twice: once for mes‐
106 sage/external-body and once for the content externally referenced.
107 In the absence of -prefer, mhshow will select the "best" displayable
109 subpart from multipart/alternative content. The -prefer switch can be
110 used (one or more times, in order of ascending preference) to let MH
111 know which content types from a multipart/alternative MIME part are
112 preferred by the user, in order to override the default selection for
113 display. For example, mail is often sent containing both plaintext and
114 HTML-formatted versions of the same content, and the HTML version is
115 usually indicated to be the "best" format for viewing. Using “-prefer
116 text/plain” will cause the plaintext version to be displayed if possi‐
117 ble, but still allow display of the HTML part if there is no plaintext
118 subpart available. Using “-prefer text/plain -prefer image/png” would
119 add a preference for PNG images, which might or might not ever appear
120 in the same multipart/alternative section with text/plain. Implementa‐
121 tion note: RFC 2046 requires that the subparts of a multipart/alterna‐
122 tive be ordered according to "faithfulness to the original content",
123 and MH by default selects the subpart ranked most "faithful" by that
124 ordering. The -prefer switch reorders the alternative parts (only
125 internally, never changing the message file) to move the user's pre‐
126 ferred part(s) to the "most faithful" position. Thus, when viewed by
127 mhlist, the ordering of multipart/alternative parts will appear to
128 change when invoked with or without various -prefer switches. Since
129 the last of multiple -prefer options "wins", a -prefer on the command
130 line will override any in a profile entry.
131 The -noprefer switch will cancel any previous -prefer switches.
133 Unseen Sequence
135 If the profile entry “Unseen-Sequence” is present and non-empty, then
136 mhshow will remove each of the messages shown from each sequence named
137 by the profile entry.
138 Checking the Contents
140 The -check switch tells mhshow to check each content for an integrity
141 checksum. If a content has such a checksum (specified as a Content-MD5
142 header field), then mhshow will attempt to verify the integrity of the
143 content.
144 Showing the Contents
146 The headers of each message are displayed with the mhlproc (usually
147 mhl), using the standard format file, mhl.headers. You may specify an
148 alternative format file with the -form formfile switch. If the format
149 file mhl.null is specified, then the display of the message headers is
150 suppressed.
151 Next, the contents are extracted from the message and are stored in a
153 temporary file. Usually, the name of the temporary file is the word
154 “mhshow” followed by a string of characters. Occasionally, the method
155 used to display a content (described next), requires that the file end
156 in a specific suffix. For example, the soffice command (part of the
157 StarOffice package) can be used to display Microsoft Word content, but
158 it uses the suffix to determine how to display the file. If no suffix
159 is present, the file is not correctly loaded. Similarly, older ver‐
160 sions of the gs command append a “.ps” suffix to the filename if one
161 was missing. As a result, these cannot be used to read the default
162 temporary file.
163 To get around this, your profile can contain lines of the form:
165 mhshow-suffix-<type>/<subtype>: <suffix>
167 or
169 mhshow-suffix-<type>: <suffix>
171 to specify a suffix which can be automatically added to the temporary
173 file created for a specific content type. For example, the following
174 lines might appear in your profile:
175 mhshow-suffix-text: .txt
177 mhshow-suffix-application/msword: .doc
178 mhshow-suffix-application/PostScript: .ps
179 to automatically append a suffix to the temporary files.
181 The method used to display the different contents in the messages bod‐
183 ies will be determined by a “display string”. To find the display
184 string, mhshow will first search your profile for an entry of the form:
185 mhshow-show-<type>/<subtype>
187 If this isn't found, mhshow will search for an entry of the form:
189 mhshow-show-<type>
191 to determine the display string.
193 If a display string is found, any escapes (given below) will be
195 expanded. The result will be executed under “/bin/sh”, with the stan‐
196 dard input set to the content.
197 The display string may contain the following escapes:
199 %a Insert parameters from Content-Type field
201 %{parameter} Insert the parameter value from the Content-Type field
202 %f Insert filename containing content
203 %F %f, and stdin is terminal not content
204 %l display listing prior to displaying content
205 %s Insert content subtype
206 %d Insert content description
207 %% Insert the character %
208 mhshow will execute at most one display string at any given time, and
210 wait for the current display string to finish execution before execut‐
211 ing the next display string.
212 The {parameter} escape is typically used in a command line argument
214 that should only be present if it has a non-null value. It is highly
215 recommended that the entire escape be wrapped in double quotes. Shell
216 parameter expansion can construct the argument only when it is non-
217 null, e.g.,
218 mhshow-show-text/html: charset="%{charset}";
220 w3m ${charset:+-I $charset} -T text/html %F
221 That example also shows the use of indentation to signify continuation:
223 the two text lines combine to form a single entry. Note that when
224 dealing with text that has been converted internally by iconv(3), the
225 “charset” parameter will reflect the target character set of the text,
226 rather than the original character set in the message.
227 Note that if the content being displayed is multipart, but not one of
229 the subtypes listed above, then the f- and F-escapes expand to multiple
230 filenames, one for each subordinate content. Furthermore, stdin is not
231 redirected from the terminal to the content.
232 If a display string is not found, mhshow behaves as if these profile
234 entries were supplied and supported:
235 mhshow-show-text/plain: %lmoreproc %F
237 mhshow-show-message/rfc822: %lshow -file %F
238 Note that “moreproc” is not supported in user profile display strings.
240 If a subtype of type text doesn't have a profile entry, it will be
242 treated as text/plain.
243 mhshow has default methods for handling multipart messages of subtype
245 mixed, alternative, parallel, and digest. Any unknown subtype of type
246 multipart (without a profile entry), will be treated as multi‐
247 part/mixed.
248 If none of these apply, then mhshow will check to see if the message
250 has an application/octet-stream content with parameter “type=tar”. If
251 so, mhshow will use an appropriate command. If not, mhshow will com‐
252 plain.
253 Example entries might be:
255 mhshow-show-audio/basic: raw2audio 2>/dev/null | play
257 mhshow-show-image: xv %f
258 mhshow-show-application/PostScript: lpr -Pps
259 If an f- or F-escape is not quoted with single quotes, its expansion
261 will be wrapped with single quotes.
262 Finally, mhshow will process each message serially -- it won't start
264 showing the next message until all the commands executed to display the
265 current message have terminated.
266 Showing Alternate Character Sets
268 If mhshow was built with iconv(3), then all text/plain parts of the
269 message(s) will be displayed using the character set of the current
270 locale. See the mhparam(1) man page for how to determine whether your
271 nmh installation includes iconv(3) support. To convert text parts
272 other than text/plain, or if mhshow was not built with iconv, an exter‐
273 nal program can be used, as described next.
274 Because a content of type text might be in a non-ASCII character set,
276 when mhshow encounters a “charset” parameter for this content, it
277 checks if your terminal can display this character set natively.
278 mhshow checks this by examining the current character set defined by
279 the locale(1) environment variables. If the value of the locale char‐
280 acter set is equal to the value of the charset parameter, then mhshow
281 assumes it can display this content without any additional setup. If
282 the locale is not set properly, mhshow will assume a value of “US-
283 ASCII”. If the character set cannot be displayed natively, then mhshow
284 will look for an entry of the form:
285 mhshow-charset-<charset>
287 which should contain a command creating an environment to render the
289 character set. This command string should containing a single “%s”,
290 which will be filled-in with the command to display the content.
291 Example entries might be:
293 mhshow-charset-iso-8859-1: xterm -fn '-*-*-medium-r-nor‐
295 mal-*-*-120-*-*-c-*-iso8859-*' -e %s
296 or
298 mhshow-charset-iso-8859-1: '%s'
300 The first example tells mhshow to start xterm and load the appropriate
302 character set for that message content. The second example tells
303 mhshow that your pager (or other program handling that content type)
304 can handle that character set, and that no special processing is needed
305 beforehand.
306 Note that many pagers strip off the high-order bit, or have problems
308 displaying text with the high-order bit set. However, the pager less
309 has support for single-octet character sets. For example, messages
310 encoded in the ISO-8859-1 character set can be viewed using less, with
311 these environment variable settings:
312 LESSCHARSET latin1
314 LESS -f
315 The first setting tells less to use the ISO-8859-1 definition to deter‐
317 mine whether a character is “normal”, “control“, or “binary”. The sec‐
318 ond setting tells less not to warn you if it encounters a file that has
319 non-ASCII characters. Then, simply set the moreproc profile entry to
320 less, and it will get called automatically. (To handle other single-
321 octet character sets, look at the less(1) manual entry for information
322 about the LESSCHARDEF environment variable.)
323 Messages of Type message/partial
325 mhshow cannot directly display messages of type partial. You must
326 first reassemble them into a normal message using mhstore. Check
327 mhstore(1) for details.
328 External Access
330 For contents of type message/external-body, mhshow supports these
331 access-types:
332 · afs
334 · anon-ftp
336 · ftp
338 · local-file
340 · mail-server
342 · url
344 For the “anon-ftp” and “ftp” access types, mhshow will look for the
346 “nmh-access-ftp” profile entry, e.g.,
347 nmh-access-ftp: myftp.sh
349 to determine the pathname of a program to perform the FTP retrieval.
351 This program is invoked with these arguments:
353 domain name of FTP-site
355 username
356 password
357 remote directory
358 remote filename
359 local filename
360 “ascii” or “binary”
361 The program should terminate with an exit status of zero if the
363 retrieval is successful, and a non-zero exit status otherwise.
364 For the “url” access-type, mhshow will look for the “nmh-access-url”
366 profile entry. See mhstore(1) for more details.
367 The Content Cache
369 When mhshow encounters an external content containing a “Content-ID:”
370 field, and if the content allows caching, then depending on the caching
371 behavior of mhshow, the content might be read from or written to a
372 cache.
373 The caching behavior of mhshow is controlled with the -rcache and
375 -wcache switches, which define the policy for reading from, and writing
376 to, the cache, respectively. One of four policies may be specified:
377 “public”, indicating that mhshow should make use of a publicly-accessi‐
378 ble content cache; “private”, indicating that mhshow should make use of
379 the user's private content cache; “never”, indicating that mhshow
380 should never make use of caching; and, “ask”, indicating that mhshow
381 should ask the user.
382 There are two directories where contents may be cached: the profile
384 entry “nmh-cache” names a directory containing world-readable contents,
385 and, the profile entry “nmh-private-cache” names a directory containing
386 private contents. The former should be an absolute (rooted) directory
387 name.
388 For example,
390 nmh-cache: /tmp
392 might be used if you didn't care that the cache got wiped after each
394 reboot of the system. The latter is interpreted relative to the user's
395 nmh directory, if not rooted, e.g.,
396 nmh-private-cache: .cache
398 (which is the default value).
400 User Environment
402 Because the display environment in which mhshow operates may vary for
403 different machines, mhshow will look for the environment variable
404 MHSHOW. If present, this specifies the name of an additional user pro‐
405 file which should be read. Hence, when a user logs in on a particular
406 display device, this environment variable should be set to refer to a
407 file containing definitions useful for the given display device. Nor‐
408 mally, only entries that deal with the methods to display different
409 content type and subtypes
410 mhshow-show-<type>/<subtype>
412 mhshow-show-<type>
413 need be present in this additional profile. Finally, mhshow will
415 attempt to consult
416 /etc/nmh/mhn.defaults
418 which is created automatically during nmh installation.
420 See "Profile Lookup" in mh-profile(5) for the profile search order, and
422 for how duplicate entries are treated.
423 Content-Type Marker
425 mhshow will display a marker containing information about the part
426 being displayed next. The default marker can be changed using the
427 -markform switch to specify a file containing mh-format(5) instructions
428 to use when displaying the content marker. A copy of the default mark‐
429 form can be found in /etc/nmh/mhshow.marker, for reference. In addi‐
430 tion to the normal set of mh-format(5) instructions, the following com‐
431 ponent escapes are supported:
432 Escape Returns Description
434 part string MIME part number
435 content-type string MIME Content-Type of part
436 description string Content-Description header
437 disposition string Content disposition (attachment or inline)
438 ctype-<PARAM> string Value of <PARAM> from Content-Type header
439 cdispo-<PARAM> string Value of <PARAM> from
440 Content-Disposition header
441 %(size) integer The size of the decoded part, in bytes
442 %(unseen) boolean Returns true for suppressed parts
443 In this context, the %(unseen) function indicates whether mhshow
444 has decided to not display a particular part due to the -textonly
445 or -inlineonly switches.
446 All MIME parameters and the “Content-Description” header will have RFC
447 2231 decoding applied and be converted to the local character set.
448
450 mhshow looks for all format files and mhn.defaults in multiple loca‐
451 tions: absolute pathnames are accessed directly, tilde expansion is
452 done on usernames, and files are searched for in the user's Mail direc‐
453 tory, as specified in their profile. If not found there, the directory
454 “/etc/nmh” is checked.
455 $HOME/.mh_profile The user profile
457 $MHSHOW Additional profile entries
458 /etc/nmh/mhn.defaults System default MIME profile entries
459 /etc/nmh/mhl.headers The headers template
460 /etc/nmh/mhshow.marker Example content marker
461 /etc/nmh/mhshow.header Example message separator header
462
464 Path: To determine the user's nmh directory
465 Current-Folder: To find the default current folder
466 Unseen-Sequence: To name sequences denoting unseen messages
467 mhlproc: Default program to display message headers
468 nmh-access-ftp: Program to retrieve contents via FTP
469 nmh-access-url: Program to retrieve contents via HTTP
470 nmh-cache Public directory to store cached external contents
471 nmh-private-cache Personal directory to store cached external contents
472 mhshow-charset-<charseTte>mplate for environment to render character sets
473 mhshow-show-<type>* Template for displaying contents
474 moreproc: Default program to display text/plain content
475
477 iconv(3), mhbuild(1), mhl(1), mhlist(1), mhparam(1), mhstore(1), send‐
478 files(1)
479
481 `+folder' defaults to the current folder
482 `msgs' defaults to cur
483 `-nocheck'
484 `-concat'
485 `-textonly'
486 `-inlineonly'
487 `-form mhl.headers'
488 `-rcache ask'
489 `-wcache ask'
490
492 If a folder is given, it will become the current folder. The last mes‐
493 sage selected will become the current message.
494nmh-1.7.1 2015-02-08 MHSHOW(1)