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