Updated version from Moshe, with a re-written warning about the

side-effect of cmpcache.cmp() using statcache.stat() internally.

Doc/lib/libcmpcache.tex

@@ -5,32 +5,15 @@
 \sectionauthor{Moshe Zadka}{mzadka@geocities.com}
 \modulesynopsis{Compare files very efficiently.}
 
-The \module{cmpcache} module defines a function to compare files, taking all
-sort of short-cuts to make it a highly efficient operation.
+The \module{cmpcache} module provides an identical interface and similar
+functionality as the \refmodule{cmp} module, but can be a bit more efficient
+as it uses \function{statcache.stat()} instead of \function{os.stat()}
+(see the \refmodule{statcache} module for information on the
+difference).
 
-The \module{cmpcache} module defines the following function:
-
-\begin{funcdesc}{cmp}{f1, f2}
-Compare two files given as names. The following tricks are used to
-optimize the comparisons:
-
-\begin{itemize}
-        \item Signatures (type, size and mtime) are computed via
-              \refmodule{statcache}
-        \item Files with identical type, size and mtime are assumed equal.
-        \item Files with different type or size are never equal.
-        \item The module only compares files it already compared if their
-              signature changed.
-        \item No external programs are called.
-\end{itemize}
-\end{funcdesc}
-
-Example:
-
-\begin{verbatim}
->>> import cmpcache
->>> cmpcache.cmp('libundoc.tex', 'libundoc.tex')
-1
->>> cmpcache.cmp('libundoc.tex', 'lib.tex')
-0
-\end{verbatim}
+\strong{Note:}  Using the \refmodule{statcache} module to provide
+\function{stat()} information results in trashing the cache
+invalidation mechanism: results are not as reliable.  To ensure
+``current'' results, use \function{cmp.cmp()} instead of the version
+defined in this module, or use \function{statcache.forget()} to
+invalidate the appropriate entries.