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