From d3aad0199e5a6dc8e4907210daa89fc32bb57c94 Mon Sep 17 00:00:00 2001
From: "Andrew M. Kuchling" <amk@amk.ca>
Date: Fri, 27 Oct 2006 14:53:41 +0000
Subject: [PATCH] Point users to the subprocess module in the docs for
 os.system, os.spawn*, os.popen2, and the popen2 and commands modules

---
 Doc/lib/libcommands.tex   |  9 +++++++++
 Doc/lib/libos.tex         | 23 +++++++++++++++++++++--
 Doc/lib/libpopen2.tex     | 12 ++++++++----
 Doc/lib/libsubprocess.tex |  3 ---
 4 files changed, 38 insertions(+), 9 deletions(-)

diff --git a/Doc/lib/libcommands.tex b/Doc/lib/libcommands.tex
index 74e7023a791..53b8a207075 100644
--- a/Doc/lib/libcommands.tex
+++ b/Doc/lib/libcommands.tex
@@ -12,6 +12,11 @@ The \module{commands} module contains wrapper functions for
 return any output generated by the command and, optionally, the exit
 status.
 
+The \module{subprocess} module provides more powerful facilities for
+spawning new processes and retrieving their results.  Using the
+\module{subprocess} module is preferable to using the \module{commands}
+module.
+
 The \module{commands} module defines the following functions:
 
 
@@ -51,3 +56,7 @@ Example:
 >>> commands.getstatus('/bin/ls')
 '-rwxr-xr-x  1 root        13352 Oct 14  1994 /bin/ls'
 \end{verbatim}
+
+\begin{seealso}
+  \seemodule{subprocess}{Module for spawning and managing subprocesses.}
+\end{seealso}
diff --git a/Doc/lib/libos.tex b/Doc/lib/libos.tex
index beb6eff9376..355d8fab257 100644
--- a/Doc/lib/libos.tex
+++ b/Doc/lib/libos.tex
@@ -361,6 +361,10 @@ object, except that when the exit status is zero (termination without
 errors), \code{None} is returned.
 Availability: Macintosh, \UNIX, Windows.
 
+The \module{subprocess} module provides more powerful facilities for
+spawning new processes and retrieving their results; using that module
+is preferable to using this function.
+
 \versionchanged[This function worked unreliably under Windows in
   earlier versions of Python.  This was due to the use of the
   \cfunction{_popen()} function from the libraries provided with
@@ -375,8 +379,13 @@ deleted once there are no file descriptors for the file.
 Availability: Macintosh, \UNIX, Windows.
 \end{funcdesc}
 
+There are a number of different \function{popen*()} functions that
+provide slightly different ways to create subprocesses.  Note that the
+\module{subprocess} module is easier to use and more powerful;
+consider using that module before writing code using the
+lower-level \function{popen*()} functions.
 
-For each of the following \function{popen()} variants, if \var{bufsize} is
+For each of the \function{popen*()} variants, if \var{bufsize} is
 specified, it specifies the buffer size for the I/O pipes.
 \var{mode}, if provided, should be the string \code{'b'} or
 \code{'t'}; on Windows this is needed to determine whether the file
@@ -1547,7 +1556,13 @@ functions are described in section \ref{os-newstreams}.
 \funcline{spawnve}{mode, path, args, env}
 \funcline{spawnvp}{mode, file, args}
 \funcline{spawnvpe}{mode, file, args, env}
-Execute the program \var{path} in a new process.  If \var{mode} is
+Execute the program \var{path} in a new process.  
+
+(Note that the \module{subprocess} module provides more powerful
+facilities for spawning new processes and retrieving their results;
+using that module is preferable to using these functions.)
+
+If \var{mode} is
 \constant{P_NOWAIT}, this function returns the process ID of the new
 process; if \var{mode} is \constant{P_WAIT}, returns the process's
 exit code if it exits normally, or \code{-\var{signal}}, where
@@ -1684,6 +1699,10 @@ and XP) this is the exit status of the command run; on systems using
 a non-native shell, consult your shell documentation.
 
 Availability: Macintosh, \UNIX, Windows.
+
+The \module{subprocess} module provides more powerful facilities for
+spawning new processes and retrieving their results; using that module
+is preferable to using this function.
 \end{funcdesc}
 
 \begin{funcdesc}{times}{}
diff --git a/Doc/lib/libpopen2.tex b/Doc/lib/libpopen2.tex
index 985f580451b..fa0c1a60eda 100644
--- a/Doc/lib/libpopen2.tex
+++ b/Doc/lib/libpopen2.tex
@@ -11,10 +11,10 @@ This module allows you to spawn processes and connect to their
 input/output/error pipes and obtain their return codes under
 \UNIX{} and Windows.
 
-Note that starting with Python 2.0, this functionality is available
-using functions from the \refmodule{os} module which have the same
-names as the factory functions here, but the order of the return
-values is more intuitive in the \refmodule{os} module variants.
+The \module{subprocess} module provides more powerful facilities for
+spawning new processes and retrieving their results.  Using the
+\module{subprocess} module is preferable to using the \module{popen2}
+module.
 
 The primary interface offered by this module is a trio of factory
 functions.  For each of these, if \var{bufsize} is specified, 
@@ -184,3 +184,7 @@ integrate I/O over pipes with their \function{select()} loops, or use
 separate threads to read each of the individual files provided by
 whichever \function{popen*()} function or \class{Popen*} class was
 used.
+
+\begin{seealso}
+  \seemodule{subprocess}{Module for spawning and managing subprocesses.}
+\end{seealso}
diff --git a/Doc/lib/libsubprocess.tex b/Doc/lib/libsubprocess.tex
index 03072f7258a..f6397105acb 100644
--- a/Doc/lib/libsubprocess.tex
+++ b/Doc/lib/libsubprocess.tex
@@ -12,9 +12,6 @@ connect to their input/output/error pipes, and obtain their return
 codes.  This module intends to replace several other, older modules
 and functions, such as:
 
-% XXX Should add pointers to this module to at least the popen2
-% and commands sections.
-
 \begin{verbatim}
 os.system
 os.spawn*