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