--- rest25/library/popen2.rst	2008-12-19 16:58:07.000000000 +0900
+++ rest262/library/popen2.rst	2009-04-05 05:02:09.000000000 +0900
@@ -1,29 +1,32 @@
 
 :mod:`popen2` --- Subprocesses with accessible I/O streams
 ==========================================================
 
 .. module:: popen2
-   :platform: Unix, Windows
    :synopsis: Subprocesses with accessible standard I/O streams.
+   :deprecated:
 .. sectionauthor:: Drew Csillag <drew_csillag@geocities.com>
 
 
+.. deprecated:: 2.6
+   This module is obsolete.  Use the :mod:`subprocess` module.  Check
+   especially the :ref:`subprocess-replacements` section.
+
 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 :mod:`os` module which have the same names as the factory
-functions here, but the order of the return values is more intuitive in the
-:mod:`os` module variants.
+The :mod:`subprocess` module provides more powerful facilities for spawning new
+processes and retrieving their results.  Using the :mod:`subprocess` module is
+preferable to using the :mod:`popen2` module.
 
 The primary interface offered by this module is a trio of factory functions.
 For each of these, if *bufsize* is specified,  it specifies the buffer size for
 the I/O pipes.  *mode*, if provided, should be the string ``'b'`` or ``'t'``; on
 Windows this is needed to determine whether the file objects should be opened in
 binary or text mode.  The default value for *mode* is ``'t'``.
 
 On Unix, *cmd* may be a sequence, in which case arguments will be passed
 directly to the program without shell intervention (as with :func:`os.spawnv`).
 If *cmd* is a string it will be passed to the shell (as with :func:`os.system`).
 
 The only way to retrieve the return codes for the child processes is by using
@@ -82,84 +85,84 @@
    .. versionadded:: 2.0
 
 
 .. _popen3-objects:
 
 Popen3 and Popen4 Objects
 -------------------------
 
 Instances of the :class:`Popen3` and :class:`Popen4` classes have the following
 methods:
 
 
-.. method:: XXX Class.poll()
+.. method:: Popen3.poll()
 
-   Returns ``-1`` if child process hasn't completed yet, or its return  code
-   otherwise.
+   Returns ``-1`` if child process hasn't completed yet, or its status code
+   (see :meth:`wait`) otherwise.
 
 
-.. method:: XXX Class.wait()
+.. method:: Popen3.wait()
 
    Waits for and returns the status code of the child process.  The status code
    encodes both the return code of the process and information about whether it
    exited using the :cfunc:`exit` system call or died due to a signal.  Functions
    to help interpret the status code are defined in the :mod:`os` module; see
    section :ref:`os-process` for the :func:`W\*` family of functions.
 
 The following attributes are also available:
 
 
-.. attribute:: XXX Class.fromchild
+.. attribute:: Popen3.fromchild
 
    A file object that provides output from the child process.  For :class:`Popen4`
    instances, this will provide both the standard output and standard error
    streams.
 
 
-.. attribute:: XXX Class.tochild
+.. attribute:: Popen3.tochild
 
    A file object that provides input to the child process.
 
 
-.. attribute:: XXX Class.childerr
+.. attribute:: Popen3.childerr
 
    A file object that provides error output from the child process, if
    *capturestderr* was true for the constructor, otherwise ``None``.  This will
    always be ``None`` for :class:`Popen4` instances.
 
 
-.. attribute:: XXX Class.pid
+.. attribute:: Popen3.pid
 
    The process ID of the child process.
 
 
 .. _popen2-flow-control:
 
 Flow Control Issues
 -------------------
 
 Any time you are working with any form of inter-process communication, control
 flow needs to be carefully thought out.  This remains the case with the file
 objects provided by this module (or the :mod:`os` module equivalents).
 
 When reading output from a child process that writes a lot of data to standard
 error while the parent is reading from the child's standard output, a deadlock
 can occur.  A similar situation can occur with other combinations of reads and
 writes.  The essential factors are that more than :const:`_PC_PIPE_BUF` bytes
 are being written by one process in a blocking fashion, while the other process
-is reading from the other process, also in a blocking fashion.
+is reading from the first process, also in a blocking fashion.
 
-.. % Example explanation and suggested work-arounds substantially stolen
-.. % from Martin von Löwis:
-.. % http://mail.python.org/pipermail/python-dev/2000-September/009460.html
+.. Example explanation and suggested work-arounds substantially stolen
+   from Martin von Löwis:
+   http://mail.python.org/pipermail/python-dev/2000-September/009460.html
 
 There are several ways to deal with this situation.
 
 The simplest application change, in many cases, will be to follow this model in
 the parent process::
 
    import popen2
 
    r, w, e = popen2.popen3('python slave.py')
    e.readlines()
    r.readlines()
    r.close()
@@ -179,12 +182,18 @@
    print >>sys.stdout, 400 * 'this is another test\n'
 
 In particular, note that ``sys.stderr`` must be closed after writing all data,
 or :meth:`readlines` won't return.  Also note that :func:`os.close` must be
 used, as ``sys.stderr.close()`` won't close ``stderr`` (otherwise assigning to
 ``sys.stderr`` will silently close it, so no further errors can be printed).
 
 Applications which need to support a more general approach should integrate I/O
 over pipes with their :func:`select` loops, or use separate threads to read each
 of the individual files provided by whichever :func:`popen\*` function or
 :class:`Popen\*` class was used.
 
+
+.. seealso::
+
+   Module :mod:`subprocess`
+      Module for spawning and managing subprocesses.
+
