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 57d01187b199afe4c312307ee568924bf87aca76..8d6c39a2009c95fb47323207c55a4d91b1da27e5 100644 (file)
--- a/man/mhlist.man
+++ b/man/mhlist.man
@@ -1,4 +1,4 @@
-.TH MHLIST %manext1% "%nmhdate%" MH.6.8 [%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


@@ -25,9 +30,9 @@ mhlist \- list information about MIME messages
 .RB [ \-wcache
 .IR policy ]
 .RB [ \-check " | " \-nocheck ]
 .RB [ \-wcache
 .IR policy ]
 .RB [ \-check " | " \-nocheck ]

+.RB [ \-changecur " | " \-nochangecur ]

 .RB [ \-verbose " | " \-noverbose ]
 .RB [ \-verbose " | " \-noverbose ]

-.RB [ \-version ]
-.RB [ \-help ]
+.RB [ \-disposition " | " \-nodisposition ]

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


@@ -38,7 +43,7 @@ MIME (multi-media) messages.
 .PP
 .B mhlist
 manipulates MIME (multi-media messages) as specified
 .PP
 .B mhlist
 manipulates MIME (multi-media messages) as specified

-in RFC\-2045 thru RFC\-2049 (See
+in RFC 2045 to RFC 2049 (See

 .IR mhbuild (1)).
 .PP
 The
 .IR mhbuild (1)).
 .PP
 The


@@ -53,6 +58,8 @@ switch tells
 to evaluate the
 \*(lqnative\*(rq (decoded) format of each content prior to listing.
 This provides an accurate count at the expense of a small delay.
 to evaluate the
 \*(lqnative\*(rq (decoded) format of each content prior to listing.
 This provides an accurate count at the expense of a small delay.

+In either case, sizes will be expressed using SI prefix abbreviations
+(K/M/G/T), which are based on factors of 1000.

 .PP
 If the
 .B \-verbose
 .PP
 If the
 .B \-verbose


@@ -60,6 +67,11 @@ switch is present, then the listing will show
 any \*(lqextra\*(rq information that is present in the message,
 such as comments in the \*(lqContent-Type\*(rq header.
 .PP
 any \*(lqextra\*(rq information that is present in the message,
 such as comments in the \*(lqContent-Type\*(rq header.
 .PP

+If the
+.B \-disposition
+switch is present, then the listing will show any relevant information from
+the \*(lqContent-Disposition\*(rq header.
+.PP

 The option
 .B \-file
 .I file
 The option
 .B \-file
 .I file


@@ -86,27 +98,49 @@ 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
 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.
+be found in RFC 2046.

 .PP
 A list of commonly used contents is briefly reproduced here:
 .PP
 .PP
 A list of commonly used contents is briefly reproduced here:
 .PP


@@ -142,6 +176,30 @@ 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.
 switch must
 be used twice: once for message/external-body and once for the content
 externally referenced.

+.PP
+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


@@ -156,7 +214,7 @@ integrity of the content.
 .SH FILES
 .fc ^ ~
 .nf
 .SH FILES
 .fc ^ ~
 .nf

-.ta \w'%etcdir%/ExtraBigFileName  'u
+.ta \w'%nmhetcdir%/ExtraBigFileName  'u

 ^$HOME/\&.mh\(ruprofile~^The user profile
 .fi
 .SH "PROFILE COMPONENTS"
 ^$HOME/\&.mh\(ruprofile~^The user profile
 .fi
 .SH "PROFILE COMPONENTS"


@@ -168,10 +226,9 @@ integrity of the content.
 ^Current\-Folder:~^To find the default current folder
 .fi
 .SH "SEE ALSO"
 ^Current\-Folder:~^To find the default current folder
 .fi
 .SH "SEE ALSO"

-,IR mhbuild (1),
+.IR mhbuild (1),

 .IR mhshow (1),
 .IR mhshow (1),

-.IR mhstore (1),
-.IR sendfiles (1)
+.IR mhstore (1)

 .SH DEFAULTS
 .nf
 .RB ` +folder "' defaults to the current folder"
 .SH DEFAULTS
 .nf
 .RB ` +folder "' defaults to the current folder"


@@ -181,8 +238,12 @@ integrity of the content.
 .RB ` \-realsize '
 .RB ` \-rcache\ ask '
 .RB ` \-wcache\ ask '
 .RB ` \-realsize '
 .RB ` \-rcache\ ask '
 .RB ` \-wcache\ ask '

+.RB ` \-changecur '

 .RB ` \-noverbose '
 .RB ` \-noverbose '

+.RB ` \-nodisposition '

 .fi
 .SH CONTEXT
 If a folder is given, it will become the current folder.  The last
 .fi
 .SH CONTEXT
 If a folder is given, it will become the current folder.  The last

-message selected will become the current message.
+message selected will become the current message, unless the
+.B \-nochangecur
+option is specified.