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