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