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

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