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 1cd7d0ed847082b77903aad77c8ed197c09756b8..8d6c39a2009c95fb47323207c55a4d91b1da27e5 100644 (file)
--- a/man/mhlist.man
+++ b/man/mhlist.man
@@ -1,81 +1,151 @@
+.TH MHLIST %manext1% "February 6, 2015" "%nmhversion%"

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

-.\" $Id$

 .\"
 .\"

-.\" include the -mh macro file
-.so %etcdir%/tmac.h
-.\"
-.TH MHLIST %manext1% MH.6.8 [%nmhversion%]

 .SH NAME
 mhlist \- list information about MIME messages
 .SH SYNOPSIS
 .SH NAME
 mhlist \- list information about MIME messages
 .SH SYNOPSIS

-.in +.5i
-.ti -.5i
-mhlist \%[+folder] \%[msgs] \%[\-file file]
-.br
-\%[\-part number]... \%[\-type content]...
-.br
-\%[\-headers] \%[\-noheaders]
-\%[\-realsize] \%[\-norealsize]
-.br
-\%[\-rcache policy] \%[\-wcache policy]
-\%[\-check] \%[\-nocheck]
-.br
-\%[\-verbose] \%[\-noverbose]
-\%[\-version]
-\%[\-help]
-.in -.5i
-
+.HP 5
+.na
+.B mhlist
+.RB [ \-help ]
+.RB [ \-version ]
+.RI [ +folder ]
+.RI [ msgs ]
+.RB [ \-file
+.IR file ]
+.RB [ \-part
+.IR number ]
+\&...
+.RB [ \-type
+.IR content ]
+\&...
+.RB [ \-prefer
+.IR content ]
+\&...
+.RB [ \-headers " | " \-noheaders ]
+.RB [ \-realsize " | " \-norealsize ]
+.RB [ \-rcache
+.IR policy ]
+.RB [ \-wcache
+.IR policy ]
+.RB [ \-check " | " \-nocheck ]
+.RB [ \-changecur " | " \-nochangecur ]
+.RB [ \-verbose " | " \-noverbose ]
+.RB [ \-disposition " | " \-nodisposition ]
+.ad

 .SH DESCRIPTION
 .SH DESCRIPTION

-The \fImhlist\fR command allows you to list information (essentially
+The
+.B mhlist
+command allows you to list information (essentially

 a table of contents) about the various parts of a collection of
 MIME (multi-media) messages.
 a table of contents) about the various parts of a collection of
 MIME (multi-media) messages.

-
-\fImhlist\fR manipulates MIME (multi-media messages) as specified
-in RFC\-2045 thru RFC\-2049.
-
-The `\-headers' switch indicates that a one-line banner should be
+.PP
+.B mhlist
+manipulates MIME (multi-media messages) as specified
+in RFC 2045 to RFC 2049 (See
+.IR mhbuild (1)).
+.PP
+The
+.B \-headers
+switch indicates that a one-line banner should be

 displayed above the listing.
 displayed above the listing.

-
-The `\-realsize' switch tells \fImhlist\fR to evaluate the
+.PP
+The
+.B \-realsize
+switch tells
+.B mhlist
+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.
 \*(lqnative\*(rq (decoded) format of each content prior to listing.
 This provides an accurate count at the expense of a small delay.

-
-If the `\-verbose' switch is present, then the listing will show
+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
+switch is present, then the listing will show

 any \*(lqextra\*(rq information that is present in the message,
 any \*(lqextra\*(rq information that is present in the message,

-such as comments in the Content-Type header.
-
-The option `\-file\ file' directs \fImhlist\fR to use the specified
+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
+directs
+.B mhlist
+to use the specified

 file as the source message, rather than a message from a folder.
 file as the source message, rather than a message from a folder.

-If you specify this file as \*(lq-\*(rq, then \fImhlist\fR will
+If you specify this file as \*(lq-\*(rq, then
+.B mhlist
+will

 accept the source message on the standard input.  Note that the
 file, or input from standard input should be a validly formatted
 accept the source message on the standard input.  Note that the
 file, or input from standard input should be a validly formatted

-message, just like any other \fInmh\fR message.  It should \fBNOT\fR
+message, just like any other
+.B nmh
+message.  It should
+.B NOT

 be in mail drop format (to convert a file in mail drop format to
 be in mail drop format (to convert a file in mail drop format to

-a folder of \fInmh\fR messages, see \fIinc\fR\0(1)).
-
-By default, \fImhlist\fR will list information about the entire
-message (all of its parts).  By using the `\-part' and `\-type'
-switches, you may limit the scope of this command to particular
-subparts (of a multipart content) and/or particular content types.
-
-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 `\-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
-`\-part' switch will not prevent the content from being acted upon.
-
+a folder of
+.B nmh
+messages, see
+.IR inc (1)).
+.PP
+By default,
+.B mhlist
+will list information about the entire
+message (all of its parts).  By using the
+.BR \-part ,
+.BR \-type ,
+and
+.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
+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
+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.
-.ne 18
+be found in RFC 2046.
+.PP

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

-.sp
+.PP
+.RS 5

 .nf
 .nf

-.in +.5i

 .ta \w'application  'u
 Type   Subtypes
 ----   --------
 .ta \w'application  'u
 Type   Subtypes
 ----   --------


@@ -86,82 +156,94 @@ application        octet-stream, postscript
 image  jpeg, gif, png
 audio  basic
 video  mpeg
 image  jpeg, gif, png
 audio  basic
 video  mpeg

-.re
-.in -.5i

 .fi
 .fi

-.sp
+.RE
+.PP

 A legal MIME message must contain a subtype specification.
 .PP
 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.
 A legal MIME message must contain a subtype specification.
 .PP
 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.
 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.
 be used twice: once for message/external-body and once for the content
 externally referenced.

-
-.Uh "Checking the Contents"
-The `\-check' switch tells \fImhlist\fR to check each content for an
+.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
+switch tells
+.B mhlist
+to check each content for an

 integrity checksum.  If a content has such a checksum (specified as a
 integrity checksum.  If a content has such a checksum (specified as a

-Content-MD5 header field), then \fImhlist\fR will attempt to verify the
+Content-MD5 header field), then
+.B mhlist
+will attempt to verify the

 integrity of the content.
 integrity of the content.

-.Fi
+.SH FILES
+.fc ^ ~
+.nf
+.ta \w'%nmhetcdir%/ExtraBigFileName  'u

 ^$HOME/\&.mh\(ruprofile~^The user profile
 ^$HOME/\&.mh\(ruprofile~^The user profile

-.Pr
+.fi
+.SH "PROFILE COMPONENTS"
+.fc ^ ~
+.nf
+.ta 2.4i
+.ta \w'ExtraBigProfileName  'u

 ^Path:~^To determine the user's nmh directory
 ^Path:~^To determine the user's nmh directory

-.Ps

 ^Current\-Folder:~^To find the default current folder
 ^Current\-Folder:~^To find the default current folder

-.Sa
-mhbuild(1), mhshow(1), mhstore(1), sendfiles(1)
-.br
-RFC\-2045:
-.br
-   \fIMultipurpose Internet Mail Extensions (MIME) Part One:
-.br
-   Format of Internet Message Bodies\fR,
-.br
-RFC\-2046:
-.br
-   \fIMultipurpose Internet Mail Extensions (MIME) Part Two:
-.br
-   Media Types\fR,
-.br
-RFC\-2047:
-.br
-   \fIMultipurpose Internet Mail Extensions (MIME) Part Three:
-.br
-   Message Header Extensions for Non-ASCII Text\fR,
-.br
-RFC\-2048:
-.br
-   \fIMultipurpose Internet Mail Extensions (MIME) Part Four:
-.br
-   Registration Procedures\fR,
-.br
-RFC\-2049:
-.br
-   \fIMultipurpose Internet Mail Extensions (MIME) Part Five:
-.br
-   Conformance Criteria and Examples\fR.
-.De
-`+folder' defaults to the current folder
-.Ds
-`msgs' defaults to cur
-.Ds
-`\-nocheck'
-.Ds
-`\-headers'
-.Ds
-`\-realsize'
-.Ds
-`\-rcache ask'
-.Ds
-`\-wcache ask'
-.Ds
-`\-noverbose'
-.Co
+.fi
+.SH "SEE ALSO"
+.IR mhbuild (1),
+.IR mhshow (1),
+.IR mhstore (1)
+.SH DEFAULTS
+.nf
+.RB ` +folder "' defaults to the current folder"
+.RB ` msgs "' defaults to cur"
+.RB ` \-nocheck '
+.RB ` \-headers '
+.RB ` \-realsize '
+.RB ` \-rcache\ ask '
+.RB ` \-wcache\ ask '
+.RB ` \-changecur '
+.RB ` \-noverbose '
+.RB ` \-nodisposition '
+.fi
+.SH CONTEXT

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

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