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