From: Paul Fox Date: Wed, 4 Feb 2015 17:07:27 +0000 (-0500) Subject: update mhshow, mhlist, and mhstore man pages for -prefer switch X-Git-Url: https://diplodocus.org/git/nmh/commitdiff_plain/570530220b71d3aea5185b8e079ea0345bd0a95f?ds=inline update mhshow, mhlist, and mhstore man pages for -prefer switch --- diff --git a/man/mhlist.man b/man/mhlist.man index a75e50d8..093b7a8c 100644 --- 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 545f4b2d..67516be5 100644 --- 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 fbdd3702..2484d69e 100644 --- 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