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>-H|--host=hostname</option>
  46       </arg>
  47       <arg choice="opt">
  48          <option>-f charset</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    It is a program to decode MIME messages. The program expects one input file
  88 (either on the command line or on stdin) which is treated as an RFC822 message,
  89 and decoded to stdout. If the file is not an RFC822 message it is just piped to
  90 stdout as is. If the file is a simple RFC822 message it is just decoded as one
  91 part. If it is a MIME message with multiple parts ("attachments") all parts are
  92 decoded recursively. Decoding can be controlled by the command-line options.
  93 </para>
  94
  95 <para>
  96    First, Subject and Content-Disposition headers are examined. If any of those
  97 exists, it is decoded according to RFC2047. Content-Disposition header is not
  98 decoded - only its "filename" parameter. Encoded header parameters violate
  99 the RFC, but widely deployed anyway, especially in the M$ Ophice GUI (often
 100 referred as "Windoze") world, where programmers are often ignorant lamers who
 101 never even heard about RFCs. Correct parameter encoding specified by RFC2231.
 102 This 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 or
 110 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 to
 112 plain text. (I have no idea how mailcap could be configured on said M$ Ophice
 113 GUI, 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 first copiousoutput filter it can find. If there is
 116 no any filter the body just passed unconverted.
 117 </para>
 118
 119 <para>
 120    Then Content-Type header consulted for charset. If it is not equal to
 121 current default charset the body text recoded. Finally message headers and body
 122 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 body to current default
 155             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 body.
 165          </para>
 166       </listitem>
 167    </varlistentry>
 168
 169    <varlistentry>
 170       <term>-H hostname</term>
 171       <term>--host=hostname</term>
 172       <listitem>
 173          <para>
 174            Use this hostname in X-MIME-Autoconverted headers instead of the
 175            current hostname.
 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>-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" and "Subject".
 196          </para>
 197       </listitem>
 198    </varlistentry>
 199
 200    <varlistentry>
 201       <term>-D</term>
 202       <listitem>
 203          <para>
 204             Clear the list of headers to decode (make it empty).
 205          </para>
 206       </listitem>
 207    </varlistentry>
 208
 209    <varlistentry>
 210       <term>-p header:param</term>
 211       <listitem>
 212          <para>
 213             Add the (header, param) pair to a list of headers' parameters to
 214             decode; initially the list contains header "Content-Disposition",
 215             parameter "filename".
 216          </para>
 217       </listitem>
 218    </varlistentry>
 219
 220    <varlistentry>
 221       <term>-P</term>
 222       <listitem>
 223          <para>
 224             Clear the list of headers' parameters to decode (make it empty).
 225          </para>
 226       </listitem>
 227    </varlistentry>
 228
 229    <varlistentry>
 230       <term>-b mask</term>
 231       <listitem>
 232          <para>
 233             Append mask to the list of binary content types; if the message to
 234             decode has a part of this type the program will pass the part as is,
 235             without any additional processing.
 236          </para>
 237       </listitem>
 238    </varlistentry>
 239
 240    <varlistentry>
 241       <term>-e mask</term>
 242       <listitem>
 243          <para>
 244             Append mask to the list of error content types; if the message to
 245             decode has a part of this type the program fails with ValueError.
 246          </para>
 247       </listitem>
 248    </varlistentry>
 249
 250    <varlistentry>
 251       <term>-i mask</term>
 252       <listitem>
 253          <para>
 254             Append mask to the list of content types to ignore; if the message to
 255             decode has a part of this type the program will not pass it, instead
 256             a line "Message body of type `%s' skipped." will be issued.
 257          </para>
 258       </listitem>
 259    </varlistentry>
 260
 261    <varlistentry>
 262       <term>-t mask</term>
 263       <listitem>
 264          <para>
 265             Append mask to the list of content types to convert to text; if the
 266             message to decode has a part of this type the program will consult
 267             mailcap database, find first copiousoutput filter and convert the
 268             part.
 269          </para>
 270       </listitem>
 271    </varlistentry>
 272
 273    <varlistentry>
 274       <term>-o output_file</term>
 275       <listitem>
 276          <para>
 277             Useful to set the output file in case of redirected stdin:
 278             <programlisting language="sh">mimedecode.py -o output_file &lt; input_file
 279 cat input_file | mimedecode.py -o output_file</programlisting>
 280          </para>
 281       </listitem>
 282    </varlistentry>
 283 </variablelist>
 284
 285 <para>
 286    The 4 list options (-beit) require more explanation. They allow a user
 287 to control body decoding with great flexibility. Think about said mail
 288 archive; for example, its maintainer wants to put there only texts, convert
 289 Postscript/PDF to text, pass HTML and images as is, and ignore everything
 290 else. Easy:
 291 </para>
 292
 293 <para>
 294 <code language="sh">
 295    mimedecode.py -t application/postscript -t application/pdf -b text/html
 296          -b 'image/*' -i '*/*'
 297 </code>
 298 </para>
 299
 300 <para>
 301    When the program decodes a message (or its part), it consults
 302 Content-Type header. The content type is searched in all 4 lists, in order
 303 "text-binary-ignore-error". If found, appropriate action performed. If not
 304 found, the program search the same lists for "type/*" mask (the type of
 305 "text/html" is just "text"). If found, appropriate action performed. If not
 306 found, the program search the same lists for "*/*" mask. If found,
 307 appropriate action performed. If not found, the program uses default
 308 action, which is to decode everything to text (if mailcap specifies
 309 a filter).
 310 </para>
 311
 312 <para>
 313    Initially all 4 lists are empty, so without any additional parameters
 314 the program always uses the default decoding.
 315 </para>
 316 </refsect1>
 317
 318
 319 <refsect1>
 320 <title>ENVIRONMENT</title>
 321 <variablelist>
 322   <varlistentry><term>LANG</term></varlistentry>
 323   <varlistentry><term>LC_ALL</term></varlistentry>
 324   <varlistentry><term>LC_CTYPE</term></varlistentry>
 325 </variablelist>
 326 <para>
 327   Define current locale settings. Used to determine current default charset (if
 328   your Python is properly installed and configured).
 329 </para>
 330 </refsect1>
 331
 332
 333 <refsect1>
 334 <title>BUGS</title>
 335 <para>
 336    The program may produce incorrect MIME message. The purpose of the program
 337 is to decode whatever it is possible to decode, not to produce absolutely
 338 correct MIME output. The incorrect parts are obvious - decoded Subject headers
 339 and filenames. Other than that output is correct MIME message. The program does
 340 not try to guess whether the headers are correct. For example, if a message
 341 header states that charset is iso8859-5, but the body is actually in koi8-r -
 342 the program will recode the message with the wrong charset.
 343 </para>
 344 </refsect1>
 345
 346
 347 <refsect1>
 348 <title>AUTHOR</title>
 349 <para>
 350   <firstname>Oleg</firstname>
 351   <surname>Broytman</surname>
 352   <email>phd@phdru.name</email>
 353 </para>
 354 </refsect1>
 355
 356
 357 <refsect1>
 358 <title>COPYRIGHT</title>
 359 <para>
 360   Copyright (C) 2001-2014 PhiloSoft Design.
 361 </para>
 362 </refsect1>
 363
 364
 365 <refsect1>
 366 <title>LICENSE</title>
 367 <para>
 368    GNU GPL
 369 </para>
 370 </refsect1>
 371
 372
 373 <refsect1>
 374 <title>NO WARRANTIES</title>
 375 <para>
 376    This program is distributed in the hope that it will be useful, but WITHOUT
 377    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 378    FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
 379    more details.
 380 </para>
 381 </refsect1>
 382
 383
 384 <refsect1>
 385 <title>SEE ALSO</title>
 386 <para>
 387   mimedecode.py home page:
 388   <ulink url="http://phdru.name/Software/Python/#mimedecode">http://phdru.name/Software/Python/#mimedecode</ulink>
 389 </para>
 390 </refsect1>
 391
 392 </refentry>