diff options
| -rw-r--r-- | Doc/Makefile | 2 | ||||
| -rw-r--r-- | Doc/lib/libmailcap.tex | 75 | ||||
| -rw-r--r-- | Doc/lib/libundoc.tex | 2 | ||||
| -rw-r--r-- | Doc/lib/libwww.tex | 3 | ||||
| -rw-r--r-- | Doc/libmailcap.tex | 75 | ||||
| -rw-r--r-- | Doc/libundoc.tex | 2 | ||||
| -rw-r--r-- | Doc/libwww.tex | 3 |
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} |