Merged revisions 86521,86632,86823-86824,87294,87296,87300,87302 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/branches/py3k

........
  r86521 | eric.araujo | 2010-11-18 17:38:46 +0100 (jeu., 18 nov. 2010) | 17 lines

  Fix usage of :option: in the docs (#9312).

  :option: is used to create a link to an option of python, not to mark
  up any instance of any arbitrary command-line option.  These were
  changed to ````.

  For modules which do have a command-line interface, lists of options
  have been properly marked up with the program/cmdoption directives
  combo.  Options defined in such blocks can be linked to with :option:
  later in the same file, they won’t link to an option of python.

  Finally, the markup of command-line fragments in optparse.rst has
  been cleaned to use ``x`` instead of ``"x"``, keeping that latter
  form for actual Python strings.

  Patch by Eli Bendersky and Éric Araujo.
........
  r86632 | eric.araujo | 2010-11-21 04:09:17 +0100 (dim., 21 nov. 2010) | 2 lines

  Style edits in followup to r86521 (#9312)
........
  r86823 | eric.araujo | 2010-11-27 00:31:07 +0100 (sam., 27 nov. 2010) | 2 lines

  Use link-generating markup (see #9312)
........
  r86824 | eric.araujo | 2010-11-27 00:46:18 +0100 (sam., 27 nov. 2010) | 2 lines

  Rewrap long lines + minor edits
........
  r87294 | eric.araujo | 2010-12-16 01:07:01 +0100 (jeu., 16 déc. 2010) | 2 lines

  No need to generate a link for something that’s just above.
........
  r87296 | eric.araujo | 2010-12-16 01:23:30 +0100 (jeu., 16 déc. 2010) | 2 lines

  Advertise “python -m” instead of direct filename.
........
  r87300 | eric.araujo | 2010-12-16 02:40:26 +0100 (jeu., 16 déc. 2010) | 2 lines

  Advertise “python -m test” over test.regrtest (r87296 followup)
........
  r87302 | eric.araujo | 2010-12-16 03:10:11 +0100 (jeu., 16 déc. 2010) | 2 lines

  Add versionadded directive missing from r78983.
........

Doc/library/codecs.rst

@@ -788,7 +788,7 @@ Encodings and Unicode
 
 Strings are stored internally as sequences of codepoints (to be precise
 as :ctype:`Py_UNICODE` arrays). Depending on the way Python is compiled (either
-via :option:`--without-wide-unicode` or :option:`--with-wide-unicode`, with the
+via ``--without-wide-unicode`` or ``--with-wide-unicode``, with the
 former being the default) :ctype:`Py_UNICODE` is either a 16-bit or 32-bit data
 type. Once a string object is used outside of CPU and memory, CPU endianness
 and how these arrays are stored as bytes become an issue.  Transforming a

Doc/library/compileall.rst

@@ -10,14 +10,44 @@ libraries.  These functions compile Python source files in a directory tree,
 allowing users without permission to write to the libraries to take advantage of
 cached byte-code files.
 
-This module may also be used as a script (using the :option:`-m` Python flag) to
-compile Python sources.  Directories to recursively traverse (passing
-:option:`-l` stops the recursive behavior) for sources are listed on the command
-line.  If no arguments are given, the invocation is equivalent to ``-l
-sys.path``.  Printing lists of the files compiled can be disabled with the
-:option:`-q` flag.  In addition, the :option:`-x` option takes a regular
-expression argument.  All files that match the expression will be skipped.
 
+Command-line use
+----------------
+
+This module can work as a script (using :program:`python -m compileall`) to
+compile Python sources.
+
+.. program:: compileall
+
+.. cmdoption:: [directory|file]...
+
+   Positional arguments are files to compile or directories that contain
+   source files, traversed recursively.  If no argument is given, behave as if
+   the command line was ``-l <directories from sys.path>``.
+
+.. cmdoption:: -l
+
+   Do not recurse.
+
+.. cmdoption:: -f
+
+   Force rebuild even if timestamps are up-to-date.
+
+.. cmdoption:: -q
+
+   Do not print the list of files compiled.
+
+.. cmdoption:: -d destdir
+
+   Purported directory name for error messages.
+
+.. cmdoption:: -x regex
+
+   Skip files with a full path that matches given regular expression.
+
+
+Public functions
+----------------
 
 .. function:: compile_dir(dir, maxlevels=10, ddir=None, force=False, rx=None, quiet=False)
 
@@ -34,7 +64,6 @@ expression argument.  All files that match the expression will be skipped.
    If *quiet* is true, nothing is printed to the standard output in normal
    operation.
 
-
 .. function:: compile_path(skip_curdir=True, maxlevels=0, force=False)
 
    Byte-compile all the :file:`.py` files found along ``sys.path``. If
@@ -58,4 +87,3 @@ subdirectory and all its subdirectories::
 
    Module :mod:`py_compile`
       Byte-compile a single source file.
-

Doc/library/doctest.rst

@@ -88,7 +88,7 @@ works its magic::
    $
 
 There's no output!  That's normal, and it means all the examples worked.  Pass
-:option:`-v` to the script, and :mod:`doctest` prints a detailed log of what
+``-v`` to the script, and :mod:`doctest` prints a detailed log of what
 it's trying, and prints a summary at the end::
 
    $ python example.py -v
@@ -151,7 +151,7 @@ example(s) and the cause(s) of the failure(s) are printed to stdout, and the
 final line of output is ``***Test Failed*** N failures.``, where *N* is the
 number of examples that failed.
 
-Run it with the :option:`-v` switch instead::
+Run it with the ``-v`` switch instead::
 
    python M.py -v
 
@@ -160,7 +160,7 @@ with assorted summaries at the end.
 
 You can force verbose mode by passing ``verbose=True`` to :func:`testmod`, or
 prohibit it by passing ``verbose=False``.  In either of those cases,
-``sys.argv`` is not examined by :func:`testmod` (so passing :option:`-v` or not
+``sys.argv`` is not examined by :func:`testmod` (so passing ``-v`` or not
 has no effect).
 
 There is also a command line shortcut for running :func:`testmod`.  You can
@@ -229,7 +229,7 @@ See section :ref:`doctest-basic-api` for a description of the optional arguments
 that can be used to tell it to look for files in other locations.
 
 Like :func:`testmod`, :func:`testfile`'s verbosity can be set with the
-:option:`-v` command-line switch or with the optional keyword argument
+``-v`` command-line switch or with the optional keyword argument
 *verbose*.
 
 There is also a command line shortcut for running :func:`testfile`.  You can
@@ -1361,7 +1361,7 @@ DocTestRunner objects
    verbosity.  If *verbose* is ``True``, then information is printed about each
    example, as it is run.  If *verbose* is ``False``, then only failures are
    printed.  If *verbose* is unspecified, or ``None``, then verbose output is used
-   iff the command-line switch :option:`-v` is used.
+   iff the command-line switch ``-v`` is used.
 
    The optional keyword argument *optionflags* can be used to control how the test
    runner compares expected output to actual output, and how it displays failures.

Doc/library/exceptions.rst

@@ -120,7 +120,7 @@ The following exceptions are the exceptions that are usually raised.
 
    Raised when a floating point operation fails.  This exception is always defined,
    but can only be raised when Python is configured with the
-   :option:`--with-fpectl` option, or the :const:`WANT_SIGFPE_HANDLER` symbol is
+   ``--with-fpectl`` option, or the :const:`WANT_SIGFPE_HANDLER` symbol is
    defined in the :file:`pyconfig.h` file.
 
 

Doc/library/getopt.rst

@@ -41,7 +41,7 @@ exception:
    empty string.  Long options on the command line can be recognized so long as
    they provide a prefix of the option name that matches exactly one of the
    accepted options.  For example, if *longopts* is ``['foo', 'frob']``, the
-   option :option:`--fo` will match as :option:`--foo`, but :option:`--f` will
+   option ``--fo`` will match as ``--foo``, but ``--f`` will
    not match uniquely, so :exc:`GetoptError` will be raised.
 
    The return value consists of two elements: the first is a list of ``(option,
@@ -62,7 +62,7 @@ exception:
    intermixed. The :func:`getopt` function stops processing options as soon as a
    non-option argument is encountered.
 
-   If the first character of the option string is '+', or if the environment
+   If the first character of the option string is ``'+'``, or if the environment
    variable :envvar:`POSIXLY_CORRECT` is set, then option processing stops as
    soon as a non-option argument is encountered.
 

Doc/library/idle.rst

@@ -286,13 +286,13 @@ Command line usage
 
 If there are arguments:
 
-#. If :option:`-e` is used, arguments are files opened for editing and
+#. If ``-e`` is used, arguments are files opened for editing and
    ``sys.argv`` reflects the arguments passed to IDLE itself.
 
-#. Otherwise, if :option:`-c` is used, all arguments are placed in
+#. Otherwise, if ``-c`` is used, all arguments are placed in
    ``sys.argv[1:...]``, with ``sys.argv[0]`` set to ``'-c'``.
 
-#. Otherwise, if neither :option:`-e` nor :option:`-c` is used, the first
+#. Otherwise, if neither ``-e`` nor ``-c`` is used, the first
    argument is a script which is executed with the remaining arguments in
    ``sys.argv[1:...]``  and ``sys.argv[0]`` set to the script name.  If the script
    name is '-', no script is executed but an interactive Python session is started;

Doc/library/pydoc.rst

@@ -41,25 +41,25 @@ produced for that file.
    executed on that occasion.  Use an ``if __name__ == '__main__':`` guard to
    only execute code when a file is invoked as a script and not just imported.
 
-Specifying a :option:`-w` flag before the argument will cause HTML documentation
+Specifying a ``-w`` flag before the argument will cause HTML documentation
 to be written out to a file in the current directory, instead of displaying text
 on the console.
 
-Specifying a :option:`-k` flag before the argument will search the synopsis
+Specifying a ``-k`` flag before the argument will search the synopsis
 lines of all available modules for the keyword given as the argument, again in a
 manner similar to the Unix :program:`man` command.  The synopsis line of a
 module is the first line of its documentation string.
 
 You can also use :program:`pydoc` to start an HTTP server on the local machine
-that will serve documentation to visiting Web browsers. :program:`pydoc`
-:option:`-p 1234` will start a HTTP server on port 1234, allowing you to browse
+that will serve documentation to visiting Web browsers. :program:`pydoc -p 1234`
+will start a HTTP server on port 1234, allowing you to browse
 the documentation at ``http://localhost:1234/`` in your preferred Web browser.
-:program:`pydoc` :option:`-g` will start the server and additionally bring up a
+:program:`pydoc -g` will start the server and additionally bring up a
 small :mod:`tkinter`\ -based graphical interface to help you search for
 documentation pages.
 
 When :program:`pydoc` generates documentation, it uses the current environment
-and path to locate modules.  Thus, invoking :program:`pydoc` :option:`spam`
+and path to locate modules.  Thus, invoking :program:`pydoc spam`
 documents precisely the version of the module you would get if you started the
 Python interpreter and typed ``import spam``.
 

Doc/library/sys.rst

@@ -162,7 +162,7 @@ always available.
 
    A string giving the site-specific directory prefix where the platform-dependent
    Python files are installed; by default, this is also ``'/usr/local'``.  This can
-   be set at build time with the :option:`--exec-prefix` argument to the
+   be set at build time with the ``--exec-prefix`` argument to the
    :program:`configure` script.  Specifically, all configuration files (e.g. the
    :file:`pyconfig.h` header file) are installed in the directory ``exec_prefix +
    '/lib/pythonversion/config'``, and shared library modules are installed in
@@ -617,7 +617,7 @@ always available.
 
    A string giving the site-specific directory prefix where the platform
    independent Python files are installed; by default, this is the string
-   ``'/usr/local'``.  This can be set at build time with the :option:`--prefix`
+   ``'/usr/local'``.  This can be set at build time with the ``--prefix``
    argument to the :program:`configure` script.  The main collection of Python
    library modules is installed in the directory ``prefix + '/lib/pythonversion'``
    while the platform independent header files (all except :file:`pyconfig.h`) are
@@ -795,7 +795,7 @@ always available.
 
    Activate dumping of VM measurements using the Pentium timestamp counter, if
    *on_flag* is true. Deactivate these dumps if *on_flag* is off. The function is
-   available only if Python was compiled with :option:`--with-tsc`. To understand
+   available only if Python was compiled with ``--with-tsc``. To understand
    the output of this dump, read :file:`Python/ceval.c` in the Python sources.
 
 

Doc/library/test.rst

@@ -154,33 +154,33 @@ guidelines to be followed:
 
 .. _regrtest:
 
-Running tests using :mod:`test.regrtest`
-----------------------------------------
+Running tests using the command-line interface
+----------------------------------------------
 
-:mod:`test.regrtest` can be used as a script to drive Python's regression test
-suite. Running the script by itself automatically starts running all regression
+The :mod:`test.regrtest` module can be run as a script to drive Python's regression
+test suite, thanks to the :option:`-m` option: :program:`python -m test.regrtest`.
+Running the script by itself automatically starts running all regression
 tests in the :mod:`test` package. It does this by finding all modules in the
 package whose name starts with ``test_``, importing them, and executing the
 function :func:`test_main` if present. The names of tests to execute may also be
 passed to the script. Specifying a single regression test (:program:`python
-regrtest.py` :option:`test_spam.py`) will minimize output and only print whether
+-m test.regrtest test_spam`) will minimize output and only print whether
 the test passed or failed and thus minimize output.
 
 Running :mod:`test.regrtest` directly allows what resources are available for
 tests to use to be set. You do this by using the :option:`-u` command-line
-option. Run :program:`python regrtest.py` :option:`-uall` to turn on all
-resources; specifying :option:`all` as an option for :option:`-u` enables all
+option. Run :program:`python -m test.regrtest -uall` to turn on all
+resources; specifying ``all`` as an option for ``-u`` enables all
 possible resources. If all but one resource is desired (a more common case), a
 comma-separated list of resources that are not desired may be listed after
-:option:`all`. The command :program:`python regrtest.py`
-:option:`-uall,-audio,-largefile` will run :mod:`test.regrtest` with all
-resources except the :option:`audio` and :option:`largefile` resources. For a
-list of all resources and more command-line options, run :program:`python
-regrtest.py` :option:`-h`.
+``all``. The command :program:`python -m test.regrtest -uall,-audio,-largefile`
+will run :mod:`test.regrtest` with all resources except the ``audio`` and
+``largefile`` resources. For a list of all resources and more command-line
+options, run :program:`python -m test.regrtest -h`.
 
 Some other ways to execute the regression tests depend on what platform the
-tests are being executed on. On Unix, you can run :program:`make` :option:`test`
-at the top-level directory where Python was built. On Windows, executing
+tests are being executed on. On Unix, you can run :program:`make test` at the
+top-level directory where Python was built. On Windows, executing
 :program:`rt.bat` from your :file:`PCBuild` directory will run all regression
 tests.
 

Doc/library/timeit.rst

@@ -117,27 +117,36 @@ When called as a program from the command line, the following form is used::
 
    python -m timeit [-n N] [-r N] [-s S] [-t] [-c] [-h] [statement ...]
 
-where the following options are understood:
+Where the following options are understood:
+
+.. program:: timeit
+
+.. cmdoption:: -n N, --number=N
 
--n N/:option:`--number=N`
    how many times to execute 'statement'
 
--r N/:option:`--repeat=N`
+.. cmdoption:: -r N, --repeat=N
+
    how many times to repeat the timer (default 3)
 
--s S/:option:`--setup=S`
-   statement to be executed once initially (default ``'pass'``)
+.. cmdoption:: -s S, --setup=S
+
+   statement to be executed once initially (default ``pass``)
+
+.. cmdoption:: -t, --time
 
--t/:option:`--time`
    use :func:`time.time` (default on all platforms but Windows)
 
--c/:option:`--clock`
+.. cmdoption:: -c, --clock
+
    use :func:`time.clock` (default on Windows)
 
--v/:option:`--verbose`
+.. cmdoption:: -v, --verbose
+
    print raw timing results; repeat for more digits precision
 
--h/:option:`--help`
+.. cmdoption:: -h, --help
+
    print a short usage message and exit
 
 A multi-line statement may be given by specifying each line as a separate

Doc/library/unittest.rst

@@ -143,7 +143,7 @@ example, :meth:`~TestCase.setUp` was used to create a fresh sequence for each
 test.
 
 The final block shows a simple way to run the tests. :func:`unittest.main`
-provides a command line interface to the test script.  When run from the command
+provides a command-line interface to the test script.  When run from the command
 line, the above script produces an output that looks like this::
 
    ...
@@ -176,6 +176,30 @@ are sufficient to meet many everyday testing needs.  The remainder of the
 documentation explores the full feature set from first principles.
 
 
+.. _unittest-command-line-interface:
+
+Command-Line Interface
+----------------------
+
+The unittest module can be used from the command line to run tests from
+modules, classes or even individual test methods::
+
+   python -m unittest test_module1 test_module2
+   python -m unittest test_module.TestClass
+   python -m unittest test_module.TestClass.test_method
+
+You can pass in a list with any combination of module names, and fully
+qualified class or method names.
+
+You can run tests with more detail (higher verbosity) by passing in the -v flag::
+
+   python -m unittest -v test_module
+
+For a list of all the command-line options::
+
+   python -m unittest -h
+
+
 .. _organizing-tests:
 
 Organizing test code

Doc/library/webbrowser.rst

@@ -31,8 +31,8 @@ browser and wait.
 
 The script :program:`webbrowser` can be used as a command-line interface for the
 module. It accepts an URL as the argument. It accepts the following optional
-parameters: :option:`-n` opens the URL in a new browser window, if possible;
-:option:`-t` opens the URL in a new browser page ("tab"). The options are,
+parameters: ``-n`` opens the URL in a new browser window, if possible;
+``-t`` opens the URL in a new browser page ("tab"). The options are,
 naturally, mutually exclusive.
 
 The following exception is defined:
@@ -64,7 +64,6 @@ The following functions are defined:
    Open *url* in a new window of the default browser, if possible, otherwise, open
    *url* in the only browser window.
 
-
 .. function:: open_new_tab(url)
 
    Open *url* in a new page ("tab") of the default browser, if possible, otherwise