Style(setup): Fix flake8 F821 undefined name `execfile` under Python 3

[mimedecode.git] / mimedecode.docbook

diff --git a/mimedecode.docbook b/mimedecode.docbook
index 0a690213af43010f8db11d01742d939ebd922938..29d081d84993ff38e5a618d659545b7b6cd8890e 100644 (file)
--- a/mimedecode.docbook
+++ b/mimedecode.docbook
@@ -2,10 +2,10 @@
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "file:///usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd">
 
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "file:///usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd">
 

-<refentry id="mimedecode.py">
+<refentry id="mimedecode">

 
 <refentryinfo>
 
 <refentryinfo>

-  <title>mimedecode.py</title>
+  <title>mimedecode</title>

   <productname>mimedecode.docbook</productname>
   <author>
     <firstname>Oleg</firstname>
   <productname>mimedecode.docbook</productname>
   <author>
     <firstname>Oleg</firstname>


@@ -14,24 +14,24 @@
     <personblurb/>
   </author>
   <copyright>
     <personblurb/>
   </author>
   <copyright>

-    <year>2001-2014</year>
+    <year>2001-2018</year>

     <holder>PhiloSoft Design.</holder>
   </copyright>
 </refentryinfo>
 
 <refmeta>
     <holder>PhiloSoft Design.</holder>
   </copyright>
 </refentryinfo>
 
 <refmeta>

-   <refentrytitle>mimedecode.py</refentrytitle>
+   <refentrytitle>mimedecode</refentrytitle>

    <manvolnum>1</manvolnum>
 </refmeta>
 
 <refnamediv>
    <manvolnum>1</manvolnum>
 </refmeta>
 
 <refnamediv>

-   <refname>mimedecode.py</refname>
+   <refname>mimedecode</refname>

    <refpurpose>decode MIME message</refpurpose>
 </refnamediv>
 
 <refsynopsisdiv>
    <cmdsynopsis>
    <refpurpose>decode MIME message</refpurpose>
 </refnamediv>
 
 <refsynopsisdiv>
    <cmdsynopsis>

-      <command>mimedecode.py</command>
+      <command>mimedecode</command>

       <arg choice="opt">
          <option>-h|--help</option>
       </arg>
       <arg choice="opt">
          <option>-h|--help</option>
       </arg>


@@ -90,7 +90,10 @@
          <option>--set-param header:param=value</option>
       </arg>
       <arg choice="opt">
          <option>--set-param header:param=value</option>
       </arg>
       <arg choice="opt">

-         <option>-Bbeit mask</option>
+         <option>-BbeIit 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 dest_dir</option>


@@ -119,7 +122,7 @@
 </para>
 
 <para>
 </para>
 
 <para>

-   Here is the solution - mimedecode.py!
+   Here is a solution - mimedecode!

 </para>
 
 <para>
 </para>
 
 <para>


@@ -128,8 +131,8 @@
    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
    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.
+   with multiple parts ("attachments") all non-multipart subparts are decoded.
+   Decoding can be controlled by the command-line options.

 </para>
 
 <para>
 </para>
 
 <para>


@@ -137,36 +140,37 @@
    -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
    -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.
+   decoded (if it was not listed in option -d) - 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>
    Then the body of the message (or the current part) is decoded. Decoding
    starts with looking at header Content-Transfer-Encoding. If the header
    specifies non-8bit encoding (usually base64 or quoted-printable), the body
 </para>
 
 <para>
    Then the body of the message (or the current part) is decoded. Decoding
    starts with looking at header Content-Transfer-Encoding. If the header
    specifies non-8bit encoding (usually base64 or quoted-printable), the body

-   converted to 8bit. Then, if its content type is multipart (multipart/related
-   or multipart/mixed, e.g) every part is recursively decoded. If it is not
-   multipart, mailcap database is consulted to find a way to convert the body
-   to plain text. (I have no idea how mailcap can be configured on OSes other
-   than POSIX, please don't ask me; real OS users can consult my example at
-   <ulink url="http://phdru.name/Software/dotfiles/mailcap.html">http://phdru.name/Software/dotfiles/mailcap.html</ulink>).
+   is converted to 8bit (can be prevented with -B). Then if its content type
+   is multipart (multipart/related or multipart/mixed, e.g) every part is
+   recursively decoded. If it is not multipart, mailcap database is consulted
+   to find a way to convert the body to plain text (can be prevented with
+   options -Bbei). (The author has no idea how mailcap can be configured on
+   OSes other than POSIX, please don't ask; users can consult an example at
+   <ulink url="https://phdru.name/Software/dotfiles/mailcap.html">https://phdru.name/Software/dotfiles/mailcap.html</ulink>).

    The decoding process uses the first copiousoutput filter it can find. If
    there are no filters the body just passed as is.
 </para>
 
 <para>
    Then Content-Type header is consulted for charset. If it is not equal to the
    The decoding process uses the first copiousoutput filter it can find. If
    there are no filters the body just passed as is.
 </para>
 
 <para>
    Then Content-Type header is consulted for charset. If it is not equal to the

-   current locale charset and recoding is allowed the body text is recoded.
-   Finally message headers and the body are flushed to stdout.
+   current locale charset and recoding is allowed (see options -Cc) the body
+   text is recoded. Finally message headers and the body are flushed to stdout.

 </para>
 </refsect1>
 
 <refsect1>
   <para>
 </para>
 </refsect1>
 
 <refsect1>
   <para>

-    Please be warned that in the following options asterisk is a shell
+    Please be reminded 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>
     metacharacter and should be escaped or quoted. Either write -d \*,-h1,-h2
     or -d '*,-h1,-h2' or such.
   </para>


@@ -218,7 +222,7 @@
       <term>-f charset</term>
       <listitem>
          <para>
       <term>-f charset</term>
       <listitem>
          <para>

-            Force this charset to be the current default charset instead of
+            Force this charset to be used for recoding instead of charset from

             the current locale.
          </para>
       </listitem>
             the current locale.
          </para>
       </listitem>


@@ -251,10 +255,10 @@
       <listitem>
          <para>
            This variant completely changes headers decoding. First, the list of
       <listitem>
          <para>
            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.
+           headers to decode is cleared (as with -D). 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 the limitation.

          </para>
       </listitem>
    </varlistentry>
          </para>
       </listitem>
    </varlistentry>


@@ -272,8 +276,8 @@
       <term>-p header1[,header2,header3,...]:param1[,param2,param3,...]</term>
       <listitem>
          <para>
       <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).
+            Add the parameter(s) to a list of headers parameters to decode;
+            the parameter(s) 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>
             Initially the list contains header "Content-Type", parameter "name";
             and header "Content-Disposition", parameter "filename".
          </para>


@@ -284,8 +288,8 @@
       <term>-p *[,-header1,-header2,-header3,...]:param1[,param2,param3,...]</term>
       <listitem>
          <para>
       <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
+            Add the parameter(s) to a list of headers parameters to decode;
+            the parameter(s) will be decoded for all headers except the given

             ones.
          </para>
       </listitem>
             ones.
          </para>
       </listitem>


@@ -341,8 +345,8 @@
       <term>-R header1[,header2,header3,...]:param1[,param2,param3,...]</term>
       <listitem>
          <para>
       <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).
+            Add the parameter(s) to a list of headers parameters to remove;
+            the parameter(s) will be removed only for the given header(s).

             Initially the list is empty.
          </para>
       </listitem>
             Initially the list is empty.
          </para>
       </listitem>


@@ -360,7 +364,7 @@
       <term>-R *[,-header1,-header2,-header3,...]:*[,-param1,-param2,-param3,...]</term>
       <listitem>
          <para>
       <term>-R *[,-header1,-header2,-header3,...]:*[,-param1,-param2,-param3,...]</term>
       <listitem>
          <para>

-           Remove listed parameters (or all parameters except listed) frome
+           Remove listed parameters (or all parameters except listed) from

            these headers (or from all headers except listed).
          </para>
       </listitem>
            these headers (or from all headers except listed).
          </para>
       </listitem>


@@ -387,22 +391,23 @@
    </varlistentry>
 
    <varlistentry>
    </varlistentry>
 
    <varlistentry>

-      <term>-b mask</term>
+      <term>-B mask</term>

       <listitem>
          <para>
       <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.
+           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>
 
    <varlistentry>
          </para>
       </listitem>
    </varlistentry>
 
    <varlistentry>

-      <term>-B mask</term>
+      <term>-b mask</term>

       <listitem>
          <para>
       <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).
+            Append mask to the list of binary content types; if the message to
+            decode has a part of this type the program content-transfer-decodes
+            (base64 or whatever to 8bit binary) it and outputs the decoded part
+            as is, without any further processing.

          </para>
       </listitem>
    </varlistentry>
          </para>
       </listitem>
    </varlistentry>


@@ -417,13 +422,25 @@
       </listitem>
    </varlistentry>
 
       </listitem>
    </varlistentry>
 

+   <varlistentry>
+      <term>-I mask</term>
+      <listitem>
+         <para>
+            Append mask to the list of content types to completely ignore.
+            There will be no output - no headers, no body, no warning. For a
+            multipart part the entire subtree is removed.
+         </para>
+      </listitem>
+   </varlistentry>
+

    <varlistentry>
       <term>-i mask</term>
       <listitem>
          <para>
    <varlistentry>
       <term>-i mask</term>
       <listitem>
          <para>

-            Append mask to the list of content types to ignore; if the message to
-            decode has a part of this type the program will not pass it, instead
-            a line "Message body of type `%s' skipped." will be issued.
+            Append mask to the list of content types to ignore; if the message
+            to decode has a part of this type the program outputs headers but
+            skips the body. Instead a line "Message body of type %s skipped."
+            will be issued.

          </para>
       </listitem>
    </varlistentry>
          </para>
       </listitem>
    </varlistentry>


@@ -433,9 +450,30 @@
       <listitem>
          <para>
             Append mask to the list of content types to convert to text; if the
       <listitem>
          <para>
             Append mask to the list of content types to convert to text; if the

-            message to decode has a part of this type the program will consult
-            mailcap database, find first copiousoutput filter and convert the
-            part.
+            message to decode has a part of this type the program consults
+            mailcap database, find the first copiousoutput filter and, if any
+            filter is found, converts the part.
+         </para>
+      </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 lists of content types to save to files;
+            --save-headers saves only decoded headers of the message (or
+            the current subpart); --save-body saves only decoded body;
+            --save-message saves the entire message or subpart (headers +
+            body).

          </para>
       </listitem>
    </varlistentry>
          </para>
       </listitem>
    </varlistentry>


@@ -444,8 +482,8 @@
       <term>-O dest_dir</term>
       <listitem>
          <para>
       <term>-O dest_dir</term>
       <listitem>
          <para>

-           Set destination directory for the output files. Default is current
-           directory.
+           Set destination directory for the output files; if the directory
+           doesn't exist it will be created. Default is the current directory.

           </para>
       </listitem>
    </varlistentry>
           </para>
       </listitem>
    </varlistentry>


@@ -456,8 +494,8 @@
          <para>
             Save output to the file related to the destination directory from
             option -O. Also useful in case of redirected stdin:
          <para>
             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 &lt; input_file
-cat input_file | mimedecode.py -o output_file</programlisting>
+            <programlisting language="sh">mimedecode -o output_file &lt; input_file
+cat input_file | mimedecode -o output_file</programlisting>

          </para>
       </listitem>
    </varlistentry>
          </para>
       </listitem>
    </varlistentry>


@@ -467,32 +505,69 @@ cat input_file | mimedecode.py -o output_file</programlisting>
    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
    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

-   Postscript/PDF to text, pass HTML and images as is, and ignore everything
-   else. Easy:
+   PDF/Postscript to text, pass HTML and images decoding base64 to html but
+   leaving images encoded, and ignore everything else. This is how it could be
+   done:

 </para>
 
 <para>
 <code language="sh">
 </para>
 
 <para>
 <code language="sh">

-   mimedecode.py -t application/postscript -t application/pdf -b text/html
-         -b 'image/*' -i '*/*'
+  mimedecode -t application/pdf -t application/postscript -t text/plain
+      -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
 </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
-   action performed. If not found, the program search the same lists for
+   in all 5 lists, in order "text-binary-ignore-error". If found, appropriate
+   action is performed. If not found, the program searches the same lists for

    "type/*" mask (the type of "text/html" is just "text"). If found,
    "type/*" mask (the type of "text/html" is just "text"). If found,

-   appropriate action performed. If not found, the program search the same
-   lists for "*/*" mask. If found, appropriate action performed. If not found,
-   the program uses default action, which is to decode everything to text (if
-   mailcap specifies a filter).
+   appropriate action is performed. If not found, the program searches the same
+   lists for "*/*" mask. If found, appropriate action is performed. If not
+   found, the program uses the default action, which is to decode everything to
+   text (if mailcap specifies a filter). This algorithm allows more specific
+   content types to override less specific: -b image/* will be processed
+   earlier than -B */*.
+</para>
+
+<para>
+  Options -e/-I/-i can also work with multipart subparts of a MIME message. In
+  case of -I/-i the entire subtree of that multipart is removed; with -i it's
+  replaced with ignore warning.
+</para>
+
+<para>
+   Initially all 5 lists are empty, so without any additional parameters
+   the program always uses the default decoding (as -t */*).
+</para>
+
+<para>
+  The 3 save 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: headers + body) that corresponds to the given mask to a file.
+  Before saving the message (or the subpart) is decoded according to all other
+  options and is 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, or the name/filename parameters contain forbidden
+  characters (null, slash, backslash) the filename is just the serial counter.
+</para>
+
+<para>
+  If the file doesn't have any extensions (no dots in the value of the
+  name/filename parameters, or the name is just the counter) the program tries
+  to guess an extension by looking up the content type in mime.types files
+  including .mime.types file in the user's home directory (if it exists). If
+  the file has an extension the program doesn't try to verify that it
+  corresponds to the content type.

 </para>
 
 <para>
 </para>
 
 <para>

-   Initially all 4 lists are empty, so without any additional parameters
-the program always uses the default decoding.
+  The file is saved in the directory set with -O (default is the current
+  directory). The save options are proceeded before -e options so the user can
+  save the message that causes an error.

 </para>
 </refsect1>
 
 </para>
 </refsect1>
 


@@ -520,8 +595,8 @@ the program always uses the default decoding.
    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
    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.
+   that charset is iso8859-1, but the body (HTML, for example) is actually in
+   utf-8 the program will recode the message with the wrong charset.

 </para>
 </refsect1>
 
 </para>
 </refsect1>
 


@@ -539,7 +614,7 @@ the program always uses the default decoding.
 <refsect1>
 <title>COPYRIGHT</title>
 <para>
 <refsect1>
 <title>COPYRIGHT</title>
 <para>

-  Copyright (C) 2001-2014 PhiloSoft Design.
+  Copyright (C) 2001-2018 PhiloSoft Design.

 </para>
 </refsect1>
 
 </para>
 </refsect1>
 


@@ -566,8 +641,8 @@ the program always uses the default decoding.
 <refsect1>
 <title>SEE ALSO</title>
 <para>
 <refsect1>
 <title>SEE ALSO</title>
 <para>

-  mimedecode.py home page:
-  <ulink url="http://phdru.name/Software/Python/#mimedecode">http://phdru.name/Software/Python/#mimedecode</ulink>
+  mimedecode home page:
+  <ulink url="https://phdru.name/Software/Python/#mimedecode">https://phdru.name/Software/Python/#mimedecode</ulink>

 </para>
 </refsect1>
 
 </para>
 </refsect1>