Add documentation for the new aspects of the mimetypes module.

This closes the SF bug (feature request) #439710.

diff --git a/Doc/lib/libmimetypes.tex b/Doc/lib/libmimetypes.tex
index da892381e97901adaa0c4e3d6d8b613fc4faa51b..3801109bf3b5f6bfe3cf320669fe564f321e6a58 100644 (file)
--- a/Doc/lib/libmimetypes.tex
+++ b/Doc/lib/libmimetypes.tex
@@ -13,9 +13,14 @@ type associated with the filename extension.  Conversions are provided
 from filename to MIME type and from MIME type to filename extension;
 encodings are not supported for the later conversion.
 
+The module provides one class and a number of convenience functions.
+The functions are the normal interface to this module, but some
+applications may be interested in the class as well.
+
 The functions described below provide the primary interface for this
 module.  If the module has not been initialized, they will call
-\function{init()}.
+\function{init()} if they rely on the information \function{init()}
+sets up.
 
 
 \begin{funcdesc}{guess_type}{filename}
@@ -92,3 +97,67 @@ Dictionary mapping filename extensions to encoding types.
 \begin{datadesc}{types_map}
 Dictionary mapping filename extensions to MIME types.
 \end{datadesc}
+
+
+The \class{MimeTypes} class may be useful for applications which may
+want more than one MIME-type database:
+
+\begin{classdesc}{MimeTypes}{\optional{filenames}}
+  This class represents a MIME-types database.  By default, it
+  provides access to the same database as the rest of this module.
+  The initial database is a copy of that provided by the module, and
+  may be extended by loading additional \file{mime.types}-style files
+  into the database using the \method{read()} or \method{readfp()}
+  methods.  The mapping dictionaries may also be cleared before
+  loading additional data if the default data is not desired.
+
+  The optional \var{filenames} parameter can be used to cause
+  additional files to be loaded ``on top'' of the default database.
+\end{classdesc}
+
+
+\subsection{MimeTypes Objects \label{mimetypes-objects}}
+
+\class{MimeTypes} instances provide an interface which is very like
+that of the \refmodule{mimetypes} module.
+
+\begin{datadesc}{suffix_map}
+  Dictionary mapping suffixes to suffixes.  This is used to allow
+  recognition of encoded files for which the encoding and the type are
+  indicated by the same extension.  For example, the \file{.tgz}
+  extension is mapped to \file{.tar.gz} to allow the encoding and type
+  to be recognized separately.  This is initially a copy of the global
+  \code{suffix_map} defined in the module.
+\end{datadesc}
+
+\begin{datadesc}{encodings_map}
+  Dictionary mapping filename extensions to encoding types.  This is
+  initially a copy of the global \code{encodings_map} defined in the
+  module.
+\end{datadesc}
+
+\begin{datadesc}{types_map}
+  Dictionary mapping filename extensions to MIME types.  This is
+  initially a copy of the global \code{types_map} defined in the
+  module.
+\end{datadesc}
+
+\begin{methoddesc}{guess_extension}{type}
+  Similar to the \function{guess_extension()} function, using the
+  tables stored as part of the object.
+\end{methoddesc}
+
+\begin{methoddesc}{guess_type}{url}
+  Similar to the \function{guess_type()} function, using the tables
+  stored as part of the object.
+\end{methoddesc}
+
+\begin{methoddesc}{read}{path}
+  Load MIME information from a file named \var{path}.  This uses
+  \method{readfp()} to parse the file.
+\end{methoddesc}
+
+\begin{methoddesc}{readfp}{file}
+  Load MIME type information from an open file.  The file must have
+  the format of the standard \file{mime.types} files.
+\end{methoddesc}