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