Doc/lib/libmimify.tex

   1 \section{\module{mimify} ---
   2          MIME processing of mail messages}
   3
   4 \declaremodule{standard}{mimify}
   5 \modulesynopsis{Mimification and unmimification of mail messages.}
   6
   7 \deprecated{2.3}{The \refmodule{email} package should be used in
   8                  preference to the \module{mimify} module.  This
   9                  module is present only to maintain backward
  10                  compatibility.}
  11
  12 The \module{mimify} module defines two functions to convert mail messages to
  13 and from MIME format.  The mail message can be either a simple message
  14 or a so-called multipart message.  Each part is treated separately.
  15 Mimifying (a part of) a message entails encoding the message as
  16 quoted-printable if it contains any characters that cannot be
  17 represented using 7-bit \ASCII.  Unmimifying (a part of) a message
  18 entails undoing the quoted-printable encoding.  Mimify and unmimify
  19 are especially useful when a message has to be edited before being
  20 sent.  Typical use would be:
  21
  22 \begin{verbatim}
  23 unmimify message
  24 edit message
  25 mimify message
  26 send message
  27 \end{verbatim}
  28
  29 The modules defines the following user-callable functions and
  30 user-settable variables:
  31
  32 \begin{funcdesc}{mimify}{infile, outfile}
  33 Copy the message in \var{infile} to \var{outfile}, converting parts to
  34 quoted-printable and adding MIME mail headers when necessary.
  35 \var{infile} and \var{outfile} can be file objects (actually, any
  36 object that has a \method{readline()} method (for \var{infile}) or a
  37 \method{write()} method (for \var{outfile})) or strings naming the files.
  38 If \var{infile} and \var{outfile} are both strings, they may have the
  39 same value.
  40 \end{funcdesc}
  41
  42 \begin{funcdesc}{unmimify}{infile, outfile\optional{, decode_base64}}
  43 Copy the message in \var{infile} to \var{outfile}, decoding all
  44 quoted-printable parts.  \var{infile} and \var{outfile} can be file
  45 objects (actually, any object that has a \method{readline()} method (for
  46 \var{infile}) or a \method{write()} method (for \var{outfile})) or strings
  47 naming the files.  If \var{infile} and \var{outfile} are both strings,
  48 they may have the same value.
  49 If the \var{decode_base64} argument is provided and tests true, any
  50 parts that are coded in the base64 encoding are decoded as well.
  51 \end{funcdesc}
  52
  53 \begin{funcdesc}{mime_decode_header}{line}
  54 Return a decoded version of the encoded header line in \var{line}.
  55 This only supports the ISO 8859-1 charset (Latin-1).
  56 \end{funcdesc}
  57
  58 \begin{funcdesc}{mime_encode_header}{line}
  59 Return a MIME-encoded version of the header line in \var{line}.
  60 \end{funcdesc}
  61
  62 \begin{datadesc}{MAXLEN}
  63 By default, a part will be encoded as quoted-printable when it
  64 contains any non-\ASCII{} characters (characters with the 8th bit
  65 set), or if there are any lines longer than \constant{MAXLEN} characters
  66 (default value 200).
  67 \end{datadesc}
  68
  69 \begin{datadesc}{CHARSET}
  70 When not specified in the mail headers, a character set must be filled
  71 in.  The string used is stored in \constant{CHARSET}, and the default
  72 value is ISO-8859-1 (also known as Latin1 (latin-one)).
  73 \end{datadesc}
  74
  75 This module can also be used from the command line.  Usage is as
  76 follows:
  77 \begin{verbatim}
  78 mimify.py -e [-l length] [infile [outfile]]
  79 mimify.py -d [-b] [infile [outfile]]
  80 \end{verbatim}
  81 to encode (mimify) and decode (unmimify) respectively.  \var{infile}
  82 defaults to standard input, \var{outfile} defaults to standard output.
  83 The same file can be specified for input and output.
  84
  85 If the \strong{-l} option is given when encoding, if there are any lines
  86 longer than the specified \var{length}, the containing part will be
  87 encoded.
  88
  89 If the \strong{-b} option is given when decoding, any base64 parts will
  90 be decoded as well.
  91
  92 \begin{seealso}
  93   \seemodule{quopri}{Encode and decode MIME quoted-printable files.}
  94 \end{seealso}