Replace getcpy() with mh_xstrdup() where the string isn't NULL.

[nmh] / man / mhlist.man

diff --git a/man/mhlist.man b/man/mhlist.man
index a75e50d82384e0b4b7b068b573349b97347ac0a2..8d6c39a2009c95fb47323207c55a4d91b1da27e5 100644 (file)
--- a/man/mhlist.man
+++ b/man/mhlist.man
@@ -1,4 +1,4 @@
-.TH MHLIST %manext1% "August 20, 2014" "%nmhversion%"
+.TH MHLIST %manext1% "February 6, 2015" "%nmhversion%"

 .\"
 .\" %nmhwarning%
 .\"
 .\"
 .\" %nmhwarning%
 .\"


@@ -8,6 +8,8 @@ mhlist \- list information about MIME messages
 .HP 5
 .na
 .B mhlist
 .HP 5
 .na
 .B mhlist

+.RB [ \-help ]
+.RB [ \-version ]

 .RI [ +folder ]
 .RI [ msgs ]
 .RB [ \-file
 .RI [ +folder ]
 .RI [ msgs ]
 .RB [ \-file


@@ -18,6 +20,9 @@ mhlist \- list information about MIME messages
 .RB [ \-type
 .IR content ]
 \&...
 .RB [ \-type
 .IR content ]
 \&...

+.RB [ \-prefer
+.IR content ]
+\&...

 .RB [ \-headers " | " \-noheaders ]
 .RB [ \-realsize " | " \-norealsize ]
 .RB [ \-rcache
 .RB [ \-headers " | " \-noheaders ]
 .RB [ \-realsize " | " \-norealsize ]
 .RB [ \-rcache


@@ -28,8 +33,6 @@ mhlist \- list information about MIME messages
 .RB [ \-changecur " | " \-nochangecur ]
 .RB [ \-verbose " | " \-noverbose ]
 .RB [ \-disposition " | " \-nodisposition ]
 .RB [ \-changecur " | " \-nochangecur ]
 .RB [ \-verbose " | " \-noverbose ]
 .RB [ \-disposition " | " \-nodisposition ]

-.RB [ \-version ]
-.RB [ \-help ]

 .ad
 .SH DESCRIPTION
 The
 .ad
 .SH DESCRIPTION
 The


@@ -95,24 +98,46 @@ By default,
 .B mhlist
 will list information about the entire
 message (all of its parts).  By using the
 .B mhlist
 will list information about the entire
 message (all of its parts).  By using the

-.B \-part
+.BR \-part ,
+.BR \-type ,

 and
 and

-.B \-type
-switches, you may limit the scope of this command to particular
-subparts (of a multipart content) and/or particular content types.
-.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 \-prefer
+switches, you may limit and reorder the set of parts to be listed,
+based on part number and/or content type.
+.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
 .B \-part

-switch is effective for only
-messages containing a multipart content.  If a message has some other
-kind of content, or if the part is itself another multipart content, the
+switch is effective for only 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
 .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 selection 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.
 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.


@@ -152,9 +177,29 @@ switch must
 be used twice: once for message/external-body and once for the content
 externally referenced.
 .PP
 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 numbering possible across all three programs.

 .SS "Checking the Contents"
 The
 .B \-check
 .SS "Checking the Contents"
 The
 .B \-check