mimedecode.docbook

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