diff options
Diffstat (limited to 'Doc/libmailcap.tex')
-rw-r--r-- | Doc/libmailcap.tex | 79 |
1 files changed, 0 insertions, 79 deletions
diff --git a/Doc/libmailcap.tex b/Doc/libmailcap.tex deleted file mode 100644 index 0ea762a..0000000 --- a/Doc/libmailcap.tex +++ /dev/null @@ -1,79 +0,0 @@ -\section{Standard Module \module{mailcap}} -\label{module-mailcap} -\stmodindex{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 -\samp{video/mpeg; xmpeg \%s}. Then, if the user encounters an email -message or Web document with the MIME type \mimetype{video/mpeg}, -\samp{\%s} will be replaced by a filename (usually one belonging to a -temporary file) and the \program{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% - \optional{, key\optional{, - filename\optional{, 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 \rfc{1524} for a complete list of these -fields. - -\var{filename} is the filename to be substituted for \samp{\%s} in the -command line; the default value is -\code{'/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 (\code{=}), and the -parameter's value. Mailcap entries can contain -named parameters like \code{\%\{foo\}}, which will be replaced by the -value of the parameter named 'foo'. For example, if the command line -\samp{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} |