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