mass changes; fix titles; add examples; correct typos; clarifications;

 unified style; etc.

1 files changed, 18 insertions, 10 deletions

diff --git a/Doc/libppath.tex b/Doc/libppath.tex
index c7c2b63..0d3bbe5 100644
--- a/Doc/libppath.tex
+++ b/Doc/libppath.tex
@@ -1,9 +1,14 @@
 \section{Standard Module \sectcode{posixpath}}
-
 \stmodindex{posixpath}
+
 This module implements some useful functions on POSIX pathnames.
 
+\strong{Do not import this module directly.}  Instead, import the
+module \code{os} and use \code{os.path}.
+\stmodindex{os}
+
 \renewcommand{\indexsubitem}{(in module posixpath)}
+
 \begin{funcdesc}{basename}{p}
 Return the base name of pathname
 \var{p}.
@@ -66,10 +71,12 @@ Always false if symbolic links are not supported.
 \end{funcdesc}
 
 \begin{funcdesc}{ismount}{p}
-Return true if \var{p} is a mount point.  (This currently checks whether
-\code{\var{p}/..} is on a different device from \var{p} or whether
-\code{\var{p}/..} and \var{p} point to the same i-node on the same
-device --- is this test correct for all \UNIX{} and POSIX variants?)
+Return true if pathname \var{p} is a \dfn{mount point}: a point in a
+file system where a different file system has been mounted.  The
+function checks whether \var{p}'s parent, \file{\var{p}/..}, is on a
+different device than \var{p}, or whether \file{\var{p}/..} and
+\var{p} point to the same i-node on the same device --- this should
+detect mount points for all \UNIX{} and POSIX variants.
 \end{funcdesc}
 
 \begin{funcdesc}{join}{p\, q}
@@ -128,9 +135,10 @@ Calls the function \var{visit} with arguments
 directory tree rooted at \var{p} (including \var{p} itself, if it is a
 directory).  The argument \var{dirname} specifies the visited directory,
 the argument \var{names} lists the files in the directory (gotten from
-\code{posix.listdir(\var{dirname})}).  The \var{visit} function may
-modify \var{names} to influence the set of directories visited below
-\var{dirname}, e.g., to avoid visiting certain parts of the tree.  (The
-object referred to by \var{names} must be modified in place, using
-\code{del} or slice assignment.)
+\code{posix.listdir(\var{dirname})}, so including \samp{.} and
+\samp{..}).  The \var{visit} function may modify \var{names} to
+influence the set of directories visited below \var{dirname}, e.g., to
+avoid visiting certain parts of the tree.  (The object referred to by
+\var{names} must be modified in place, using \code{del} or slice
+assignment.)
 \end{funcdesc}