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

 unified style; etc.

1 files changed, 39 insertions, 12 deletions

diff --git a/Doc/libos.tex b/Doc/libos.tex
index 5109f5d..51442ef 100644
--- a/Doc/libos.tex
+++ b/Doc/libos.tex
@@ -26,9 +26,11 @@ In addition to whatever the correct OS dependent module exports, the
 following variables and functions are always exported by \code{os}:
 
 \renewcommand{\indexsubitem}{(in module os)}
+
 \begin{datadesc}{name}
-The name of the OS dependent module imported, e.g. \code{'posix'} or
-\code{'mac'}.
+The name of the OS dependent module imported.  The following names
+have currently been registered: \code{'posix'}, \code{'nt'},
+\code{'dos'}, \code{'mac'}.
 \end{datadesc}
 
 \begin{datadesc}{path}
@@ -49,29 +51,54 @@ e.g. \code{'..'} for POSIX or \code{'::'} for the Mac.
 \end{datadesc}
 
 \begin{datadesc}{sep}
-The character used by the OS to separate pathname components, e.g.
+The character used by the OS to separate pathname components, e.g.\
 \code{'/'} for POSIX or \code{':'} for the Mac.  Note that knowing this
 is not sufficient to be able to parse or concatenate pathnames---better
 use \code{os.path.split()} and \code{os.path.join()}---but it is
 occasionally useful.
 \end{datadesc}
 
+\begin{datadesc}{pathsep}
+The character conventionally used by the OS to separate search patch
+components (as in \code{\$PATH}), e.g.\ \code{':'} for POSIX or
+\code{';'} for MS-DOS.
+\end{datadesc}
+
+\begin{datadesc}{defpath}
+The default search path used by \code{os.exec*p*()} if the environment
+doesn't have a \code{'PATH'} key.
+\end{datadesc}
+
 \begin{funcdesc}{execl}{path\, arg0\, arg1\, ...}
-This is equivalent to a call to \code{os.execv} with an \var{argv}
-of \code{[\var{arg0}, \var{arg1}, ...]}.
+This is equivalent to
+\code{os.execv(\var{path}, (\var{arg0}, \var{arg1}, ...))}.
 \end{funcdesc}
 
 \begin{funcdesc}{execle}{path\, arg0\, arg1\, ...\, env}
-This is equivalent to a call to \code{os.execve} with an \var{argv}
-of \code{[\var{arg0}, \var{arg1}, ...]}.
+This is equivalent to
+\code{os.execve(\var{path}, (\var{arg0}, \var{arg1}, ...), \var{env})}.
 \end{funcdesc}
 
 \begin{funcdesc}{execlp}{path\, arg0\, arg1\, ...}
-This is like \code{execl} but duplicates the shell's actions in
-searching for an executable file in a list of directories.  The
-directory list is obtained from \code{environ['PATH']}.
+This is equivalent to
+\code{os.execvp(\var{path}, (\var{arg0}, \var{arg1}, ...))}.
+\end{funcdesc}
+
+\begin{funcdesc}{execvp}{path\, args}
+This is like \code{os.execv(\var{path}, \var{args})} but duplicates
+the shell's actions in searching for an executable file in a list of
+directories.  The directory list is obtained from
+\code{os.environ['PATH']}.
 \end{funcdesc}
 
-\begin{funcdesc}{execvp}{path\, arg0\, arg1\, ...}
-\code{execvp} is for \code{execv} what \code{execlp} is for \code{execl}.
+\begin{funcdesc}{execvpe}{path\, args\, env}
+This is a cross between \code{os.execve()} and \code{os.execvp()}.
+The directory list is obtained from \code{\var{env}['PATH']}.
 \end{funcdesc}
+
+(The functions \code{os.execv()} and \code{execve()} are not
+documented here, since they are implemented by the OS dependent
+module.  If the OS dependent module doesn't define either of these,
+the functions that rely on it will raise an exception.  They are
+documented in the section on module \code{posix}, together with all
+other functions that \code{os} imports from the OS dependent module.)