diff -r 46cadd3955d0 Doc/library/argparse.rst
--- a/Doc/library/argparse.rst	Sat Mar 16 09:15:47 2013 -0700
+++ b/Doc/library/argparse.rst	Tue Apr 02 23:36:57 2013 -0700
@@ -868,6 +868,8 @@
      usage: PROG [-h] foo [foo ...]
      PROG: error: too few arguments
 
+.. _`argparse.REMAINDER`:
+
 * ``argparse.REMAINDER``.  All the remaining command-line arguments are gathered
   into a list.  This is commonly useful for command line utilities that dispatch
   to other command line utilities::
@@ -1250,8 +1252,8 @@
    created and how they are assigned. See the documentation for
    :meth:`add_argument` for details.
 
-   By default, the argument strings are taken from :data:`sys.argv`, and a new empty
-   :class:`Namespace` object is created for the attributes.
+   * args_ - List of strings to parse.  The default is taken from :data:`sys.argv`.
+   * namespace_ - An object to take the attributes.  The default is a new empty :class:`Namespace` object.
 
 
 Option value syntax
@@ -1390,6 +1392,7 @@
 
 An error is produced for arguments that could produce more than one options.
 
+.. _args:
 
 Beyond ``sys.argv``
 ^^^^^^^^^^^^^^^^^^^
@@ -1410,7 +1413,10 @@
    Namespace(accumulate=<built-in function max>, integers=[1, 2, 3, 4])
    >>> parser.parse_args('1 2 3 4 --sum'.split())
    Namespace(accumulate=<built-in function sum>, integers=[1, 2, 3, 4])
+   >>> parser.parse_args(args=['1', '2', '3', '4'])
+   Namespace(accumulate=<built-in function max>, integers=[1, 2, 3, 4])
 
+.. _namespace:
 
 The Namespace object
 ^^^^^^^^^^^^^^^^^^^^
@@ -1884,7 +1890,13 @@
 * Replace ``(options, args) = parser.parse_args()`` with ``args =
   parser.parse_args()`` and add additional :meth:`ArgumentParser.add_argument`
   calls for the positional arguments. Keep in mind that what was previously
-  called ``options``, now in :mod:`argparse` context is called ``args``.
+  called ``options``, now in the :mod:`argparse` context is called ``args``.
+
+* If ``optparse`` used ``allow_interspersed_args = False`` to dispatch to
+  other command line utilities, set ``nargs`` to `argparse.REMAINDER`_.
+
+* Alternatively use :meth:`~ArgumentParser.parse_known_args` to collect
+  unparsed argument strings in a separate list.
 
 * Replace callback actions and the ``callback_*`` keyword arguments with
   ``type`` or ``action`` arguments.