--- subprocess_orig.rst	2010-02-01 19:56:52.000000000 -0800
+++ subprocess_old.rst	2010-02-01 19:56:38.000000000 -0800
@@ -46,16 +46,65 @@
    different from the actual executable name.  On Unix, it becomes the display
    name for the executing program in utilities such as :program:`ps`.
 
+   .. note::
+   
+      :meth:`shlex.split` can be useful when determining the correct tokenization
+      for *args*, especially in complex cases::
+      
+         >>> import shlex, subprocess
+         >>> command_line = raw_input()
+         /bin/vikings -input eggs.txt -output "spam spam.txt" -cmd "python -c 'print __name__'"
+         >>> shlex.split(command_line)
+         ['/bin/vikings', '-input', 'eggs.txt', '-output', 'spam spam.txt', '-cmd', "python -c 'print __name__'"]
+         >>> p = subprocess.Popen(['/bin/vikings', '-input', 'eggs.txt', '-output', 'spam spam.txt', '-cmd', "python -c 'print __name__'"]) # Success!
+
+   .. note::
+   
+      Do not put an argument-taking option together with its argument as a
+      single item in the *args* list::
+
+         >>> subprocess.Popen(['/bin/vikings', '-input eggs.txt']) # Wrong
+
+      Because that is incorrect::
+      
+         >>> shlex.split('/bin/vikings -input eggs.txt') # Let's see what shlex() says is right...
+         ['/bin/vikings', '-input', 'eggs.txt']
+
    On Unix, with *shell=False* (default): In this case, the Popen class uses
    :meth:`os.execvp` to execute the child program. *args* should normally be a
    sequence.  A string will be treated as a sequence with the string as the only
    item (the program to execute).
 
+   .. note::
+
+      Unless the program is not being given any arguments at all, the entire
+      command should not be put into one string as *args* when *shell=False*::
+
+         >>> p1 = Popen(args="/bin/vikings -input eggs.txt")
+         Traceback (most recent call last):
+         ...
+         OSError: [Errno 2] No such file or directory
+         >>> p2 = Popen(args=["/bin/vikings -input eggs.txt"])
+         Traceback (most recent call last):
+         ...
+         OSError: [Errno 2] No such file or directory
+      
+      In these cases, the system is trying to execute an (obviously nonexistent)
+      program whose name/path includes the entire command string, arguments and
+      all.
+
    On Unix, with *shell=True*: If args is a string, it specifies the command string
    to execute through the shell.  If *args* is a sequence, the first item specifies
    the command string, and any additional items will be treated as additional shell
    arguments.
 
+   .. note::
+
+      When using *shell=True*, characters of special meaning to the shell must be
+      escaped in the command string when necessary.  In particular, spaces in
+      filenames must be escaped. Using *shell=False* avoids the need to do any such
+      escaping.
+
    On Windows: the :class:`Popen` class uses CreateProcess() to execute the child
    program, which operates on strings.  If *args* is a sequence, it will be
    converted to a string using the :meth:`list2cmdline` method.  Please note that