diplodocus.org Git - nmh/blob - man/mhlist.man

   1 .TH MHLIST %manext1% 2015-02-06 "%nmhversion%"
   2 .
   3 .\" %nmhwarning%
   4 .
   5 .SH NAME
   6 mhlist \- list information about nmh MIME messages
   7 .SH SYNOPSIS
   8 .HP 5
   9 .na
  10 .B mhlist
  11 .RB [ \-help ]
  12 .RB [ \-version ]
  13 .RI [ +folder ]
  14 .RI [ msgs ]
  15 .RB [ \-file
  16 .IR file ]
  17 .RB [ \-part
  18 .IR number ]
  19 \&...
  20 .RB [ \-type
  21 .IR content ]
  22 \&...
  23 .RB [ \-prefer
  24 .IR content ]
  25 \&...
  26 .RB [ \-headers " | " \-noheaders ]
  27 .RB [ \-realsize " | " \-norealsize ]
  28 .RB [ \-rcache
  29 .IR policy ]
  30 .RB [ \-wcache
  31 .IR policy ]
  32 .RB [ \-check " | " \-nocheck ]
  33 .RB [ \-changecur " | " \-nochangecur ]
  34 .RB [ \-verbose " | " \-noverbose ]
  35 .RB [ \-disposition " | " \-nodisposition ]
  36 .ad
  37 .SH DESCRIPTION
  38 The
  39 .B mhlist
  40 command allows you to list information (a table of contents, essentially)
  41 about the various parts of a collection of MIME (multi-media) messages.
  42 .PP
  43 .B mhlist
  44 manipulates MIME messages as specified in RFC 2045 to RFC 2049 (See
  45 .IR mhbuild (1)).
  46 .PP
  47 The
  48 .B \-headers
  49 switch indicates that a one-line banner should be displayed above the
  50 listing (the default).
  51 .PP
  52 The
  53 .B \-realsize
  54 switch tells
  55 .B mhlist
  56 to evaluate the \*(lqnative\*(rq (decoded) format of each content prior
  57 to listing.  This provides an accurate count at the expense of a small delay.
  58 In either case, sizes will be expressed using SI prefix abbreviations
  59 (K/M/G/T), which are based on factors of 1000.
  60 .PP
  61 If the
  62 .B \-verbose
  63 switch is present, then the listing will show any \*(lqextra\*(rq
  64 information that is present in the message, such as comments in the
  65 \*(lqContent-Type\*(rq header.
  66 .PP
  67 If the
  68 .B \-disposition
  69 switch is present, then the listing will show any relevant information from
  70 the \*(lqContent-Disposition\*(rq header.
  71 .PP
  72 The option
  73 .B \-file
  74 .I file
  75 directs
  76 .B mhlist
  77 to use the specified file as the source message, rather than a message
  78 from a folder.  If you specify this file as \*(lq-\*(rq, then
  79 .B mhlist
  80 will accept the source message on the standard input.  Note that the
  81 file, or input from standard input should be a validly formatted
  82 message, just like any other
  83 .B nmh
  84 message.  It should
  85 .I not
  86 be in mail drop format (to convert a file in
  87 mail drop format to a folder of
  88 .B nmh
  89 messages, see
  90 .IR inc (1)).
  91 .PP
  92 By default,
  93 .B mhlist
  94 will list information about the entire message (all of its parts).
  95 By using the
  96 .BR \-part ,
  97 .BR \-type ,
  98 and
  99 .B \-prefer
 100 switches, you may limit and reorder the set of parts to be listed,
 101 based on part number and/or content type.
 102 .PP
 103 A part specification consists of a series of numbers separated by
 104 dots.  For example, in a multipart content containing three parts,
 105 these would be named as 1, 2, and 3, respectively.  If part 2 was also
 106 a multipart content containing two parts, these would be named as 2.1
 107 and 2.2, respectively.  Note that the
 108 .B \-part
 109 switch is effective only for messages containing a multipart content.
 110 If a message has some other kind of content, or if the part is itself
 111 another multipart content, the
 112 .B \-part
 113 switch will not prevent the content from being acted upon.
 114 .PP
 115 The
 116 .B \-type
 117 switch can also be used to restrict (or, when used in conjunction with
 118 .BR \-part ,
 119 to further restrict) the selection of parts according to content type.
 120 One or more
 121 .B \-type
 122 switches part will only select the first match from a multipart/alternative,
 123 even if there is more than one subpart that matches (one of) the given
 124 content type(s).
 125 .PP
 126 Using either
 127 .B \-part
 128 or
 129 .B -type
 130 switches alone will cause either to select the part(s) they match.
 131 Using them together will select only the part(s) matched by both
 132 (sets of) switches.  In other words, the result is the intersection,
 133 and not the union, of their separate match results.
 134 .PP
 135 A content specification consists of a content type and a subtype.
 136 The initial list of \*(lqstandard\*(rq content types and subtypes can
 137 be found in RFC 2046.
 138 .PP
 139 A list of commonly used contents is briefly reproduced here:
 140 .PP
 141 .RS 5
 142 .nf
 143 .ta \w'application  'u
 144 Type    Subtypes
 145 ----    --------
 146 text    plain, enriched
 147 multipart       mixed, alternative, digest, parallel
 148 message rfc822, partial, external-body
 149 application     octet-stream, postscript
 150 image   jpeg, gif, png
 151 audio   basic
 152 video   mpeg
 153 .fi
 154 .RE
 155 .PP
 156 A legal MIME message must contain a subtype specification.
 157 .PP
 158 To specify a content, regardless of its subtype, just use the
 159 name of the content, e.g., \*(lqaudio\*(rq.  To specify a specific
 160 subtype, separate the two with a slash, e.g., \*(lqaudio/basic\*(rq.
 161 Note that regardless of the values given to the
 162 .B \-type
 163 switch, a multipart content (of any subtype listed above) is always
 164 acted upon.  Further note that if the
 165 .B \-type
 166 switch is used, and it is desirable to act on a message/external-body
 167 content, then the
 168 .B \-type
 169 switch must be used twice: once for message/external-body and once
 170 for the content externally referenced.
 171 .PP
 172 By default, the parts of a multipart/alternative part are listed in
 173 the reverse order of their placement in the message.  The listing,
 174 therefore, is in decreasing order of preference, as defined in RFC
 175 2046.  The
 176 .B \-prefer
 177 switch can be used (one or more times, in order of descending
 178 preference) to let MH know which content types from a
 179 multipart/alternative MIME part are preferred by the user, in order to
 180 override the default preference order.  Thus, when viewed by
 181 .BR mhlist ,
 182 the ordering of multipart/alternative parts will appear to change when
 183 invoked with or without various
 184 .B \-prefer
 185 switches.
 186 The
 187 .B \-prefer
 188 switch is functionally most important for
 189 .IR mhshow ,
 190 but is also implemented in
 191 .B mhlist
 192 and
 193 .B mhstore
 194 to make common part numbering possible across all three programs.
 195 .SS "Checking the Contents"
 196 The
 197 .B \-check
 198 switch tells
 199 .B mhlist
 200 to check each content for an integrity checksum.  If a content has
 201 such a checksum (specified as a Content-MD5 header field), then
 202 .B mhlist
 203 will attempt to verify the integrity of the content.
 204 .SH FILES
 205 .fc ^ ~
 206 .nf
 207 .ta \w'%nmhetcdir%/ExtraBigFileName  'u
 208 ^$HOME/.mh_profile~^The user profile
 209 .fi
 210 .SH "PROFILE COMPONENTS"
 211 .fc ^ ~
 212 .nf
 213 .ta 2.4i
 214 .ta \w'ExtraBigProfileName  'u
 215 ^Path:~^To determine the user's nmh directory
 216 ^Current\-Folder:~^To find the default current folder
 217 .fi
 218 .SH "SEE ALSO"
 219 .IR mhbuild (1),
 220 .IR mhshow (1),
 221 .IR mhstore (1)
 222 .SH DEFAULTS
 223 .nf
 224 .RB ` +folder "' defaults to the current folder"
 225 .RB ` msgs "' defaults to cur"
 226 .RB ` \-nocheck '
 227 .RB ` \-headers '
 228 .RB ` \-realsize '
 229 .RB ` \-rcache\ ask '
 230 .RB ` \-wcache\ ask '
 231 .RB ` \-changecur '
 232 .RB ` \-noverbose '
 233 .RB ` \-nodisposition '
 234 .fi
 235 .SH CONTEXT
 236 If a folder is given, it will become the current folder.  The last
 237 message selected will become the current message, unless the
 238 .B \-nochangecur
 239 option is specified.