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 NOT be in mail drop format (to convert a file in
  85 mail drop format to a folder of
  86 .B nmh
  87 messages, see
  88 .IR inc (1)).
  89 .PP
  90 By default,
  91 .B mhlist
  92 will list information about the entire message (all of its parts).
  93 By using the
  94 .BR \-part ,
  95 .BR \-type ,
  96 and
  97 .B \-prefer
  98 switches, you may limit and reorder the set of parts to be listed,
  99 based on part number and/or content type.
 100 .PP
 101 A part specification consists of a series of numbers separated by
 102 dots.  For example, in a multipart content containing three parts,
 103 these would be named as 1, 2, and 3, respectively.  If part 2 was also
 104 a multipart content containing two parts, these would be named as 2.1
 105 and 2.2, respectively.  Note that the
 106 .B \-part
 107 switch is effective only for messages containing a multipart content.
 108 If a message has some other kind of content, or if the part is itself
 109 another multipart content, the
 110 .B \-part
 111 switch will not prevent the content from being acted upon.
 112 .PP
 113 The
 114 .B \-type
 115 switch can also be used to restrict (or, when used in conjunction with
 116 .BR \-part ,
 117 to further restrict) the selection of parts according to content type.
 118 One or more
 119 .B \-type
 120 switches part will only select the first match from a multipart/alternative,
 121 even if there is more than one subpart that matches (one of) the given
 122 content type(s).
 123 .PP
 124 Using either
 125 .B \-part
 126 or
 127 .B -type
 128 switches alone will cause either to select the part(s) they match.
 129 Using them together will select only the part(s) matched by both
 130 (sets of) switches.  In other words, the result is the intersection,
 131 and not the union, of their separate match results.
 132 .PP
 133 A content specification consists of a content type and a subtype.
 134 The initial list of \*(lqstandard\*(rq content types and subtypes can
 135 be found in RFC 2046.
 136 .PP
 137 A list of commonly used contents is briefly reproduced here:
 138 .PP
 139 .RS 5
 140 .nf
 141 .ta \w'application  'u
 142 Type    Subtypes
 143 ----    --------
 144 text    plain, enriched
 145 multipart       mixed, alternative, digest, parallel
 146 message rfc822, partial, external-body
 147 application     octet-stream, postscript
 148 image   jpeg, gif, png
 149 audio   basic
 150 video   mpeg
 151 .fi
 152 .RE
 153 .PP
 154 A legal MIME message must contain a subtype specification.
 155 .PP
 156 To specify a content, regardless of its subtype, just use the
 157 name of the content, e.g., \*(lqaudio\*(rq.  To specify a specific
 158 subtype, separate the two with a slash, e.g., \*(lqaudio/basic\*(rq.
 159 Note that regardless of the values given to the
 160 .B \-type
 161 switch, a multipart content (of any subtype listed above) is always
 162 acted upon.  Further note that if the
 163 .B \-type
 164 switch is used, and it is desirable to act on a message/external-body
 165 content, then the
 166 .B \-type
 167 switch must be used twice: once for message/external-body and once
 168 for the content externally referenced.
 169 .PP
 170 By default, the parts of a multipart/alternative part are listed in
 171 the reverse order of their placement in the message.  The listing,
 172 therefore, is in decreasing order of preference, as defined in RFC
 173 2046.  The
 174 .B \-prefer
 175 switch can be used (one or more times, in order of descending
 176 preference) to let MH know which content types from a
 177 multipart/alternative MIME part are preferred by the user, in order to
 178 override the default preference order.  Thus, when viewed by
 179 .BR mhlist ,
 180 the ordering of multipart/alternative parts will appear to change when
 181 invoked with or without various
 182 .B \-prefer
 183 switches.
 184 The
 185 .B \-prefer
 186 switch is functionally most important for
 187 .IR mhshow ,
 188 but is also implemented in
 189 .B mhlist
 190 and
 191 .B mhstore
 192 to make common part numbering possible across all three programs.
 193 .SS "Checking the Contents"
 194 The
 195 .B \-check
 196 switch tells
 197 .B mhlist
 198 to check each content for an integrity checksum.  If a content has
 199 such a checksum (specified as a Content-MD5 header field), then
 200 .B mhlist
 201 will attempt to verify the integrity of the content.
 202 .SH FILES
 203 .fc ^ ~
 204 .nf
 205 .ta \w'%nmhetcdir%/ExtraBigFileName  'u
 206 ^$HOME/.mh_profile~^The user profile
 207 .fi
 208 .SH "PROFILE COMPONENTS"
 209 .fc ^ ~
 210 .nf
 211 .ta 2.4i
 212 .ta \w'ExtraBigProfileName  'u
 213 ^Path:~^To determine the user's nmh directory
 214 ^Current\-Folder:~^To find the default current folder
 215 .fi
 216 .SH "SEE ALSO"
 217 .IR mhbuild (1),
 218 .IR mhshow (1),
 219 .IR mhstore (1)
 220 .SH DEFAULTS
 221 .nf
 222 .RB ` +folder "' defaults to the current folder"
 223 .RB ` msgs "' defaults to cur"
 224 .RB ` \-nocheck '
 225 .RB ` \-headers '
 226 .RB ` \-realsize '
 227 .RB ` \-rcache\ ask '
 228 .RB ` \-wcache\ ask '
 229 .RB ` \-changecur '
 230 .RB ` \-noverbose '
 231 .RB ` \-nodisposition '
 232 .fi
 233 .SH CONTEXT
 234 If a folder is given, it will become the current folder.  The last
 235 message selected will become the current message, unless the
 236 .B \-nochangecur
 237 option is specified.