--- rest25/library/commands.rst	2008-12-19 16:58:07.000000000 +0900
+++ rest262/library/commands.rst	2009-04-05 05:02:09.000000000 +0900
@@ -3,50 +3,71 @@
 ==================================================
 
 .. module:: commands
    :platform: Unix
    :synopsis: Utility functions for running external commands.
 .. sectionauthor:: Sue Williams <sbw@provis.com>
 
 
 The :mod:`commands` module contains wrapper functions for :func:`os.popen` which
 take a system command as a string and return any output generated by the command
 and, optionally, the exit status.
 
+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:`commands` module.
+
+.. warning::
+
+   In 3.x, :func:`getstatus` and two undocumented functions (:func:`mk2arg` and
+   :func:`mkarg`) have been removed.  Also, :func:`getstatusoutput` and
+   :func:`getoutput` have been moved to the :mod:`subprocess` module.
+
 The :mod:`commands` module defines the following functions:
 
 
 .. function:: getstatusoutput(cmd)
 
    Execute the string *cmd* in a shell with :func:`os.popen` and return a 2-tuple
    ``(status, output)``.  *cmd* is actually run as ``{ cmd ; } 2>&1``, so that the
    returned output will contain output or error messages. A trailing newline is
    stripped from the output. The exit status for the command can be interpreted
    according to the rules for the C function :cfunc:`wait`.
 
 
 .. function:: getoutput(cmd)
 
    Like :func:`getstatusoutput`, except the exit status is ignored and the return
    value is a string containing the command's output.
 
 
 .. function:: getstatus(file)
 
    Return the output of ``ls -ld file`` as a string.  This function uses the
    :func:`getoutput` function, and properly escapes backslashes and dollar signs in
    the argument.
 
+   .. deprecated:: 2.6
+      This function is nonobvious and useless.  The name is also misleading in the
+      presence of :func:`getstatusoutput`.
+
+
 Example::
 
    >>> import commands
    >>> commands.getstatusoutput('ls /bin/ls')
    (0, '/bin/ls')
    >>> commands.getstatusoutput('cat /bin/junk')
    (256, 'cat: /bin/junk: No such file or directory')
    >>> commands.getstatusoutput('/bin/junk')
    (256, 'sh: /bin/junk: not found')
    >>> commands.getoutput('ls /bin/ls')
    '/bin/ls'
    >>> commands.getstatus('/bin/ls')
    '-rwxr-xr-x  1 root        13352 Oct 14  1994 /bin/ls'
 
+
+.. seealso::
+
+   Module :mod:`subprocess`
+      Module for spawning and managing subprocesses.
+
