Restructured library documentation

1 files changed, 128 insertions, 0 deletions

diff --git a/Doc/libppath.tex b/Doc/libppath.tex
new file mode 100644
index 0000000..e6430be
--- /dev/null
+++ b/Doc/libppath.tex
@@ -0,0 +1,128 @@
+\section{Standard Module \sectcode{posixpath}}
+
+\stmodindex{posixpath}
+This module implements some useful functions on POSIX pathnames.
+
+\renewcommand{\indexsubitem}{(in module posixpath)}
+\begin{funcdesc}{basename}{p}
+Return the base name of pathname
+\var{p}.
+This is the second half of the pair returned by
+\code{posixpath.split(\var{p})}.
+\end{funcdesc}
+
+\begin{funcdesc}{commonprefix}{list}
+Return the longest string that is a prefix of all strings in
+\var{list}.
+If
+\var{list}
+is empty, return the empty string (\code{''}).
+\end{funcdesc}
+
+\begin{funcdesc}{exists}{p}
+Return true if
+\var{p}
+refers to an existing path.
+\end{funcdesc}
+
+\begin{funcdesc}{expanduser}{p}
+Return the argument with an initial component of \samp{\~} or
+\samp{\~\var{user}} replaced by that \var{user}'s home directory.  An
+initial \samp{\~{}} is replaced by the environment variable \code{\${}HOME};
+an initial \samp{\~\var{user}} is looked up in the password directory through
+the built-in module \code{pwd}.  If the expansion fails, or if the
+path does not begin with a tilde, the path is returned unchanged.
+\end{funcdesc}
+
+\begin{funcdesc}{isabs}{p}
+Return true if \var{p} is an absolute pathname (begins with a slash).
+\end{funcdesc}
+
+\begin{funcdesc}{isfile}{p}
+Return true if \var{p} is an existing regular file.  This follows
+symbolic links, so both islink() and isfile() can be true for the same
+path.
+\end{funcdesc}
+
+\begin{funcdesc}{isdir}{p}
+Return true if \var{p} is an existing directory.  This follows
+symbolic links, so both islink() and isdir() can be true for the same
+path.
+\end{funcdesc}
+
+\begin{funcdesc}{islink}{p}
+Return true if
+\var{p}
+refers to a directory entry that is a symbolic link.
+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?)
+\end{funcdesc}
+
+\begin{funcdesc}{join}{p\, q}
+Join the paths
+\var{p}
+and
+\var{q} intelligently:
+If
+\var{q}
+is an absolute path, the return value is
+\var{q}.
+Otherwise, the concatenation of
+\var{p}
+and
+\var{q}
+is returned, with a slash (\code{'/'}) inserted unless
+\var{p}
+is empty or ends in a slash.
+\end{funcdesc}
+
+\begin{funcdesc}{normcase}{p}
+Normalize the case of a pathname.  This returns the path unchanged;
+however, a similar function in \code{macpath} converts upper case to
+lower case.
+\end{funcdesc}
+
+\begin{funcdesc}{samefile}{p\, q}
+Return true if both pathname arguments refer to the same file or directory
+(as indicated by device number and i-node number).
+Raise an exception if a stat call on either pathname fails.
+\end{funcdesc}
+
+\begin{funcdesc}{split}{p}
+Split the pathname \var{p} in a pair \code{(\var{head}, \var{tail})}, where
+\var{tail} is the last pathname component and \var{head} is
+everything leading up to that.  If \var{p} ends in a slash (except if
+it is the root), the trailing slash is removed and the operation
+applied to the result; otherwise, \code{join(\var{head}, \var{tail})} equals
+\var{p}.  The \var{tail} part never contains a slash.  Some boundary
+cases: if \var{p} is the root, \var{head} equals \var{p} and
+\var{tail} is empty; if \var{p} is empty, both \var{head} and
+\var{tail} are empty; if \var{p} contains no slash, \var{head} is
+empty and \var{tail} equals \var{p}.
+\end{funcdesc}
+
+\begin{funcdesc}{splitext}{p}
+Split the pathname \var{p} in a pair \code{(\var{root}, \var{ext})}
+such that \code{\var{root} + \var{ext} == \var{p}},
+the last component of \var{root} contains no periods,
+and \var{ext} is empty or begins with a period.
+\end{funcdesc}
+
+\begin{funcdesc}{walk}{p\, visit\, arg}
+Calls the function \var{visit} with arguments
+\code{(\var{arg}, \var{dirname}, \var{names})} for each directory in the
+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.)
+\end{funcdesc}