Check for text/html display programs in this order: w3m, lynx, elinks.

[nmh] / man / mhshow.man

diff --git a/man/mhshow.man b/man/mhshow.man
index f55fbfe6a4bf71ae2981df5ba049186b6bdb0d23..8505d7e19dcc77bda309fbce9e8f75e151c21254 100644 (file)
--- a/man/mhshow.man
+++ b/man/mhshow.man
@@ -1,4 +1,4 @@
-.TH MHSHOW %manext1% "May 4, 2013" "%nmhversion%"
+.TH MHSHOW %manext1% "February 18, 2014" "%nmhversion%"
 .\"
 .\" %nmhwarning%
 .\"
@@ -224,16 +224,17 @@ The display string may contain the following escapes:
 .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
+%{parameter} Insert the parameter 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
@@ -257,6 +258,26 @@ control-\\) will tell
 .B mhshow
 to wrap things up immediately.
 .PP
+The {parameter} escape is typically used in a command line argument
+that should only be present if it has a non-null value.  Its value
+will be wrapped with single quotes if the escape is not so wrapped.
+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.  Note that when
+dealing with text that has been converted internally by
+.IR iconv (3),
+the \*(lqcharset\*(rq parameter will reflect the target character set
+of the text, rather than the original character set in the message.
+.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
@@ -268,8 +289,8 @@ 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
@@ -299,14 +320,13 @@ Example entries might be:
 .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, its expansion
+will be wrapped with single quotes.
 .PP
 Finally,
 .B mhshow
@@ -321,6 +341,18 @@ switch can be given to tell
 .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
@@ -328,15 +360,15 @@ encounters a \*(lqcharset\*(rq parameter for
 this content, it checks if your terminal can display this character
 set natively.
 .B mhn
-checks this by examining 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
@@ -379,29 +411,24 @@ needed beforehand.
 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
@@ -599,6 +626,7 @@ is checked.
 ^moreproc:~^Default program to display text/plain content
 .fi
 .SH "SEE ALSO"
+.IR iconv (3),
 .IR mhbuild (1),
 .IR mhl (1),
 .IR mhlist (1),