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