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