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