<option>-H|--host=hostname</option>
</arg>
<arg choice="opt">
- <option>-d header</option>
+ <option>-d header1[,header2,header3...]</option>
</arg>
<arg choice="opt">
- <option>-p header:param</option>
+ <option>-d *[,-header1,-header2,-header3...]</option>
</arg>
<arg choice="opt">
- <option>-beit mask</option>
+ <option>-p header1[,header2,header3,...]:param1[,param2,param3,...]</option>
+ </arg>
+ <arg choice="opt">
+ <option>-p *[,-header1,-header2,-header3,...]:param1[,param2,param3,...]</option>
+ </arg>
+ <arg choice="opt">
+ <option>-p header1[,header2,header3,...]:*[,-param1,-param2,-param3,...]</option>
+ </arg>
+ <arg choice="opt">
+ <option>-p *[,-header1,-header2,-header3,...]:*[,-param1,-param2,-param3,...]</option>
+ </arg>
+ <arg choice="opt">
+ <option>-r header1[,header2,header3...]</option>
+ </arg>
+ <arg choice="opt">
+ <option>-r *[,-header1,-header2,-header3...]</option>
+ </arg>
+ <arg choice="opt">
+ <option>-R header1[,header2,header3,...]:param1[,param2,param3,...]</option>
+ </arg>
+ <arg choice="opt">
+ <option>-R *[,-header1,-header2,-header3,...]:param1[,param2,param3,...]</option>
+ </arg>
+ <arg choice="opt">
+ <option>-R header1[,header2,header3,...]:*[,-param1,-param2,-param3,...]</option>
+ </arg>
+ <arg choice="opt">
+ <option>-R *[,-header1,-header2,-header3,...]:*[,-param1,-param2,-param3,...]</option>
+ </arg>
+ <arg choice="opt">
+ <option>--set-header header:value</option>
+ </arg>
+ <arg choice="opt">
+ <option>--set-param header:param=value</option>
+ </arg>
+ <arg choice="opt">
+ <option>-Bbeit mask</option>
+ </arg>
+ <arg choice="opt">
+ <option>--save-headers|body|message mask</option>
+ </arg>
+ <arg choice="opt">
+ <option>-O dest_dir</option>
</arg>
<arg choice="opt">
<option>-o output_file</option>
<title>DESCRIPTION</title>
<para>
Mail users, especially in non-English countries, often find that mail
-messages arrived in different formats, with different content types, in
-different encodings and charsets. Usually it is good because it allows to use
-an appropriate format/encoding/whatever. Sometimes, though, some unification is
-desirable. For example, one may want to put mail messages into an archive,
-make HTML indices, run search indexer, etc. In such situations converting
-messages to text in one character set and skipping some binary attachments is
-much desirable.
+ messages arrived in different formats, with different content types, in
+ different encodings and charsets. Usually it is good because it allows to
+ use an appropriate format/encoding/whatever. Sometimes, though, some
+ unification is desirable. For example, one may want to put mail messages
+ into an archive, make HTML indices, run search indexer, etc. In such
+ situations converting messages to text in one character set and skipping
+ some binary attachments is much desirable.
</para>
<para>
<para>
This is a program to decode MIME messages. The program expects one input
-file (either on command line or on stdin) which is treated as an RFC822
-message, and decodes to stdout or an output file. If the file is not an RFC822
-message it is just copied to the output one-to-one. If the file is a simple
-RFC822 message it is decoded as one part. If it is a MIME message with multiple
-parts ("attachments") all parts are decoded. Decoding can be controlled by
-command-line options.
+ file (either on command line or on stdin) which is treated as an RFC822
+ message, and decodes to stdout or an output file. If the file is not an
+ RFC822 message it is just copied to the output one-to-one. If the file is a
+ simple RFC822 message it is decoded as one part. If it is a MIME message
+ with multiple parts ("attachments") all parts are decoded. Decoding can be
+ controlled by command-line options.
</para>
<para>
- First, Subject and Content-Disposition headers are examined. If any of those
- exists, it is decoded according to RFC2047. Content-Disposition header is
- not decoded - only its "filename" parameter. Encoded header parameters
- violate the RFC, but widely deployed anyway by ignorant coders who never
- even heard about RFCs. Correct parameter encoding specified by RFC2231. This
- program decodes RFC2231-encoded parameters, too.
+ First, for every part the program removes headers and parameters listed with
+ -r and -R options. Then, Subject and Content-Disposition headers (and all
+ headers listed with -d and -p options) are examined. If any of those exists,
+ they are decoded according to RFC2047. Content-Disposition header is not
+ decoded - only its "filename" parameter. Encoded header parameters violate
+ the RFC, but widely deployed anyway by ignorant coders who never even heard
+ about RFCs. Correct parameter encoding specified by RFC2231. This program
+ decodes RFC2231-encoded parameters, too.
</para>
<para>
</para>
</refsect1>
+<refsect1>
+ <para>
+ Please be warned that in the following options asterisk is a shell
+ metacharacter and should be escaped or quoted. Either write -d \*,-h1,-h2
+ or -d '*,-h1,-h2' or such.
+ </para>
+</refsect1>
<refsect1>
<title>OPTIONS</title>
</varlistentry>
<varlistentry>
- <term>-d header</term>
+ <term>-d header1[,header2,header3...]</term>
+ <listitem>
+ <para>
+ Add the header(s) to a list of headers to decode; initially the
+ list contains headers "From", "To", "Cc", "Reply-To",
+ "Mail-Followup-To" and "Subject".
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-d *[,-header1,-header2,-header3...]</term>
<listitem>
<para>
- Add the header to a list of headers to decode; initially the list
- contains headers "From", "To", "Cc" and "Subject".
+ This variant completely changes headers decoding. First, the list of
+ headers to decode is cleared. Then all the headers are decoded
+ except the given list of exceptions (headers listed with '-'). In
+ this mode it would be meaningless to give more than one -d options
+ but the program doesn't enforce it.
</para>
</listitem>
</varlistentry>
</varlistentry>
<varlistentry>
- <term>-p header:param</term>
+ <term>-p header1[,header2,header3,...]:param1[,param2,param3,...]</term>
+ <listitem>
+ <para>
+ Add the parameters(s) to a list of headers parameters to decode;
+ the parameters will be decoded only for the given header(s).
+ Initially the list contains header "Content-Type", parameter "name";
+ and header "Content-Disposition", parameter "filename".
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-p *[,-header1,-header2,-header3,...]:param1[,param2,param3,...]</term>
+ <listitem>
+ <para>
+ Add the parameters(s) to a list of headers parameters to decode;
+ the parameters will be decoded for all headers except the given
+ ones.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-p header1[,header2,header3,...]:*[,-param1,-param2,-param3,...]</term>
<listitem>
<para>
- Add the pair (header, param) to a list of headers' parameters to
- decode; initially the list contains header "Content-Type",
- parameter "name" and header "Content-Disposition", parameter
- "filename".
+ Decode all parameters except listed for the given list of headers.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-p *[,-header1,-header2,-header3,...]:*[,-param1,-param2,-param3,...]</term>
+ <listitem>
+ <para>
+ Decode all parameters except listed for all headers (except listed).
</para>
</listitem>
</varlistentry>
<term>-P</term>
<listitem>
<para>
- Clear the list of headers' parameters to decode (make it empty).
+ Clear the list of headers parameters to decode (make it empty).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-r header1[,header2,header3...]</term>
+ <listitem>
+ <para>
+ Add the header(s) to a list of headers to remove completely;
+ initially the list is empty.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-r *[,-header1,-header2,-header3...]</term>
+ <listitem>
+ <para>
+ Remove all headers except listed.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-R header1[,header2,header3,...]:param1[,param2,param3,...]</term>
+ <listitem>
+ <para>
+ Add the parameters(s) to a list of headers parameters to remove;
+ the parameters will be decoded only for the given header(s).
+ Initially the list is empty.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-R *[,-header1,-header2,-header3,...]:param1[,param2,param3,...]</term>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-R header1[,header2,header3,...]:*[,-param1,-param2,-param3,...]</term>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-R *[,-header1,-header2,-header3,...]:*[,-param1,-param2,-param3,...]</term>
+ <listitem>
+ <para>
+ Remove listed parameters (or all parameters except listed) frome
+ these headers (or from all headers except listed).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>--set-header header:value</term>
+ <listitem>
+ <para>
+ The program sets or changes value for the header to the given value
+ (only at the top-level message).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>--set-param header:param=value</term>
+ <listitem>
+ <para>
+ The program sets or changes value for the header's parameter to the
+ given value (only at the top-level message). The header must exist.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-B mask</term>
+ <listitem>
+ <para>
+ Append mask to the list of binary content types that will be not
+ content-transfer-decoded (will be left as base64 or such).
</para>
</listitem>
</varlistentry>
<listitem>
<para>
Append mask to the list of binary content types; if the message to
- decode has a part of this type the program will pass the part as is,
- without any additional processing.
+ decode has a part of this type the program will
+ content-transfer-decode (base64 or whatever to 8bit binary) it but
+ pass the part as is, without any further processing.
</para>
</listitem>
</varlistentry>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term>--save-headers mask</term>
+ </varlistentry>
+
+ <varlistentry>
+ <term>--save-body mask</term>
+ </varlistentry>
+
+ <varlistentry>
+ <term>--save-message mask</term>
+ <listitem>
+ <para>
+ Append mask to a list of content types to save to a file;
+ --save-headers saves only decoded headers of the message (or
+ subpart); --save-body saves only decoded body; --save-message saves
+ the entire message or subpart (headers + body).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-O dest_dir</term>
+ <listitem>
+ <para>
+ Set destination directory for the output files; the directory must
+ exist. Default is current directory.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term>-o output_file</term>
<listitem>
<para>
- Useful to set the output file in case of redirected stdin:
+ Save output to the file related to the destination directory from
+ option -O. Also useful in case of redirected stdin:
<programlisting language="sh">mimedecode.py -o output_file < input_file
cat input_file | mimedecode.py -o output_file</programlisting>
</para>
</variablelist>
<para>
- The 4 list options (-beit) require more explanation. They allow a user
-to control body decoding with great flexibility. Think about said mail
-archive; for example, its maintainer wants to put there only texts, convert
-Postscript/PDF to text, pass HTML and images as is, and ignore everything
-else. Easy:
+ The 5 list options (-Bbeit) require more explanation. They allow a user to
+ control body decoding with great flexibility. Think about said mail archive;
+ for example, its maintainer wants to put there only texts, convert
+ PDF/Postscript to text, pass HTML and images as is (decoding base64 to html
+ but left images in base64), and ignore everything else. Easy:
</para>
<para>
<code language="sh">
- mimedecode.py -t application/postscript -t application/pdf -b text/html
- -b 'image/*' -i '*/*'
+ mimedecode.py -t application/pdf -t application/postscript -b text/html
+ -B 'image/*' -i '*/*'
</code>
</para>
<para>
When the program decodes a message (non-MIME or a non-multipart subpart of a
MIME message), it consults Content-Type header. The content type is searched
- in all 4 lists, in order "text-binary-ignore-error". If found, appropriate
+ in all 5 lists, in order "text-binary-ignore-error". If found, appropriate
action performed. If not found, the program search the same lists for
"type/*" mask (the type of "text/html" is just "text"). If found,
appropriate action performed. If not found, the program search the same
</para>
<para>
- Initially all 4 lists are empty, so without any additional parameters
+ Initially all 5 lists are empty, so without any additional parameters
the program always uses the default decoding.
</para>
+
+<para>
+ The 3 save list options (--save-headers/body/message) are similar. They make
+ the program to save every non-multipart subpart (only headers, or body, or
+ the entire subpart) that corresponds to the given mask to a file. Before
+ saving the message (or the subpart) is decoded according to all other options
+ and placed to the output stream as usual. Filename for the file is created
+ using "filename" parameter from the Content-Disposition header, or "name"
+ parameter from the Content-Type header if one of those exist; a serial
+ counter is prepended to the filename to avoid collisions; if there are no
+ name/filename parameters, the filename is just the serial counter. The file
+ is saved in the directory set with -O (default is the current directory).
+</para>
</refsect1>
The program may produce incorrect MIME message. The purpose of the program
is to decode whatever it is possible to decode, not to produce absolutely
correct MIME output. The incorrect parts are obvious - decoded
- From/To/Cc/Subject headers and filenames. Other than that output is correct
- MIME message. The program does not try to guess whether the headers are
- correct. For example, if a message header states that charset is iso8859-5,
- but the body is actually in utf-8 the program will recode the message with
- the wrong charset.
+ From/To/Cc/Reply-To/Mail-Followup-To/Subject headers and filenames. Other
+ than that output is correct MIME message. The program does not try to guess
+ whether the headers are correct. For example, if a message header states
+ that charset is iso8859-5, but the body is actually in utf-8 the program
+ will recode the message with the wrong charset.
</para>
</refsect1>
projects / mimedecode.git / blobdiff