-.TH MHSHOW %manext1% "April 30, 2012" "%nmhversion%"
+.TH MHSHOW %manext1% "February 18, 2014" "%nmhversion%"
.\"
.\" %nmhwarning%
.\"
.PP
.B mhshow
manipulates multi-media messages as specified in
-RFC\-2045 thru RFC\-2049. Currently
+RFC 2045 to RFC 2049. Currently
.B mhshow
only supports
encodings in message bodies, and does not support the encoding of
-message headers as specified in RFC\-2047.
+message headers as specified in RFC 2047.
.PP
By default
.B mhshow
.PP
A content specification consists of a content type and a subtype.
The initial list of \*(lqstandard\*(rq content types and subtypes can
-be found in RFC\-2046.
+be found in RFC 2046.
.PP
A list of commonly used contents is briefly reproduced here:
.PP
.PP
.RS 5
.nf
-.ta \w'%F 'u
-%a Insert parameters from Content-Type field
-%e exclusive execution
-%f Insert filename containing content
-%F %e, %f, and stdin is terminal not content
-%l display listing prior to displaying content
-%p %l, and ask for confirmation
-%s Insert content subtype
-%d Insert content description
-%% Insert the character %
+.ta \w'%F 'u
+%a Insert parameters from Content-Type field
+%{charset} Insert the charset value from the Content-Type field
+%e exclusive execution
+%f Insert filename containing content
+%F %e, %f, and stdin is terminal not content
+%l display listing prior to displaying content
+%p %l, and ask for confirmation
+%s Insert content subtype
+%d Insert content description
+%% Insert the character %
.fi
.RE
.PP
.B mhshow
to wrap things up immediately.
.PP
+The {charset} escape is typically used in a command line argument that
+should only be present if it has a non-null value. Shell parameter
+expansion can construct the argument only when it is non-null, e.g.,
+.PP
+.RS 5
+.nf
+mhshow-show-text/html: charset="%{charset}";
+ w3m ${charset:+-I $charset} -T text/html %F
+.fi
+.RE
+.PP
+That example also shows the use of indentation to signify continuation:
+the two text lines combine to form a single entry.
+.PP
Note that if the content being displayed is multipart, but not one of
the subtypes listed above, then the f- and F-escapes expand to multiple
filenames, one for each subordinate content. Further, stdin is not
.PP
If a display string is not found,
.B mhshow
-has several default values:
+behaves as if these profile entries were supplied and supported:
.PP
.RS 5
.nf
-mhshow-show-text/plain: %pmoreproc '%F'
-mhshow-show-message/rfc822: %pshow -file '%F'
+mhshow-show-text/plain: %pmoreproc %F
+mhshow-show-message/rfc822: %pshow -file %F
.fi
.RE
.PP
+Note that \*(lqmoreproc\*(rq is not supported in user profile display
+strings.
+.PP
If a subtype of type text doesn't have a profile entry, it will be
treated as text/plain.
.PP
.RS 5
.nf
mhshow-show-audio/basic: raw2audio 2>/dev/null | play
-mhshow-show-image: xv '%f'
+mhshow-show-image: xv %f
mhshow-show-application/PostScript: lpr -Pps
.fi
.RE
.PP
-Note that when using the f- or F-escape, it's a good idea to use
-single-quotes around the escape. This prevents misinterpretation by
-the shell of any funny characters that might be present in the filename.
+If an f- or F-escape is not quoted with single quotes, double quotes,
+or backticks, its expansion will be wrapped with single quotes.
.PP
Finally,
.B mhshow
.B mhshow
to never display parts in parallel.
.SS "Showing Alternate Character Sets"
+If
+.B mhshow
+was built with
+.IR iconv (3),
+then all text/plain parts of the message(s) will be displayed using
+the character set of the current locale. To convert text parts other
+than text/plain, or if
+.B mhshow
+was not built with
+.IR iconv ,
+an external program can be used, as described next.
+.PP
Because a content of type text might be in a non-ASCII character
set, when
.B mhshow
this content, it checks if your terminal can display this character
set natively.
.B mhn
-checks this by examining the the environment
-variable
-.BR $MM_CHARSET .
-If the value of this environment variable is equal
+checks this by examining the current character set defined by the
+.IR locale (1)
+environment variables.
+If the value of the locale character set is equal
to the value of the charset parameter, then
.B mhshow
assumes it can
-display this content without any additional setup. If this environment
-variable is not set,
+display this content without any additional setup. If the locale is not
+set properly,
.B mhshow
will assume a value of \*(lqUS-ASCII\*(rq.
If the character set cannot be displayed natively, then
Note that many pagers strip off the high-order bit or have problems
displaying text with the high-order bit set. However, the pager
.B less
-has support for single-octet character sets. The source
-to
-.B less
-is available on many ftp sites carrying free software.
-In order to view messages sent in the ISO-8859-1 character set using
+has support for single-octet character sets. For example, messages
+encoded in the ISO-8859-1 character set can be view using
.BR less ,
-.PP
-put these lines in your
-.I \&.login
-file:
+with these environment variable settings:
.PP
.RS 5
.nf
-setenv LESSCHARSET latin1
-setenv LESS "-f"
+.ta \w'%F 'u
+LESSCHARSET latin1
+LESS -f
.fi
.RE
.PP
-The first line tells
+The first setting tells
.B less
to use the ISO-8859-1 definition for
determining whether a character is \*(lqnormal\*(rq, \*(lqcontrol\*(lq,
-or \*(lqbinary\*(rq. The second line tells
+or \*(lqbinary\*(rq. The second setting tells
.B less
not to warn you
if it encounters a file that has non-ASCII characters. Then, simply
local-file
.IP \(bu 4
mail-server
+.IP \(bu 4
+url
.PP
For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types,
.B mhshow
.PP
The program should terminate with an exit status of zero if the
retrieval is successful, and a non-zero exit status otherwise.
+.PP
+For the \*(lqurl\*(rq access\-type,
+.B mhshow
+will look for the \*(lqnmh-access-url\*(rq
+profile entry. See
+.IR mhstore (1)
+for more details.
+.PP
.SS "The Content Cache"
When
.B mhshow
.B nmh
installation.
.SH FILES
+.B mhshow
+looks for all format files and mhn.defaults in multiple locations:
+absolute pathnames are accessed directly, tilde expansion is done on
+usernames, and files are searched for in the user's
+.I Mail
+directory as specified in their profile. If not found there, the directory
+.RI \*(lq %etcdir% \*(rq
+is checked.
+.PP
.fc ^ ~
.nf
.ta \w'%etcdir%/ExtraBigFileName 'u
^Unseen\-Sequence:~^To name sequences denoting unseen messages
^mhlproc:~^Default program to display message headers
^nmh-access-ftp:~^Program to retrieve contents via FTP
+^nmh-access-url:~^Program to retrieve contents via HTTP
^nmh-cache~^Public directory to store cached external contents
^nmh-private-cache~^Personal directory to store cached external contents
^mhshow-charset-<charset>~^Template for environment to render character sets
^moreproc:~^Default program to display text/plain content
.fi
.SH "SEE ALSO"
+.IR iconv (3),
.IR mhbuild (1),
.IR mhl (1),
.IR mhlist (1),
projects / nmh / blobdiff