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