Added docs for mailcap

7 files changed, 157 insertions, 5 deletions

diff --git a/Doc/Makefile b/Doc/Makefile
index e1b2c36..db63157 100644
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -113,7 +113,7 @@ LIBFILES = lib.tex \
     libxdrlib.tex libimghdr.tex \
     librestricted.tex librexec.tex libbastion.tex \
     libformatter.tex liboperator.tex libsoundex.tex libresource.tex \
-    libstat.tex libstrio.tex libundoc.tex
+    libstat.tex libstrio.tex libundoc.tex libmailcap.tex
 
 # Library document
 lib.dvi: $(LIBFILES)
diff --git a/Doc/lib/libmailcap.tex b/Doc/lib/libmailcap.tex
new file mode 100644
index 0000000..7fea9b5
--- /dev/null
+++ b/Doc/lib/libmailcap.tex
@@ -0,0 +1,75 @@
+\section{Standard Module \sectcode{mailcap}}
+\stmodindex{mailcap}
+\renewcommand{\indexsubitem}{(in module mailcap)}
+
+Mailcap files are used to configure how MIME-aware applications such
+as mail readers and Web browsers react to files with different MIME
+types. (The name ``mailcap'' is derived from the phrase ``mail
+capability''.)  For example, a mailcap file might contain a line like
+\verb\video/mpeg; xmpeg %s\.  Then, if the user encounters an email
+message or Web document with the MIME type video/mpeg, \verb\%s\ will be
+replaced by a filename (usually one belonging to a temporary file) and
+the xmpeg program can be automatically started to view the file.
+
+The mailcap format is documented in RFC 1524, ``A User Agent
+Configuration Mechanism For Multimedia Mail Format Information'', but
+is not an Internet standard.  However, mailcap files are supported on
+most Unix systems.
+
+\begin{funcdesc}{findmatch}{caps\, MIMEtype\, key\, filename\, plist}
+Return a 2-tuple; the first element is a string containing the command
+line to be executed
+(which can be passed to \code{os.system()}), and the second element is
+the mailcap entry for a given MIME type.  If no matching MIME
+type can be found, \code{(None, None)} is returned.
+
+\var{key} is the name of the field desired, which represents the type of
+activity to be performed; the default value is 'view', since in the
+most common case you simply want to view the body of the MIME-typed
+data.  Other possible values might be 'compose' and 'edit', if you
+wanted to create a new body of the given MIME type or alter the
+existing body data.  See RFC1524 for a complete list of these fields.
+
+\var{filename} is the filename to be substituted for \%s in the
+command line; the default value is
+\file{/dev/null} which is almost certainly not what you want, so
+usually you'll override it by specifying a filename.
+
+\var{plist} can be a list containing named parameters; the default
+value is simply an empty list.  Each entry in the list must be a
+string containing the parameter name, an equals sign (=), and the
+parameter's value.  Mailcap entries can contain 
+named parameters like \verb\%{foo}\, which will be replaced by the
+value of the parameter named 'foo'.  For example, if the command line
+\verb\showpartial %{id} %{number} %{total}\
+was in a mailcap file, and \var{plist} was set to \code{['id=1',
+'number=2', 'total=3']}, the resulting command line would be 
+\code{"showpartial 1 2 3"}.  
+
+In a mailcap file, the "test" field can optionally be specified to
+test some external condition (e.g., the machine architecture, or the
+window system in use) to determine whether or not the mailcap line
+applies.  \code{findmatch()} will automatically check such conditions
+and skip the entry if the check fails.
+\end{funcdesc}
+
+\begin{funcdesc}{getcaps}{}
+Returns a dictionary mapping MIME types to a list of mailcap file
+entries. This dictionary must be passed to the \code{findmatch}
+function.  An entry is stored as a list of dictionaries, but it
+shouldn't be necessary to know the details of this representation.
+
+The information is derived from all of the mailcap files found on the
+system. Settings in the user's mailcap file \file{\$HOME/.mailcap}
+will override settings in the system mailcap files
+\file{/etc/mailcap}, \file{/usr/etc/mailcap}, and
+\file{/usr/local/etc/mailcap}.
+\end{funcdesc}
+
+An example usage:
+\begin{verbatim}
+>>> import mailcap
+>>> d=mailcap.getcaps()
+>>> mailcap.findmatch(d, 'video/mpeg', filename='/tmp/tmp1223')
+('xmpeg /tmp/tmp1223', {'view': 'xmpeg %s'})
+\end{verbatim}
diff --git a/Doc/lib/libundoc.tex b/Doc/lib/libundoc.tex
index 8e2e5db..bcd52a9 100644
--- a/Doc/lib/libundoc.tex
+++ b/Doc/lib/libundoc.tex
@@ -44,8 +44,6 @@ multifile.py -- make each part of a multipart message ``feel'' like
 
 base64.py -- Conversions to/from base64 transport encoding
 
-mailcap.py -- Mailcap file handling
-
 mailbox.py -- handle Unix style, MMDF style, and MH style mailboxes
 
 quopri.py -- Conversions to/from quoted-printable transport encoding
diff --git a/Doc/lib/libwww.tex b/Doc/lib/libwww.tex
index aebe931..aae20b2 100644
--- a/Doc/lib/libwww.tex
+++ b/Doc/lib/libwww.tex
@@ -65,4 +65,7 @@ representation
 --- The External Data Representation Standard as described in RFC 1014,
 written by Sun Microsystems, Inc. June 1987.
 
+\item[mailcap]
+--- Mailcap file handling.  See RFC 1524.
+
 \end{description}
diff --git a/Doc/libmailcap.tex b/Doc/libmailcap.tex
new file mode 100644
index 0000000..7fea9b5
--- /dev/null
+++ b/Doc/libmailcap.tex
@@ -0,0 +1,75 @@
+\section{Standard Module \sectcode{mailcap}}
+\stmodindex{mailcap}
+\renewcommand{\indexsubitem}{(in module mailcap)}
+
+Mailcap files are used to configure how MIME-aware applications such
+as mail readers and Web browsers react to files with different MIME
+types. (The name ``mailcap'' is derived from the phrase ``mail
+capability''.)  For example, a mailcap file might contain a line like
+\verb\video/mpeg; xmpeg %s\.  Then, if the user encounters an email
+message or Web document with the MIME type video/mpeg, \verb\%s\ will be
+replaced by a filename (usually one belonging to a temporary file) and
+the xmpeg program can be automatically started to view the file.
+
+The mailcap format is documented in RFC 1524, ``A User Agent
+Configuration Mechanism For Multimedia Mail Format Information'', but
+is not an Internet standard.  However, mailcap files are supported on
+most Unix systems.
+
+\begin{funcdesc}{findmatch}{caps\, MIMEtype\, key\, filename\, plist}
+Return a 2-tuple; the first element is a string containing the command
+line to be executed
+(which can be passed to \code{os.system()}), and the second element is
+the mailcap entry for a given MIME type.  If no matching MIME
+type can be found, \code{(None, None)} is returned.
+
+\var{key} is the name of the field desired, which represents the type of
+activity to be performed; the default value is 'view', since in the
+most common case you simply want to view the body of the MIME-typed
+data.  Other possible values might be 'compose' and 'edit', if you
+wanted to create a new body of the given MIME type or alter the
+existing body data.  See RFC1524 for a complete list of these fields.
+
+\var{filename} is the filename to be substituted for \%s in the
+command line; the default value is
+\file{/dev/null} which is almost certainly not what you want, so
+usually you'll override it by specifying a filename.
+
+\var{plist} can be a list containing named parameters; the default
+value is simply an empty list.  Each entry in the list must be a
+string containing the parameter name, an equals sign (=), and the
+parameter's value.  Mailcap entries can contain 
+named parameters like \verb\%{foo}\, which will be replaced by the
+value of the parameter named 'foo'.  For example, if the command line
+\verb\showpartial %{id} %{number} %{total}\
+was in a mailcap file, and \var{plist} was set to \code{['id=1',
+'number=2', 'total=3']}, the resulting command line would be 
+\code{"showpartial 1 2 3"}.  
+
+In a mailcap file, the "test" field can optionally be specified to
+test some external condition (e.g., the machine architecture, or the
+window system in use) to determine whether or not the mailcap line
+applies.  \code{findmatch()} will automatically check such conditions
+and skip the entry if the check fails.
+\end{funcdesc}
+
+\begin{funcdesc}{getcaps}{}
+Returns a dictionary mapping MIME types to a list of mailcap file
+entries. This dictionary must be passed to the \code{findmatch}
+function.  An entry is stored as a list of dictionaries, but it
+shouldn't be necessary to know the details of this representation.
+
+The information is derived from all of the mailcap files found on the
+system. Settings in the user's mailcap file \file{\$HOME/.mailcap}
+will override settings in the system mailcap files
+\file{/etc/mailcap}, \file{/usr/etc/mailcap}, and
+\file{/usr/local/etc/mailcap}.
+\end{funcdesc}
+
+An example usage:
+\begin{verbatim}
+>>> import mailcap
+>>> d=mailcap.getcaps()
+>>> mailcap.findmatch(d, 'video/mpeg', filename='/tmp/tmp1223')
+('xmpeg /tmp/tmp1223', {'view': 'xmpeg %s'})
+\end{verbatim}
diff --git a/Doc/libundoc.tex b/Doc/libundoc.tex
index 8e2e5db..bcd52a9 100644
--- a/Doc/libundoc.tex
+++ b/Doc/libundoc.tex
@@ -44,8 +44,6 @@ multifile.py -- make each part of a multipart message ``feel'' like
 
 base64.py -- Conversions to/from base64 transport encoding
 
-mailcap.py -- Mailcap file handling
-
 mailbox.py -- handle Unix style, MMDF style, and MH style mailboxes
 
 quopri.py -- Conversions to/from quoted-printable transport encoding
diff --git a/Doc/libwww.tex b/Doc/libwww.tex
index aebe931..aae20b2 100644
--- a/Doc/libwww.tex
+++ b/Doc/libwww.tex
@@ -65,4 +65,7 @@ representation
 --- The External Data Representation Standard as described in RFC 1014,
 written by Sun Microsystems, Inc. June 1987.
 
+\item[mailcap]
+--- Mailcap file handling.  See RFC 1524.
+
 \end{description}