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