-.TH MHSHOW %manext1% "April 9, 2014" "%nmhversion%"
+.TH MHSHOW %manext1% "February 8, 2015" "%nmhversion%"
.\"
.\" %nmhwarning%
.\"
.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
.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
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
messages, see
.IR inc (1)).
.PP
+The
+.B \-part
+switch can be used (one or more times) to restrict the
+set of subparts that will be displayed. (Obviously with no
+.B \-part
+switches, all parts will be considered.) If a
+.B \-part
+switch specifies a specific subpart (i.e., a "leaf" in the tree of
+MIME parts), then that part will always be displayed. If a
+.B \-part
+switch references a multipart/alternative part, then (in
+the absence of a
+.B \-type
+switch) only the default subpart of that multipart will be displayed.
+.PP
A part specification consists of a series of numbers separated by dots.
For example, in a multipart content containing three parts, these
would be named as 1, 2, and 3, respectively. If part 2 was also a
multipart content containing two parts, these would be named as 2.1 and
2.2, respectively. Note that the
.B \-part
-switch is effective for only
+switch is effective only for
messages containing a multipart content. If a message has some other
kind of content, or if the part is itself another multipart content, the
.B \-part
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
+.BR \-part ,
+to further restrict) the display of parts according to content type.
+One or more
+.B \-type
+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.
To specify a content, regardless of its subtype, just use the
name of the content, e.g., \*(lqaudio\*(rq. To specify a specific
subtype, separate the two with a slash, e.g., \*(lqaudio/basic\*(rq.
-Note that regardless of the values given to the `\-type' switch, a
+Note that regardless of the values given to the
+.B \-type
+switch, a
multipart content (of any subtype listed above) is always acted upon.
-Further note that if the `\-type' switch is used, and it is desirable to
-act on a message/external-body content, then the `\-type' switch must
+Further note that if the
+.B \-type
+switch is used, and it is 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
+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
.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
.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
^%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 ^ ~
projects / nmh / blobdiff