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