mimedecode.docbook

   1 <?xml version="1.0" standalone="no"?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "file:///usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd">
   4
   5 <refentry id="mimedecode.py">
   6
   7 <refentryinfo>
   8   <title>mimedecode.py</title>
   9   <productname>mimedecode.docbook</productname>
  10   <author>
  11     <firstname>Oleg</firstname>
  12     <surname>Broytman</surname>
  13     <email>phd@phdru.name</email>
  14     <personblurb/>
  15   </author>
  16   <copyright>
  17     <year>2001-2014</year>
  18     <holder>PhiloSoft Design.</holder>
  19   </copyright>
  20 </refentryinfo>
  21
  22 <refmeta>
  23    <refentrytitle>mimedecode.py</refentrytitle>
  24    <manvolnum>1</manvolnum>
  25 </refmeta>
  26
  27 <refnamediv>
  28    <refname>mimedecode.py</refname>
  29    <refpurpose>decode MIME message</refpurpose>
  30 </refnamediv>
  31
  32 <refsynopsisdiv>
  33    <cmdsynopsis>
  34       <command>mimedecode.py</command>
  35       <arg choice="opt">
  36          <option>-h|--help</option>
  37       </arg>
  38       <arg choice="opt">
  39          <option>-V|--version</option>
  40       </arg>
  41       <arg choice="opt">
  42          <option>-cCDP</option>
  43       </arg>
  44       <arg choice="opt">
  45          <option>-f charset</option>
  46       </arg>
  47       <arg choice="opt">
  48          <option>-H|--host=hostname</option>
  49       </arg>
  50       <arg choice="opt">
  51          <option>-d header1[,header2,header3...]</option>
  52       </arg>
  53       <arg choice="opt">
  54          <option>-d *[,-header1,-header2,-header3...]</option>
  55       </arg>
  56       <arg choice="opt">
  57         <option>-p header1[,header2,header3,...]:param1[,param2,param3,...]</option>
  58       </arg>
  59       <arg choice="opt">
  60         <option>-p *[,-header1,-header2,-header3,...]:param1[,param2,param3,...]</option>
  61       </arg>
  62       <arg choice="opt">
  63         <option>-p header1[,header2,header3,...]:*[,-param1,-param2,-param3,...]</option>
  64       </arg>
  65       <arg choice="opt">
  66         <option>-p *[,-header1,-header2,-header3,...]:*[,-param1,-param2,-param3,...]</option>
  67       </arg>
  68       <arg choice="opt">
  69          <option>-r header1[,header2,header3...]</option>
  70       </arg>
  71       <arg choice="opt">
  72          <option>-r *[,-header1,-header2,-header3...]</option>
  73       </arg>
  74       <arg choice="opt">
  75         <option>-R header1[,header2,header3,...]:param1[,param2,param3,...]</option>
  76       </arg>
  77       <arg choice="opt">
  78         <option>-R *[,-header1,-header2,-header3,...]:param1[,param2,param3,...]</option>
  79       </arg>
  80       <arg choice="opt">
  81         <option>-R header1[,header2,header3,...]:*[,-param1,-param2,-param3,...]</option>
  82       </arg>
  83       <arg choice="opt">
  84         <option>-R *[,-header1,-header2,-header3,...]:*[,-param1,-param2,-param3,...]</option>
  85       </arg>
  86       <arg choice="opt">
  87          <option>--set-header header:value</option>
  88       </arg>
  89       <arg choice="opt">
  90          <option>-beit mask</option>
  91       </arg>
  92       <arg choice="opt">
  93          <option>-o output_file</option>
  94       </arg>
  95       <arg choice="opt">input_file
  96         <arg choice="opt">output_file</arg>
  97       </arg>
  98    </cmdsynopsis>
  99 </refsynopsisdiv>
 100
 101
 102 <refsect1>
 103 <title>DESCRIPTION</title>
 104 <para>
 105    Mail users, especially in non-English countries, often find that mail
 106    messages arrived in different formats, with different content types, in
 107    different encodings and charsets. Usually it is good because it allows to
 108    use an appropriate format/encoding/whatever. Sometimes, though, some
 109    unification is desirable. For example, one may want to put mail messages
 110    into an archive, make HTML indices, run search indexer, etc. In such
 111    situations converting messages to text in one character set and skipping
 112    some binary attachments is much desirable.
 113 </para>
 114
 115 <para>
 116    Here is the solution - mimedecode.py!
 117 </para>
 118
 119 <para>
 120    This is a program to decode MIME messages. The program expects one input
 121    file (either on command line or on stdin) which is treated as an RFC822
 122    message, and decodes to stdout or an output file. If the file is not an
 123    RFC822 message it is just copied to the output one-to-one. If the file is a
 124    simple RFC822 message it is decoded as one part. If it is a MIME message
 125    with multiple parts ("attachments") all parts are decoded. Decoding can be
 126    controlled by command-line options.
 127 </para>
 128
 129 <para>
 130    First, for every part the program removes headers and parameters listed with
 131    -r and -R options. Then, Subject and Content-Disposition headers (and all
 132    headers listed with -d and -p options) are examined. If any of those exists,
 133    they are decoded according to RFC2047. Content-Disposition header is not
 134    decoded - only its "filename" parameter. Encoded header parameters violate
 135    the RFC, but widely deployed anyway by ignorant coders who never even heard
 136    about RFCs. Correct parameter encoding specified by RFC2231. This program
 137    decodes RFC2231-encoded parameters, too.
 138 </para>
 139
 140 <para>
 141    Then the body of the message (or the current part) is decoded. Decoding
 142    starts with looking at header Content-Transfer-Encoding. If the header
 143    specifies non-8bit encoding (usually base64 or quoted-printable), the body
 144    converted to 8bit. Then, if its content type is multipart (multipart/related
 145    or multipart/mixed, e.g) every part is recursively decoded. If it is not
 146    multipart, mailcap database is consulted to find a way to convert the body
 147    to plain text. (I have no idea how mailcap can be configured on OSes other
 148    than POSIX, please don't ask me; real OS users can consult my example at
 149    <ulink url="http://phdru.name/Software/dotfiles/mailcap.html">http://phdru.name/Software/dotfiles/mailcap.html</ulink>).
 150    The decoding process uses the first copiousoutput filter it can find. If
 151    there are no filters the body just passed as is.
 152 </para>
 153
 154 <para>
 155    Then Content-Type header is consulted for charset. If it is not equal to the
 156    current locale charset and recoding is allowed the body text is recoded.
 157    Finally message headers and the body are flushed to stdout.
 158 </para>
 159 </refsect1>
 160
 161 <refsect1>
 162   <para>
 163     Please be warned that in the following options asterisk is a shell
 164     metacharacter and should be escaped or quoted. Either write -d \*,-h1,-h2
 165     or -d '*,-h1,-h2' or such.
 166   </para>
 167 </refsect1>
 168
 169 <refsect1>
 170 <title>OPTIONS</title>
 171 <variablelist>
 172    <varlistentry>
 173       <term>-h</term>
 174       <term>-help</term>
 175       <listitem>
 176          <para>
 177             Print brief usage help and exit.
 178          </para>
 179       </listitem>
 180    </varlistentry>
 181
 182    <varlistentry>
 183       <term>-V</term>
 184       <term>--version</term>
 185       <listitem>
 186          <para>
 187             Print version and exit.
 188          </para>
 189       </listitem>
 190    </varlistentry>
 191
 192    <varlistentry>
 193       <term>-c</term>
 194       <listitem>
 195          <para>
 196             Recode different character sets in message bodies to the current
 197             default charset; this is the default.
 198          </para>
 199       </listitem>
 200    </varlistentry>
 201
 202    <varlistentry>
 203       <term>-C</term>
 204       <listitem>
 205          <para>
 206             Do not recode character sets in message bodies.
 207          </para>
 208       </listitem>
 209    </varlistentry>
 210
 211    <varlistentry>
 212       <term>-f charset</term>
 213       <listitem>
 214          <para>
 215             Force this charset to be the current default charset instead of
 216             the current locale.
 217          </para>
 218       </listitem>
 219    </varlistentry>
 220
 221    <varlistentry>
 222       <term>-H hostname</term>
 223       <term>--host=hostname</term>
 224       <listitem>
 225          <para>
 226            Use this hostname in X-MIME-Autoconverted headers instead of the
 227            current hostname.
 228          </para>
 229       </listitem>
 230    </varlistentry>
 231
 232    <varlistentry>
 233       <term>-d header1[,header2,header3...]</term>
 234       <listitem>
 235          <para>
 236             Add the header(s) to a list of headers to decode; initially the
 237             list contains headers "From", "To", "Cc", "Reply-To",
 238             "Mail-Followup-To" and "Subject".
 239          </para>
 240       </listitem>
 241    </varlistentry>
 242
 243    <varlistentry>
 244       <term>-d *[,-header1,-header2,-header3...]</term>
 245       <listitem>
 246          <para>
 247            This variant completely changes headers decoding. First, the list of
 248            headers to decode is cleared. Then all the headers are decoded
 249            except the given list of exceptions (headers listed with '-'). In
 250            this mode it would be meaningless to give more than one -d options
 251            but the program doesn't enforce it.
 252          </para>
 253       </listitem>
 254    </varlistentry>
 255
 256    <varlistentry>
 257       <term>-D</term>
 258       <listitem>
 259          <para>
 260             Clear the list of headers to decode (make it empty).
 261          </para>
 262       </listitem>
 263    </varlistentry>
 264
 265    <varlistentry>
 266       <term>-p header1[,header2,header3,...]:param1[,param2,param3,...]</term>
 267       <listitem>
 268          <para>
 269             Add the parameters(s) to a list of headers parameters to decode;
 270             the parameters will be decoded only for the given header(s).
 271             Initially the list contains header "Content-Type", parameter "name";
 272             and header "Content-Disposition", parameter "filename".
 273          </para>
 274       </listitem>
 275    </varlistentry>
 276
 277    <varlistentry>
 278       <term>-p *[,-header1,-header2,-header3,...]:param1[,param2,param3,...]</term>
 279       <listitem>
 280          <para>
 281             Add the parameters(s) to a list of headers parameters to decode;
 282             the parameters will be decoded for all headers except the given
 283             ones.
 284          </para>
 285       </listitem>
 286    </varlistentry>
 287
 288    <varlistentry>
 289       <term>-p header1[,header2,header3,...]:*[,-param1,-param2,-param3,...]</term>
 290       <listitem>
 291          <para>
 292            Decode all parameters except listed for the given list of headers.
 293          </para>
 294       </listitem>
 295    </varlistentry>
 296
 297    <varlistentry>
 298       <term>-p *[,-header1,-header2,-header3,...]:*[,-param1,-param2,-param3,...]</term>
 299       <listitem>
 300          <para>
 301            Decode all parameters except listed for all headers (except listed).
 302          </para>
 303       </listitem>
 304    </varlistentry>
 305
 306    <varlistentry>
 307       <term>-P</term>
 308       <listitem>
 309          <para>
 310             Clear the list of headers parameters to decode (make it empty).
 311          </para>
 312       </listitem>
 313    </varlistentry>
 314
 315    <varlistentry>
 316       <term>-r header1[,header2,header3...]</term>
 317       <listitem>
 318          <para>
 319             Add the header(s) to a list of headers to remove completely;
 320             initially the list is empty.
 321          </para>
 322       </listitem>
 323    </varlistentry>
 324
 325    <varlistentry>
 326       <term>-r *[,-header1,-header2,-header3...]</term>
 327       <listitem>
 328          <para>
 329            Remove all headers except listed.
 330          </para>
 331       </listitem>
 332    </varlistentry>
 333
 334    <varlistentry>
 335       <term>-R header1[,header2,header3,...]:param1[,param2,param3,...]</term>
 336       <listitem>
 337          <para>
 338             Add the parameters(s) to a list of headers parameters to remove;
 339             the parameters will be decoded only for the given header(s).
 340             Initially the list is empty.
 341          </para>
 342       </listitem>
 343    </varlistentry>
 344
 345    <varlistentry>
 346       <term>-R *[,-header1,-header2,-header3,...]:param1[,param2,param3,...]</term>
 347    </varlistentry>
 348
 349    <varlistentry>
 350       <term>-R header1[,header2,header3,...]:*[,-param1,-param2,-param3,...]</term>
 351    </varlistentry>
 352
 353    <varlistentry>
 354       <term>-R *[,-header1,-header2,-header3,...]:*[,-param1,-param2,-param3,...]</term>
 355       <listitem>
 356          <para>
 357            Remove listed parameters (or all parameters except listed) frome
 358            these headers (or from all headers except listed).
 359          </para>
 360       </listitem>
 361    </varlistentry>
 362
 363    <varlistentry>
 364       <term>--set-header header:value</term>
 365       <listitem>
 366          <para>
 367            The program sets or changes value for the header to the given value
 368            (only at the top-level message).
 369          </para>
 370       </listitem>
 371    </varlistentry>
 372
 373    <varlistentry>
 374       <term>-b mask</term>
 375       <listitem>
 376          <para>
 377             Append mask to the list of binary content types; if the message to
 378             decode has a part of this type the program will pass the part as is,
 379             without any additional processing.
 380          </para>
 381       </listitem>
 382    </varlistentry>
 383
 384    <varlistentry>
 385       <term>-e mask</term>
 386       <listitem>
 387          <para>
 388             Append mask to the list of error content types; if the message to
 389             decode has a part of this type the program fails with ValueError.
 390          </para>
 391       </listitem>
 392    </varlistentry>
 393
 394    <varlistentry>
 395       <term>-i mask</term>
 396       <listitem>
 397          <para>
 398             Append mask to the list of content types to ignore; if the message to
 399             decode has a part of this type the program will not pass it, instead
 400             a line "Message body of type `%s' skipped." will be issued.
 401          </para>
 402       </listitem>
 403    </varlistentry>
 404
 405    <varlistentry>
 406       <term>-t mask</term>
 407       <listitem>
 408          <para>
 409             Append mask to the list of content types to convert to text; if the
 410             message to decode has a part of this type the program will consult
 411             mailcap database, find first copiousoutput filter and convert the
 412             part.
 413          </para>
 414       </listitem>
 415    </varlistentry>
 416
 417    <varlistentry>
 418       <term>-o output_file</term>
 419       <listitem>
 420          <para>
 421             Useful to set the output file in case of redirected stdin:
 422             <programlisting language="sh">mimedecode.py -o output_file &lt; input_file
 423 cat input_file | mimedecode.py -o output_file</programlisting>
 424          </para>
 425       </listitem>
 426    </varlistentry>
 427 </variablelist>
 428
 429 <para>
 430    The 4 list options (-beit) require more explanation. They allow a user to
 431    control body decoding with great flexibility. Think about said mail archive;
 432    for example, its maintainer wants to put there only texts, convert
 433    Postscript/PDF to text, pass HTML and images as is, and ignore everything
 434    else. Easy:
 435 </para>
 436
 437 <para>
 438 <code language="sh">
 439    mimedecode.py -t application/postscript -t application/pdf -b text/html
 440          -b 'image/*' -i '*/*'
 441 </code>
 442 </para>
 443
 444 <para>
 445    When the program decodes a message (non-MIME or a non-multipart subpart of a
 446    MIME message), it consults Content-Type header. The content type is searched
 447    in all 4 lists, in order "text-binary-ignore-error". If found, appropriate
 448    action performed. If not found, the program search the same lists for
 449    "type/*" mask (the type of "text/html" is just "text"). If found,
 450    appropriate action performed. If not found, the program search the same
 451    lists for "*/*" mask. If found, appropriate action performed. If not found,
 452    the program uses default action, which is to decode everything to text (if
 453    mailcap specifies a filter).
 454 </para>
 455
 456 <para>
 457    Initially all 4 lists are empty, so without any additional parameters
 458 the program always uses the default decoding.
 459 </para>
 460 </refsect1>
 461
 462
 463 <refsect1>
 464 <title>ENVIRONMENT</title>
 465 <variablelist>
 466   <varlistentry><term>LANG</term></varlistentry>
 467   <varlistentry><term>LC_ALL</term></varlistentry>
 468   <varlistentry><term>LC_CTYPE</term></varlistentry>
 469 </variablelist>
 470 <para>
 471   Define current locale settings. Used to determine current default charset (if
 472   your Python is properly installed and configured).
 473 </para>
 474 </refsect1>
 475
 476
 477 <refsect1>
 478 <title>BUGS</title>
 479 <para>
 480    The program may produce incorrect MIME message. The purpose of the program
 481    is to decode whatever it is possible to decode, not to produce absolutely
 482    correct MIME output. The incorrect parts are obvious - decoded
 483    From/To/Cc/Reply-To/Mail-Followup-To/Subject headers and filenames. Other
 484    than that output is correct MIME message. The program does not try to guess
 485    whether the headers are correct. For example, if a message header states
 486    that charset is iso8859-5, but the body is actually in utf-8 the program
 487    will recode the message with the wrong charset.
 488 </para>
 489 </refsect1>
 490
 491
 492 <refsect1>
 493 <title>AUTHOR</title>
 494 <para>
 495   <firstname>Oleg</firstname>
 496   <surname>Broytman</surname>
 497   <email>phd@phdru.name</email>
 498 </para>
 499 </refsect1>
 500
 501
 502 <refsect1>
 503 <title>COPYRIGHT</title>
 504 <para>
 505   Copyright (C) 2001-2014 PhiloSoft Design.
 506 </para>
 507 </refsect1>
 508
 509
 510 <refsect1>
 511 <title>LICENSE</title>
 512 <para>
 513    GNU GPL
 514 </para>
 515 </refsect1>
 516
 517
 518 <refsect1>
 519 <title>NO WARRANTIES</title>
 520 <para>
 521    This program is distributed in the hope that it will be useful, but WITHOUT
 522    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 523    FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
 524    more details.
 525 </para>
 526 </refsect1>
 527
 528
 529 <refsect1>
 530 <title>SEE ALSO</title>
 531 <para>
 532   mimedecode.py home page:
 533   <ulink url="http://phdru.name/Software/Python/#mimedecode">http://phdru.name/Software/Python/#mimedecode</ulink>
 534 </para>
 535 </refsect1>
 536
 537 </refentry>