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

   1 .TH MHLIST %manext1% "August 20, 2014" "%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 .RI [ +folder ]
  12 .RI [ msgs ]
  13 .RB [ \-file
  14 .IR file ]
  15 .RB [ \-part
  16 .IR number ]
  17 \&...
  18 .RB [ \-type
  19 .IR content ]
  20 \&...
  21 .RB [ \-prefer
  22 .IR content ]
  23 \&...
  24 .RB [ \-headers " | " \-noheaders ]
  25 .RB [ \-realsize " | " \-norealsize ]
  26 .RB [ \-rcache
  27 .IR policy ]
  28 .RB [ \-wcache
  29 .IR policy ]
  30 .RB [ \-check " | " \-nocheck ]
  31 .RB [ \-changecur " | " \-nochangecur ]
  32 .RB [ \-verbose " | " \-noverbose ]
  33 .RB [ \-disposition " | " \-nodisposition ]
  34 .RB [ \-version ]
  35 .RB [ \-help ]
  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 .B \-part
 102 and
 103 .B \-type
 104 switches, you may limit the scope of this command to particular
 105 subparts (of a multipart content) and/or particular content types.
 106 .PP
 107 A part specification consists of a series of numbers separated by dots.
 108 For example, in a multipart content containing three parts, these
 109 would be named as 1, 2, and 3, respectively.  If part 2 was also a
 110 multipart content containing two parts, these would be named as 2.1 and
 111 2.2, respectively.  Note that the
 112 .B \-part
 113 switch is effective for only
 114 messages containing a multipart content.  If a message has some other
 115 kind of content, or if the part is itself another multipart content, the
 116 .B \-part
 117 switch will not prevent the content from being acted upon.
 118 .PP
 119 A content specification consists of a content type and a subtype.
 120 The initial list of \*(lqstandard\*(rq content types and subtypes can
 121 be found in RFC 2046.
 122 .PP
 123 A list of commonly used contents is briefly reproduced here:
 124 .PP
 125 .RS 5
 126 .nf
 127 .ta \w'application  'u
 128 Type    Subtypes
 129 ----    --------
 130 text    plain, enriched
 131 multipart       mixed, alternative, digest, parallel
 132 message rfc822, partial, external-body
 133 application     octet-stream, postscript
 134 image   jpeg, gif, png
 135 audio   basic
 136 video   mpeg
 137 .fi
 138 .RE
 139 .PP
 140 A legal MIME message must contain a subtype specification.
 141 .PP
 142 To specify a content, regardless of its subtype, just use the
 143 name of the content, e.g., \*(lqaudio\*(rq.  To specify a specific
 144 subtype, separate the two with a slash, e.g., \*(lqaudio/basic\*(rq.
 145 Note that regardless of the values given to the
 146 .B \-type
 147 switch, a
 148 multipart content (of any subtype listed above) is always acted upon.
 149 Further note that if the
 150 .B \-type
 151 switch is used, and it is desirable to
 152 act on a message/external-body content, then the
 153 .B \-type
 154 switch must
 155 be used twice: once for message/external-body and once for the content
 156 externally referenced.
 157 .PP
 158 By default, the parts of a multipart/alternative part are listed in
 159 the reverse order of their placement in the message.  The listing
 160 therefore is in decreasing order of preference, as defined in RFC
 161 2046.  The
 162 .B \-prefer
 163 switch can be used (one or more times, in order of descending
 164 preference) to let MH know which content types from a
 165 multipart/alternative MIME part are preferred by the user, in order to
 166 override the default preference order.  Thus, when viewed by
 167 .BR mhlist ,
 168 the ordering of multipart/alternative parts will appear to change when
 169 invoked with or without various
 170 .B \-prefer
 171 switches.
 172 The
 173 .B \-prefer
 174 switch is functionally most important for
 175 .IR mhshow ,
 176 but is also implemented in
 177 .B mhlist
 178 and
 179 .B mhstore
 180 to make common part number ordering possible across all three programs.
 181 .SS "Checking the Contents"
 182 The
 183 .B \-check
 184 switch tells
 185 .B mhlist
 186 to check each content for an
 187 integrity checksum.  If a content has such a checksum (specified as a
 188 Content-MD5 header field), then
 189 .B mhlist
 190 will attempt to verify the
 191 integrity of the content.
 192 .SH FILES
 193 .fc ^ ~
 194 .nf
 195 .ta \w'%nmhetcdir%/ExtraBigFileName  'u
 196 ^$HOME/\&.mh\(ruprofile~^The user profile
 197 .fi
 198 .SH "PROFILE COMPONENTS"
 199 .fc ^ ~
 200 .nf
 201 .ta 2.4i
 202 .ta \w'ExtraBigProfileName  'u
 203 ^Path:~^To determine the user's nmh directory
 204 ^Current\-Folder:~^To find the default current folder
 205 .fi
 206 .SH "SEE ALSO"
 207 .IR mhbuild (1),
 208 .IR mhshow (1),
 209 .IR mhstore (1)
 210 .SH DEFAULTS
 211 .nf
 212 .RB ` +folder "' defaults to the current folder"
 213 .RB ` msgs "' defaults to cur"
 214 .RB ` \-nocheck '
 215 .RB ` \-headers '
 216 .RB ` \-realsize '
 217 .RB ` \-rcache\ ask '
 218 .RB ` \-wcache\ ask '
 219 .RB ` \-changecur '
 220 .RB ` \-noverbose '
 221 .RB ` \-nodisposition '
 222 .fi
 223 .SH CONTEXT
 224 If a folder is given, it will become the current folder.  The last
 225 message selected will become the current message, unless the
 226 .B \-nochangecur
 227 option is specified.