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