docs/mimedecode.rst

   1 Name
   2 ----
   3
   4 mimedecode -- decode MIME message
   5
   6 Synopsis
   7 --------
   8
   9 mimedecode [ -h|--help ] [ -V|--version ] [ -cCDP ] [ -f charset ]
  10 [ -H|--host=hostname ] [ -d header1[,header2,header3...] ]
  11 [ -d \*[,-header1,-header2,-header3...] ]
  12 [ -p header1[,header2,header3,...]:param1[,param2,param3,...] ]
  13 [ -p \*[,-header1,-header2,-header3,...]:param1[,param2,param3,...] ]
  14 [ -p header1[,header2,header3,...]:\*[,-param1,-param2,-param3,...] ]
  15 [ -p \*[,-header1,-header2,-header3,...]:\*[,-param1,-param2,-param3,...] ]
  16 [ -r header1[,header2,header3...] ] [ -r \*[,-header1,-header2,-header3...] ]
  17 [ -R header1[,header2,header3,...]:param1[,param2,param3,...] ]
  18 [ -R \*[,-header1,-header2,-header3,...]:param1[,param2,param3,...] ]
  19 [ -R header1[,header2,header3,...]:\*[,-param1,-param2,-param3,...] ]
  20 [ -R \*[,-header1,-header2,-header3,...]:\*[,-param1,-param2,-param3,...] ]
  21 [ --set-header header:value ] [ --set-param header:param=value ]
  22 [ -BbeIit mask ] [ --save-headers|body|message mask ] [ -O dest_dir ]
  23 [ -o output_file ] [input_file [output_file] ]
  24
  25 DESCRIPTION
  26 -----------
  27
  28 Mail users, especially in non-English countries, often find that mail
  29 messages arrived in different formats, with different content types, in
  30 different encodings and charsets. Usually it is good because it allows to
  31 use an appropriate format/encoding/whatever. Sometimes, though, some
  32 unification is desirable. For example, one may want to put mail messages
  33 into an archive, make HTML indices, run search indexer, etc. In such
  34 situations converting messages to text in one character set and skipping
  35 some binary attachments is much desirable.
  36
  37 Here is a solution - mimedecode!
  38
  39 This is a program to decode MIME messages. The program expects one input
  40 file (either on command line or on stdin) which is treated as an RFC822
  41 message, and decodes to stdout or an output file. If the file is not an
  42 RFC822 message it is just copied to the output one-to-one. If the file is
  43 a simple RFC822 message it is decoded as one part. If it is a MIME message
  44 with multiple parts ("attachments") all non-multipart subparts are
  45 decoded. Decoding can be controlled by the command-line options.
  46
  47 First, for every part the program removes headers and parameters listed
  48 with -r and -R options. Then, Subject and Content-Disposition headers (and
  49 all headers listed with -d and -p options) are examined. If any of those
  50 exists, they are decoded according to RFC2047. Content-Disposition header
  51 is not decoded (if it was not listed in option -d) - only its "filename"
  52 parameter. Encoded header parameters violate the RFC, but widely deployed
  53 anyway by ignorant coders who never even heard about RFCs. Correct
  54 parameter encoding specified by RFC2231. This program decodes
  55 RFC2231-encoded parameters, too.
  56
  57 Then the body of the message (or the current part) is decoded. Decoding
  58 starts with looking at header Content-Transfer-Encoding. If the header
  59 specifies non-8bit encoding (usually base64 or quoted-printable), the body
  60 is converted to 8bit (can be prevented with -B). Then if its content type
  61 is multipart (multipart/related or multipart/mixed, e.g) every part is
  62 recursively decoded. If it is not multipart, mailcap database is consulted
  63 to find a way to convert the body to plain text (can be prevented with
  64 options -Bbei). (The author has no idea how mailcap can be configured on
  65 OSes other than POSIX, please don't ask; users can consult an example at
  66 https://phdru.name/Software/dotfiles/mailcap.html). The decoding process
  67 uses the first copiousoutput filter it can find. If there are no filters
  68 the body just passed as is.
  69
  70 Then Content-Type header is consulted for charset. If it is not equal to
  71 the current locale charset and recoding is allowed (see options -Cc) the
  72 body text is recoded. Finally message headers and the body are flushed to
  73 stdout.
  74
  75 Please be reminded that in the following options asterisk is a shell
  76 metacharacter and should be escaped or quoted. Either write -d \*,-h1,-h2
  77 or -d '\*,-h1,-h2' or such.
  78
  79 OPTIONS
  80 -------
  81
  82 -h, -help
  83
  84        Print brief usage help and exit.
  85
  86 -V, --version
  87
  88        Print version and exit.
  89
  90 -c
  91
  92        Recode different character sets in message bodies to the current
  93        default charset; this is the default.
  94
  95 -C
  96
  97        Do not recode character sets in message bodies.
  98
  99 -f charset
 100
 101        Force this charset to be used for recoding instead of charset from
 102        the current locale.
 103
 104 -H hostname, --host=hostname
 105
 106        Use this hostname in X-MIME-Autoconverted headers instead of the
 107        current hostname.
 108
 109 -d header1[,header2,header3...]
 110
 111        Add the header(s) to a list of headers to decode; initially the
 112        list contains headers "From", "To", "Cc", "Reply-To",
 113        "Mail-Followup-To" and "Subject".
 114
 115 -d \*[,-header1,-header2,-header3...]
 116
 117        This variant completely changes headers decoding. First, the list
 118        of headers to decode is cleared (as with -D). Then all the headers
 119        are decoded except the given list of exceptions (headers listed
 120        with '-'). In this mode it would be meaningless to give more than
 121        one -d options but the program doesn't enforce the limitation.
 122
 123 -D
 124
 125        Clear the list of headers to decode (make it empty).
 126
 127 -p header1[,header2,header3,...]:param1[,param2,param3,...]
 128
 129        Add the parameter(s) to a list of headers parameters to decode;
 130        the parameter(s) will be decoded only for the given header(s).
 131        Initially the list contains header "Content-Type", parameter
 132        "name"; and header "Content-Disposition", parameter "filename".
 133
 134 -p \*[,-header1,-header2,-header3,...]:param1[,param2,param3,...]
 135
 136        Add the parameter(s) to a list of headers parameters to decode;
 137        the parameter(s) will be decoded for all headers except the given
 138        ones.
 139
 140 -p header1[,header2,header3,...]:\*[,-param1,-param2,-param3,...]
 141
 142        Decode all parameters except listed for the given list of headers.
 143
 144 -p \*[,-header1,-header2,-header3,...]:\*[,-param1,-param2,-param3,...]
 145
 146        Decode all parameters except listed for all headers (except
 147        listed).
 148
 149 -P
 150
 151        Clear the list of headers parameters to decode (make it empty).
 152
 153 -r header1[,header2,header3...]
 154
 155        Add the header(s) to a list of headers to remove completely;
 156        initially the list is empty.
 157
 158 -r \*[,-header1,-header2,-header3...]
 159
 160        Remove all headers except listed.
 161
 162 -R header1[,header2,header3,...]:param1[,param2,param3,...]
 163
 164        Add the parameter(s) to a list of headers parameters to remove;
 165        the parameter(s) will be removed only for the given header(s).
 166        Initially the list is empty.
 167
 168 -R \*[,-header1,-header2,-header3,...]:param1[,param2,param3,...]
 169
 170 -R header1[,header2,header3,...]:\*[,-param1,-param2,-param3,...]
 171
 172 -R \*[,-header1,-header2,-header3,...]:\*[,-param1,-param2,-param3,...]
 173
 174        Remove listed parameters (or all parameters except listed) from
 175        these headers (or from all headers except listed).
 176
 177 --set-header header:value
 178
 179        The program sets or changes value for the header to the given
 180        value (only at the top-level message).
 181
 182 --set-param header:param=value
 183
 184        The program sets or changes value for the header's parameter to
 185        the given value (only at the top-level message). The header must
 186        exist.
 187
 188 -B mask
 189
 190        Append mask to the list of binary content types that will be not
 191        content-transfer-decoded (will be left as base64 or such).
 192
 193 -b mask
 194
 195        Append mask to the list of binary content types; if the message to
 196        decode has a part of this type the program
 197        content-transfer-decodes (base64 or whatever to 8bit binary) it
 198        and outputs the decoded part as is, without any further
 199        processing.
 200
 201 -e mask
 202
 203        Append mask to the list of error content types; if the message to
 204        decode has a part of this type the program fails with ValueError.
 205
 206 -I mask
 207
 208        Append mask to the list of content types to completely ignore.
 209        There will be no output - no headers, no body, no warning. For a
 210        multipart part the entire subtree is removed.
 211
 212 -i mask
 213
 214        Append mask to the list of content types to ignore; if the message
 215        to decode has a part of this type the program outputs headers but
 216        skips the body. Instead a line "Message body of type %s skipped."
 217        will be issued.
 218
 219 -t mask
 220
 221        Append mask to the list of content types to convert to text; if
 222        the message to decode has a part of this type the program consults
 223        mailcap database, find the first copiousoutput filter and, if any
 224        filter is found, converts the part.
 225
 226 --save-headers mask
 227
 228 --save-body mask
 229
 230 --save-message mask
 231
 232        Append mask to lists of content types to save to files;
 233        --save-headers saves only decoded headers of the message (or the
 234        current subpart); --save-body saves only decoded body;
 235        --save-message saves the entire message or subpart (headers +
 236        body).
 237
 238 -O dest_dir
 239
 240        Set destination directory for the output files; if the directory
 241        doesn't exist it will be created. Default is the current
 242        directory.
 243
 244 -o output_file
 245
 246        Save output to the file related to the destination directory from
 247        option -O. Also useful in case of redirected stdin:
 248
 249 mimedecode -o output_file < input_file
 250 cat input_file | mimedecode -o output_file
 251
 252 The 5 list options (-Bbeit) require more explanation. They allow a user to
 253 control body decoding with great flexibility. Think about said mail
 254 archive; for example, its maintainer wants to put there only texts,
 255 convert PDF/Postscript to text, pass HTML and images decoding base64 to
 256 html but leaving images encoded, and ignore everything else. This is how
 257 it could be done:
 258
 259 mimedecode -t application/pdf -t application/postscript -t text/plain -b
 260 text/html -B 'image/\*' -i '\*/\*'
 261
 262 When the program decodes a message (non-MIME or a non-multipart subpart of
 263 a MIME message), it consults Content-Type header. The content type is
 264 searched in all 5 lists, in order "text-binary-ignore-error". If found,
 265 appropriate action is performed. If not found, the program searches the
 266 same lists for "type/\*" mask (the type of "text/html" is just "text"). If
 267 found, appropriate action is performed. If not found, the program searches
 268 the same lists for "\*/\*" mask. If found, appropriate action is performed.
 269 If not found, the program uses the default action, which is to decode
 270 everything to text (if mailcap specifies a filter). This algorithm allows
 271 more specific content types to override less specific: -b image/\* will be
 272 processed earlier than -B \*/\*.
 273
 274 Options -e/-I/-i can also work with multipart subparts of a MIME message.
 275 In case of -I/-i the entire subtree of that multipart is removed; with -i
 276 it's replaced with ignore warning.
 277
 278 Initially all 5 lists are empty, so without any additional parameters the
 279 program always uses the default decoding (as -t \*/\*).
 280
 281 The 3 save options (--save-headers/body/message) are similar. They make
 282 the program to save every non-multipart subpart (only headers, or body, or
 283 the entire subpart: headers + body) that corresponds to the given mask to
 284 a file. Before saving the message (or the subpart) is decoded according to
 285 all other options and is placed to the output stream as usual. Filename
 286 for the file is created using "filename" parameter from the
 287 Content-Disposition header, or "name" parameter from the Content-Type
 288 header if one of those exist; a serial counter is prepended to the
 289 filename to avoid collisions; if there are no name/filename parameters, or
 290 the name/filename parameters contain forbidden characters (null, slash,
 291 backslash) the filename is just the serial counter.
 292
 293 If the file doesn't have any extensions (no dots in the value of the
 294 name/filename parameters, or the name is just the counter) the program
 295 tries to guess an extension by looking up the content type in mime.types
 296 files including .mime.types file in the user's home directory (if it
 297 exists). If the file has an extension the program doesn't try to verify
 298 that it corresponds to the content type.
 299
 300 The file is saved in the directory set with -O (default is the current
 301 directory). The save options are proceeded before -e options so the user
 302 can save the message that causes an error.
 303
 304 ENVIRONMENT
 305 -----------
 306
 307 LANG
 308
 309 LC_ALL
 310
 311 LC_CTYPE
 312
 313 Define current locale settings. Used to determine current default charset
 314 (if your Python is properly installed and configured).
 315
 316 BUGS
 317 ----
 318
 319 The program may produce incorrect MIME message. The purpose of the program
 320 is to decode whatever it is possible to decode, not to produce absolutely
 321 correct MIME output. The incorrect parts are obvious - decoded
 322 From/To/Cc/Reply-To/Mail-Followup-To/Subject headers and filenames. Other
 323 than that output is correct MIME message. The program does not try to
 324 guess whether the headers are correct. For example, if a message header
 325 states that charset is iso8859-1, but the body (HTML, for example) is
 326 actually in utf-8 the program will recode the message with the wrong
 327 charset.
 328
 329 AUTHOR
 330 ------
 331
 332 Oleg Broytman <phd@phdru.name>
 333
 334 COPYRIGHT
 335 ---------
 336
 337 Copyright (C) 2001-2020 PhiloSoft Design.
 338
 339 LICENSE
 340 -------
 341
 342 GNU GPL
 343
 344 NO WARRANTIES
 345 -------------
 346
 347 This program is distributed in the hope that it will be useful, but
 348 WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 349 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
 350 for more details.
 351
 352 SEE ALSO
 353 --------
 354
 355 mimedecode home page: https://phdru.name/Software/Python/#mimedecode