diff -r fa6b9bd60cce Doc/library/pipes.rst
--- a/Doc/library/pipes.rst	Sun Oct 28 08:18:52 2012 +0100
+++ b/Doc/library/pipes.rst	Sun Oct 28 02:03:34 2012 -0700
@@ -16,8 +16,6 @@
 Because the module uses :program:`/bin/sh` command lines, a POSIX or compatible
 shell for :func:`os.system` and :func:`os.popen` is required.
 
-The :mod:`pipes` module defines the following class:
-
 
 .. class:: Template()
 
@@ -35,6 +33,43 @@
    'HELLO WORLD'
 
 
+.. function:: quote(s)
+
+   .. deprecated:: 1.6
+      Prior to Python 2.7, this function was not publicly documented.  It is
+      finally exposed publicly in Python 3.3 as the
+      :func:`quote <shlex.quote>` function in the :mod:`shlex` module.
+
+   Return a shell-escaped version of the string *s*.  The returned value is a
+   string that can safely be used as one token in a shell command line, for
+   cases where you cannot use a list.
+
+   This idiom would be unsafe::
+
+      >>> filename = 'somefile; rm -rf ~'
+      >>> command = 'ls -l {}'.format(filename)
+      >>> print command  # executed by a shell: boom!
+      ls -l somefile; rm -rf ~
+
+   :func:`quote` lets you plug the security hole::
+
+      >>> command = 'ls -l {}'.format(quote(filename))
+      >>> print command
+      ls -l 'somefile; rm -rf ~'
+      >>> remote_command = 'ssh home {}'.format(quote(command))
+      >>> print remote_command
+      ssh home 'ls -l '"'"'somefile; rm -rf ~'"'"''
+
+   The quoting is compatible with UNIX shells and with :func:`shlex.split`:
+
+      >>> remote_command = shlex.split(remote_command)
+      >>> remote_command
+      ['ssh', 'home', "ls -l 'somefile; rm -rf ~'"]
+      >>> command = shlex.split(remote_command[-1])
+      >>> command
+      ['ls', '-l', 'somefile; rm -rf ~']
+
+
 .. _template-objects:
 
 Template Objects