update mhshow, mhlist, and mhstore man pages for -prefer switch

diff --git a/man/mhlist.man b/man/mhlist.man
index a75e50d..093b7a8 100644 (file)
--- a/man/mhlist.man
+++ b/man/mhlist.man
@@ -18,6 +18,9 @@ mhlist \- list information about MIME messages
 .RB [ \-type
 .IR content ]
 \&...
+.RB [ \-prefer
+.IR content ]
+\&...
 .RB [ \-headers " | " \-noheaders ]
 .RB [ \-realsize " | " \-norealsize ]
 .RB [ \-rcache
@@ -152,9 +155,29 @@ switch must
 be used twice: once for message/external-body and once for the content
 externally referenced.
 .PP
-The parts of a multipart/alternative part are listed in the reverse
-order of their placement in the message.  The listing therefore is
-in decreasing order of preference, as defined in RFC 2046.
+By default, the parts of a multipart/alternative part are listed in
+the reverse order of their placement in the message.  The listing
+therefore is in decreasing order of preference, as defined in RFC
+2046.  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 preference order.  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.
+The
+.B \-prefer
+switch is functionally most important for
+.IR mhshow ,
+but is also implemented in
+.B mhlist
+and
+.B mhstore
+to make common part number ordering possible across all three programs.
 .SS "Checking the Contents"
 The
 .B \-check

diff --git a/man/mhshow.man b/man/mhshow.man
index 545f4b2..67516be 100644 (file)
--- a/man/mhshow.man
+++ b/man/mhshow.man
@@ -18,6 +18,9 @@ mhshow \- display MIME messages
 .RB [ \-type
 .IR content ]
 \&...
+.RB [ \-prefer
+.IR content ]
+\&...
 .RB [ \-concat " | " \-noconcat ]
 .RB [ \-textonly " | " \-notextonly ]
 .RB [ \-inlineonly " | " \-noinlineonly ]
@@ -128,7 +131,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
@@ -175,6 +178,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 +412,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

diff --git a/man/mhstore.man b/man/mhstore.man
index fbdd370..2484d69 100644 (file)
--- a/man/mhstore.man
+++ b/man/mhstore.man
@@ -20,6 +20,9 @@ mhstore \- store contents of MIME messages into files
 .RB [ \-type
 .IR content ]
 \&...
+.RB [ \-prefer
+.IR content ]
+\&...
 .RB [ \-auto " | " \-noauto ]
 .RB [ \-clobber
 .IR always " | " auto " | " suffix " | " ask " | " never ]
@@ -129,6 +132,26 @@ desirable to act on a message/external-body content, then the
 .B \-type
 switch must be used twice: once for message/external-body
 and once for the content externally referenced.
+.PP
+The
+.B \-prefer
+switch will alter the part ordering of multipart/alternative MIME sections
+in order to override the sender-imposed default ordering.
+The
+.B \-prefer
+switch is functionally most important for
+.BR mhshow ,
+but is also implemented in
+.B mhlist
+and
+.B mhstore
+to make common part number ordering possible across all three programs.
+See
+.IR mhlist (1)
+and
+.IR mhshow (1)
+for more information on
+.BR \-prefer.
 .SS "Checking the Contents"
 The
 .B \-check