X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/b36e2ab7892cdf30a8b33d02e00af70398013b5d..d205d39a:/man/mhlist.man?ds=sidebyside diff --git a/man/mhlist.man b/man/mhlist.man index 9ee15dbc..021d5d84 100644 --- a/man/mhlist.man +++ b/man/mhlist.man @@ -1,81 +1,145 @@ -.\" +.TH MHLIST %manext1% 2015-02-06 "%nmhversion%" +. .\" %nmhwarning% -.\" $Id$ -.\" -.\" include the -mh macro file -.so %etcdir%/tmac.h -.\" -.TH MHLIST %manext1% "%nmhdate%" MH.6.8 [%nmhversion%] +. .SH NAME -mhlist \- list information about MIME messages +mhlist \- list information about nmh 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 -The \fImhlist\fR command allows you to list information (essentially -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 -displayed above the listing. - -The `\-realsize' switch tells \fImhlist\fR 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. - -If the `\-verbose' switch is present, then the listing will show -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 -file as the source message, rather than a message from a folder. -If you specify this file as \*(lq-\*(rq, then \fImhlist\fR will -accept the source message on the standard input. Note that the +The +.B mhlist +command allows you to list information (a table of contents, essentially) +about the various parts of a collection of MIME (multi-media) messages. +.PP +.B mhlist +manipulates MIME 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 (the default). +.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. +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, 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. 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 -message, just like any other \fInmh\fR message. It should \fBNOT\fR -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. - +message, just like any other +.B nmh +message. It should +.I not +be in mail drop format (to convert a file in +mail drop format to 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 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 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. -.ne 18 +be found in RFC 2046. +.PP A list of commonly used contents is briefly reproduced here: -.sp +.PP +.RS 5 .nf -.in +.5i .ta \w'application 'u Type Subtypes ---- -------- @@ -86,82 +150,90 @@ application octet-stream, postscript image jpeg, gif, png audio basic video mpeg -.re -.in -.5i .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. -Note that regardless of the values given to the `\-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 -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 -integrity checksum. If a content has such a checksum (specified as a -Content-MD5 header field), then \fImhlist\fR will attempt to verify the -integrity of the content. -.Fi -^$HOME/\&.mh\(ruprofile~^The user profile -.Pr +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 +.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 +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 Content-MD5 header field), then +.B mhlist +will attempt to verify the integrity of the content. +.SH FILES +.fc ^ ~ +.nf +.ta \w'%nmhetcdir%/ExtraBigFileName 'u +^$HOME/.mh_profile~^The user profile +.fi +.SH "PROFILE COMPONENTS" +.fc ^ ~ +.nf +.ta 2.4i +.ta \w'ExtraBigProfileName 'u ^Path:~^To determine the user's nmh directory -.Ps ^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 -message selected will become the current message. -.En +message selected will become the current message, unless the +.B \-nochangecur +option is specified.