Update command line usage documentation to reflect 2.6 changes (also includes…

Update command line usage documentation to reflect 2.6 changes (also includes some minor cleanups). Addresses TODO list issue 2258

Doc/using/cmdline.rst

@@ -28,20 +28,25 @@ The most common use case is, of course, a simple invocation of a script::
     python myscript.py
 
 
+.. _using-on-interface-options:
+
 Interface options
 ~~~~~~~~~~~~~~~~~
 
-The interpreter interface resembles that of the UNIX shell:
+The interpreter interface resembles that of the UNIX shell, but provides some
+additional methods of invocation:
 
 * When called with standard input connected to a tty device, it prompts for
   commands and executes them until an EOF (an end-of-file character, you can
   produce that with *Ctrl-D* on UNIX or *Ctrl-Z, Enter* on Windows) is read.
 * When called with a file name argument or with a file as standard input, it
   reads and executes a script from that file.
+* When called with a directory name argument, it reads and executes an
+  appropriately named script from that directory.
 * When called with ``-c command``, it executes the Python statement(s) given as
   *command*.  Here *command* may contain multiple statements separated by
   newlines. Leading whitespace is significant in Python statements!
-* When called with ``-m module-name``, the given module is searched on the
+* When called with ``-m module-name``, the given module is located on the
   Python module path and executed as a script.
 
 In non-interactive mode, the entire input is parsed before it is executed.
@@ -58,25 +63,31 @@ source.
    normal module code.
    
    If this option is given, the first element of :data:`sys.argv` will be
-   ``"-c"``.
+   ``"-c"`` and the current directory will be added to the start of
+   :data:`sys.path` (allowing modules in that directory to be imported as top
+   level modules).
 
 
 .. cmdoption:: -m <module-name>
 
-   Search :data:`sys.path` for the named module and run the corresponding module
-   file as if it were executed with ``python modulefile.py`` as a script.
+   Search :data:`sys.path` for the named module and execute its contents as
+   the :mod:`__main__` module.
    
    Since the argument is a *module* name, you must not give a file extension
-   (``.py``).  However, the ``module-name`` does not have to be a valid Python
-   identifer (e.g. you can use a file name including a hyphen).
+   (``.py``).  The ``module-name`` should be a valid Python module name, but
+   the implementation may not always enforce this (e.g. it may allow you to
+   use a name that includes a hyphen).
 
    .. note::
 
       This option cannot be used with builtin modules and extension modules
-      written in C, since they do not have Python module files.
+      written in C, since they do not have Python module files. However, it
+      can still be used for precompiled modules, even if the original source
+      file is not available.
    
    If this option is given, the first element of :data:`sys.argv` will be the
-   full path to the module file.
+   full path to the module file. As with the :option:`-c` option, the current
+   directory will be added to the start of :data:`sys.path`.
    
    Many standard library modules contain code that is invoked on their execution
    as a script.  An example is the :mod:`timeit` module::
@@ -90,34 +101,52 @@ source.
 
       :pep:`338` -- Executing modules as scripts
 
+   .. versionadded:: 2.4
+
    .. versionchanged:: 2.5
-      The module name can now include packages.
+      The named module can now be located inside a package.
+
+
+.. describe:: -
+
+   Read commands from standard input (:data:`sys.stdin`).  If standard input is
+   a terminal, :option:`-i` is implied.
+
+   If this option is given, the first element of :data:`sys.argv` will be
+   ``"-"`` and the current directory will be added to the start of
+   :data:`sys.path`.
 
 
 .. describe:: <script>
 
-   Execute the Python code contained in *script*, which must be an (absolute or
-   relative) file name.
+   Execute the Python code contained in *script*, which must be a filesystem
+   path (absolute or relative) referring to either a Python file, a directory
+   containing a ``__main__.py`` file, or a zipfile containing a
+   ``__main__.py`` file.
 
    If this option is given, the first element of :data:`sys.argv` will be the
-   script file name as given on the command line.
+   script name as given on the command line.
 
+   If the script name refers directly to a Python file, the directory
+   containing that file is added to the start of :data:`sys.path`, and the
+   file is executed as the :mod:`__main__` module.
 
-.. describe:: -
+   If the script name refers to a directory or zipfile, the script name is
+   added to the start of :data:`sys.path` and the ``__main__.py`` file in
+   that location is executed as the :mod:`__main__` module.
 
-   Read commands from standard input (:data:`sys.stdin`).  If standard input is
-   a terminal, :option:`-i` is implied.
+   .. versionchanged:: 2.5
+      Directories and zipfiles containing a ``__main__.py`` file at the top
+      level are now considered valid Python scripts.
 
-   If this option is given, the first element of :data:`sys.argv` will be
-   ``"-"``.
+If no interface option is given, :option:`-i` is implied, ``sys.argv[0]`` is
+an empty string (``""``) and the current directory will be added to the
+start of :data:`sys.path`.
 
    .. seealso:: 
       :ref:`tut-invoking`
 
 
-If no script name is given, ``sys.argv[0]`` is an empty string (``""``).
-
-
 Generic options
 ~~~~~~~~~~~~~~~
 
@@ -127,7 +156,7 @@ Generic options
 
    Print a short description of all command line options.
 
-   .. versionadded:: 2.5
+   .. versionchanged:: 2.5
       The ``--help`` variant.
 
 
@@ -138,7 +167,7 @@ Generic options
     
        Python 2.5.1
 
-   .. versionadded:: 2.5
+   .. versionchanged:: 2.5
       The ``--version`` variant.
 
 
@@ -302,6 +331,7 @@ Miscellaneous options
    thus equivalent to an omitted line number.
 
    .. seealso::
+      :mod:`warnings` -- the warnings module
 
       :pep:`230` -- Warning framework
 
@@ -358,14 +388,19 @@ These environment variables influence Python's behavior.
    the shell's :envvar:`PATH`: one or more directory pathnames separated by
    :data:`os.pathsep` (e.g. colons on Unix or semicolons on Windows).
    Non-existent directories are silently ignored.
+
+   In addition to normal directories, individual :envvar:`PYTHONPATH` entries
+   may refer to zipfiles containing pure Python modules (in either source or
+   compiled form). Extension modules cannot be imported from zipfiles.
    
    The default search path is installation dependent, but generally begins with
    :file:`{prefix}/lib/python{version}`` (see :envvar:`PYTHONHOME` above).  It
    is *always* appended to :envvar:`PYTHONPATH`.
    
-   If a script argument is given, the directory containing the script is
-   inserted in the path in front of :envvar:`PYTHONPATH`.  The search path can
-   be manipulated from within a Python program as the variable :data:`sys.path`.
+   An additional directory will be inserted in the search path in front of
+   :envvar:`PYTHONPATH` as described above under
+   :ref:`using-on-interface-options`. The search path can be manipulated from
+   within a Python program as the variable :data:`sys.path`.
 
 
 .. envvar:: PYTHONSTARTUP
@@ -451,7 +486,7 @@ if Python was configured with the :option:`--with-pydebug` build option.
 
 .. envvar:: PYTHONTHREADDEBUG
 
-   If set, Python will print debug threading debug info.
+   If set, Python will print threading debug info.
 
    .. versionchanged:: 2.6
       Previously, this variable was called ``THREADDEBUG``.