Follow-up to #4488: document PIPE and STDOUT properly.
diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
index 1a0f134..e0ab96d 100644
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -73,13 +73,13 @@
specified by the :envvar:`COMSPEC` environment variable.
*stdin*, *stdout* and *stderr* specify the executed programs' standard input,
- standard output and standard error file handles, respectively. Valid values are
- ``PIPE``, an existing file descriptor (a positive integer), an existing file
- object, and ``None``. ``PIPE`` indicates that a new pipe to the child should be
- created. With ``None``, no redirection will occur; the child's file handles
- will be inherited from the parent. Additionally, *stderr* can be ``STDOUT``,
- which indicates that the stderr data from the applications should be captured
- into the same file handle as for stdout.
+ standard output and standard error file handles, respectively. Valid values
+ are :data:`PIPE`, an existing file descriptor (a positive integer), an
+ existing file object, and ``None``. :data:`PIPE` indicates that a new pipe
+ to the child should be created. With ``None``, no redirection will occur;
+ the child's file handles will be inherited from the parent. Additionally,
+ *stderr* can be :data:`STDOUT`, which indicates that the stderr data from the
+ applications should be captured into the same file handle as for stdout.
If *preexec_fn* is set to a callable object, this object will be called in the
child process just before the child is executed. (Unix only)
@@ -119,6 +119,20 @@
of the main window and priority for the new process. (Windows only)
+.. data:: PIPE
+
+ Special value that can be used as the *stdin*, *stdout* or *stderr* argument
+ to :class:`Popen` and indicates that a pipe to the standard stream should be
+ opened.
+
+
+.. data:: STDOUT
+
+ Special value that can be used as the *stderr* argument to :class:`Popen` and
+ indicates that standard error should go into the same handle as standard
+ output.
+
+
Convenience Functions
^^^^^^^^^^^^^^^^^^^^^
@@ -285,20 +299,21 @@
.. attribute:: Popen.stdin
- If the *stdin* argument is ``PIPE``, this attribute is a file object that
- provides input to the child process. Otherwise, it is ``None``.
+ If the *stdin* argument was :data:`PIPE`, this attribute is a file object
+ that provides input to the child process. Otherwise, it is ``None``.
.. attribute:: Popen.stdout
- If the *stdout* argument is ``PIPE``, this attribute is a file object that
- provides output from the child process. Otherwise, it is ``None``.
+ If the *stdout* argument was :data:`PIPE`, this attribute is a file object
+ that provides output from the child process. Otherwise, it is ``None``.
.. attribute:: Popen.stderr
- If the *stderr* argument is ``PIPE``, this attribute is file object that
- provides error output from the child process. Otherwise, it is ``None``.
+ If the *stderr* argument was :data:`PIPE`, this attribute is a file object
+ that provides error output from the child process. Otherwise, it is
+ ``None``.
.. attribute:: Popen.pid
@@ -478,15 +493,15 @@
stdin=PIPE, stdout=PIPE, close_fds=True)
(child_stdout, child_stdin) = (p.stdout, p.stdin)
-The popen2.Popen3 and popen2.Popen4 basically works as subprocess.Popen, except
-that:
+:class:`popen2.Popen3` and :class:`popen2.Popen4` basically work as
+:class:`subprocess.Popen`, except that:
-* subprocess.Popen raises an exception if the execution fails
+* :class:`Popen` raises an exception if the execution fails.
* the *capturestderr* argument is replaced with the *stderr* argument.
-* stdin=PIPE and stdout=PIPE must be specified.
+* ``stdin=PIPE`` and ``stdout=PIPE`` must be specified.
* popen2 closes all file descriptors by default, but you have to specify
- close_fds=True with subprocess.Popen.
+ ``close_fds=True`` with :class:`Popen`.