X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/275a31b54179d2afa6777072325d1bcba02e0b7b..29ff4f879ba9eea142df4e8caf436d0dd933218c:/man/mhshow.man

diff --git a/man/mhshow.man b/man/mhshow.man
index 545f4b2d..58e2c195 100644
--- a/man/mhshow.man
+++ b/man/mhshow.man
@@ -1,4 +1,4 @@
-.TH MHSHOW %manext1% "April 9, 2014" "%nmhversion%"
+.TH MHSHOW %manext1% "March 24, 2016" "%nmhversion%"
 .\"
 .\" %nmhwarning%
 .\"
@@ -18,9 +18,13 @@ mhshow \- display MIME messages
 .RB [ \-type
 .IR content ]
 \&...
+.RB [ \-prefer
+.IR content ]
+\&...
 .RB [ \-concat " | " \-noconcat ]
 .RB [ \-textonly " | " \-notextonly ]
 .RB [ \-inlineonly " | " \-noinlineonly ]
+.RB [ \-header " | " \-noheader ]
 .RB [ \-form
 .IR formfile ]
 .RB [ \-markform
@@ -56,14 +60,13 @@ and
 .B \-noinlineonly
 switches.
 In addition, by using the
-.B \-part
+.BR \-part ,
+.BR \-type ,
 and
-.B \-type
-switches, you may
-further limit the scope of
-.B mhshow
-to particular subparts (of a
-multipart content) and/or particular content types.  The inclusion of any
+.B \-prefer
+switches, you may limit and reorder the set of parts to be displayed,
+based on part number and/or content type.
+The inclusion of any
 .B \-part
 or
 .B \-type
@@ -72,9 +75,25 @@ switches will override the default settings of
 and
 .BR \-inlineonly.
 .PP
+The
+.B \-header
+switch control whether
+.B mhshow
+will print a message separator header before each message that it
+displays.  The header format can be controlled using
+.B \-headerform
+to specify a file containing
+.IR mh\-format (5)
+instructions.  A copy of the built-in default
+headerform can be found in %nmhetcdir%/mhshow.header, for reference.
+In addition to the normal set of
+.IR mh\-format (5)
+instructions, a "%{folder}" escape provides a
+string representing the current folder.
+.PP
 By default
 .B mhshow
-will concatenate all content under one pager.  If you which each part to
+will concatenate all content under one pager.  If you want each part to
 displayed separately, you can override the default behavior with
 .B \-noconcat.
 .PP
@@ -128,7 +147,7 @@ switch will not prevent the content from being acted upon.
 .PP
 The
 .B \-type
-switch can also be used to restrict (or, when used in conjunction with 
+switch can also be used to restrict (or, when used in conjunction with
 .BR \-part ,
 to further restrict) the display of parts according to content type.
 One or more
@@ -137,6 +156,16 @@ switches part will only select the first match
 from a multipart/alternative, even if there is more than one
 subpart that matches (one of) the given content type(s).
 .PP
+Using either
+.B \-part
+or
+.B -type
+switches alone will cause either to select
+the part(s) they match.  Using them together will select only
+the part(s) matched by both (sets of) switches.  In other
+words, the result is the intersection, and not the union, of their
+separate match results.
+.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.
@@ -175,6 +204,38 @@ act on a message/external-body content, then the
 switch must
 be used twice: once for message/external-body and once for the content
 externally referenced.
+.PP
+In the absence of
+.BR \-prefer ,
+.B mhshow
+will select the "best" displayable subpart from
+multipart/alternative content.  The
+.B \-prefer
+switch can be used (one or more times, in order of descending
+preference) to let MH know which content types from a
+multipart/alternative MIME part are preferred by the user, in order to
+override the default selection for display.  For example, mail is
+often sent containing both plaintext and HTML-formatted versions of
+the same content, and the HTML version is usually indicated to be the
+"best" format for viewing.  Using \*(lq-prefer text/plain\*(rq will
+cause the plaintext version to be displayed if possible, but still
+allow display of the HTML part if there is no plaintext subpart
+available.  Using \*(lq-prefer text/plain -prefer image/png\*(rq
+would add a preference for PNG images, which might or might not
+ever appear in the same multipart/alternative section with text/plain.
+Implementation note:  RFC 2046 requires that the subparts
+of a multipart/alternative be ordered according to "faithfulness to
+the original content", and MH by default selects the subpart ranked
+most "faithful" by that ordering.  The
+.B \-prefer
+switch reorders the alternative parts (only internally, never changing
+the message file) to move the user's preferred part(s) to the "most
+faithful" position.  Thus, when viewed by
+.BR mhlist ,
+the ordering of multipart/alternative parts will appear to change when
+invoked with or without various
+.B \-prefer
+switches.
 .SS "Unseen Sequence"
 If the profile entry \*(lqUnseen\-Sequence\*(rq is present and
 non\-empty, then
@@ -377,7 +438,7 @@ 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.  See the
-.BR mhparam (1)
+.IR mhparam (1)
 man page for how determine whether your
 .B nmh
 installation includes
@@ -636,8 +697,9 @@ next.  The default marker can be changed using the
 .B \-markform
 switch to specify a file containing
 .IR mh\-format (5)
-instructions to use when displaying the content marker.  In addition to
-the normal set of
+instructions to use when displaying the content marker.  A copy of the
+default markform can be found in %nmhetcdir%/mhshow.marker, for
+reference.  In addition to the normal set of
 .IR mh\-format (5)
 instructions, the following
 .I component
@@ -687,6 +749,7 @@ is checked.
 ^%nmhetcdir%/mhn.defaults~^System default MIME profile entries
 ^%nmhetcdir%/mhl.headers~^The headers template
 ^%nmhetcdir%/mhshow.marker~^Example content marker
+^%nmhetcdir%/mhshow.header~^Example message separator header
 .fi
 .SH "PROFILE COMPONENTS"
 .fc ^ ~