--- subprocess_orig.rst	2010-02-01 19:56:52.000000000 -0800
+++ subprocess_old.rst	2010-02-02 05:58:22.000000000 -0800
@@ -46,15 +46,40 @@
    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 in particular that options (such as *-input*) and their arguments
+      (such as *eggs.txt*), when separated by whitespace in the shell, go in
+      separate list elements, while arguments that need quoting or escaping
+      when used in the shell (such as filenames containing spaces or the python
+      command shown above) are single list elements.
+
    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).
-
-   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.
+   item (the program to execute).  This means that unless the program is not
+   being given any arguments at all, the entire command should not be put into
+   one string (or a list containing only one string) as *args*.
+
+   On Unix, with *shell=True*:  If args is a string, it specifies the command
+   string to execute through the shell.  This means that the string must be
+   formatted exactly as it would be when typed at the shell prompt.  This
+   includes, for example, quoting filenames with spaces in them.  Additional
+   quoting may be required because the entire string is a Python string.  It
+   may be useful to use a Python raw string in complex cases.  If *args* is a
+   sequence, the first item specifies the command string, and any additional
+   items will be treated as additional arguments to the shell itself, following
+   the "-c" and the specified command string in the call to the shell.
 
    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