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