From fb45216da81610dc3166237a628cd7bf0db12f0a Mon Sep 17 00:00:00 2001 From: Martin Panter Date: Sat, 16 Apr 2016 04:59:38 +0000 Subject: [PATCH] Issue #26638: Fix links to some CLI options Disable inappropriate links to Python interpreter options. Also make CLI section label in timeit less ambiguous. --- Doc/distutils/apiref.rst | 8 ++++---- Doc/distutils/configfile.rst | 2 +- Doc/install/index.rst | 6 +++--- Doc/library/2to3.rst | 10 +++++----- Doc/library/timeit.rst | 6 +++--- Doc/library/warnings.rst | 2 +- Doc/whatsnew/2.2.rst | 2 +- Doc/whatsnew/2.3.rst | 6 +++--- Doc/whatsnew/2.4.rst | 4 ++-- Doc/whatsnew/2.5.rst | 6 +++--- Doc/whatsnew/2.7.rst | 8 ++++---- 11 files changed, 30 insertions(+), 30 deletions(-) diff --git a/Doc/distutils/apiref.rst b/Doc/distutils/apiref.rst index ae07f559e48..96a486b6235 100644 --- a/Doc/distutils/apiref.rst +++ b/Doc/distutils/apiref.rst @@ -314,12 +314,12 @@ This module provides the following functions. .. function:: gen_preprocess_options(macros, include_dirs) - Generate C pre-processor options (:option:`-D`, :option:`-U`, :option:`-I`) as + Generate C pre-processor options (:option:`-D`, :option:`!-U`, :option:`!-I`) as used by at least two types of compilers: the typical Unix compiler and Visual C++. *macros* is the usual thing, a list of 1- or 2-tuples, where ``(name,)`` - means undefine (:option:`-U`) macro *name*, and ``(name, value)`` means define + means undefine (:option:`!-U`) macro *name*, and ``(name, value)`` means define (:option:`-D`) macro *name* to *value*. *include_dirs* is just a list of - directory names to be added to the header file search path (:option:`-I`). + directory names to be added to the header file search path (:option:`!-I`). Returns a list of command-line options suitable for either Unix compilers or Visual C++. @@ -794,7 +794,7 @@ This module provides the :class:`UnixCCompiler` class, a subclass of * library search directories specified with :option:`-Ldir` -* compile handled by :program:`cc` (or similar) executable with :option:`-c` +* compile handled by :program:`cc` (or similar) executable with :option:`!-c` option: compiles :file:`.c` to :file:`.o` * link static library handled by :program:`ar` command (possibly with diff --git a/Doc/distutils/configfile.rst b/Doc/distutils/configfile.rst index 8faffe6c200..51d88971a4b 100644 --- a/Doc/distutils/configfile.rst +++ b/Doc/distutils/configfile.rst @@ -51,7 +51,7 @@ option values can be split across multiple lines simply by indenting the continuation lines. You can find out the list of options supported by a particular command with the -universal :option:`--help` option, e.g. :: +universal :option:`!--help` option, e.g. :: > python setup.py --help build_ext [...] diff --git a/Doc/install/index.rst b/Doc/install/index.rst index 7f3560a8a5c..1ffd480ac36 100644 --- a/Doc/install/index.rst +++ b/Doc/install/index.rst @@ -862,12 +862,12 @@ config file will apply. (Or if other commands that derive values from it are run, they will use the values in the config file.) You can find out the complete list of options for any command using the -:option:`--help` option, e.g.:: +:option:`!--help` option, e.g.:: python setup.py build --help and you can find out the complete list of global options by using -:option:`--help` without a command:: +:option:`!--help` without a command:: python setup.py --help @@ -924,7 +924,7 @@ Let's examine each of the fields in turn. to be in Objective C. * *cpparg* is an argument for the C preprocessor, and is anything starting with - :option:`-I`, :option:`-D`, :option:`-U` or :option:`-C`. + :option:`!-I`, :option:`-D`, :option:`!-U` or :option:`-C`. * *library* is anything ending in :file:`.a` or beginning with :option:`-l` or :option:`-L`. diff --git a/Doc/library/2to3.rst b/Doc/library/2to3.rst index 7ebc208efe1..9f59ddad867 100644 --- a/Doc/library/2to3.rst +++ b/Doc/library/2to3.rst @@ -56,7 +56,7 @@ Comments and exact indentation are preserved throughout the translation process. By default, 2to3 runs a set of :ref:`predefined fixers <2to3-fixers>`. The :option:`-l` flag lists all available fixers. An explicit set of fixers to run -can be given with :option:`-f`. Likewise the :option:`-x` explicitly disables a +can be given with :option:`-f`. Likewise the :option:`!-x` explicitly disables a fixer. The following example runs only the ``imports`` and ``has_key`` fixers:: $ 2to3 -f imports -f has_key example.py @@ -78,12 +78,12 @@ but 2to3 cannot fix automatically. In this case, 2to3 will print a warning beneath the diff for a file. You should address the warning in order to have compliant 3.x code. -2to3 can also refactor doctests. To enable this mode, use the :option:`-d` +2to3 can also refactor doctests. To enable this mode, use the :option:`!-d` flag. Note that *only* doctests will be refactored. This also doesn't require the module to be valid Python. For example, doctest like examples in a reST document could also be refactored with this option. -The :option:`-v` option enables output of more information on the translation +The :option:`!-v` option enables output of more information on the translation process. Since some print statements can be parsed as function calls or statements, 2to3 @@ -102,14 +102,14 @@ when not overwriting the input files. .. versionadded:: 2.7.3 The :option:`-o` option was added. -The :option:`-W` or :option:`--write-unchanged-files` flag tells 2to3 to always +The :option:`!-W` or :option:`--write-unchanged-files` flag tells 2to3 to always write output files even if no changes were required to the file. This is most useful with :option:`-o` so that an entire Python source tree is copied with translation from one directory to another. This option implies the :option:`-w` flag as it would not make sense otherwise. .. versionadded:: 2.7.3 - The :option:`-W` flag was added. + The :option:`!-W` flag was added. The :option:`--add-suffix` option specifies a string to append to all output filenames. The :option:`-n` flag is required when specifying this as backups diff --git a/Doc/library/timeit.rst b/Doc/library/timeit.rst index 2cb3c9d3c7b..e7b35489b14 100644 --- a/Doc/library/timeit.rst +++ b/Doc/library/timeit.rst @@ -16,7 +16,7 @@ -------------- This module provides a simple way to time small bits of Python code. It has both -a :ref:`command-line-interface` as well as a :ref:`callable ` +a :ref:`timeit-command-line-interface` as well as a :ref:`callable ` one. It avoids a number of common traps for measuring execution times. See also Tim Peters' introduction to the "Algorithms" chapter in the *Python Cookbook*, published by O'Reilly. @@ -25,7 +25,7 @@ Cookbook*, published by O'Reilly. Basic Examples -------------- -The following example shows how the :ref:`command-line-interface` +The following example shows how the :ref:`timeit-command-line-interface` can be used to compare three different expressions: .. code-block:: sh @@ -170,7 +170,7 @@ The module defines three convenience functions and a public class: where the traceback is sent; it defaults to :data:`sys.stderr`. -.. _command-line-interface: +.. _timeit-command-line-interface: Command-Line Interface ---------------------- diff --git a/Doc/library/warnings.rst b/Doc/library/warnings.rst index 27658d64f45..40a0770d4d7 100644 --- a/Doc/library/warnings.rst +++ b/Doc/library/warnings.rst @@ -256,7 +256,7 @@ Updating Code For New Versions of Python Warnings that are only of interest to the developer are ignored by default. As such you should make sure to test your code with typically ignored warnings -made visible. You can do this from the command-line by passing :option:`-Wd` +made visible. You can do this from the command-line by passing :option:`-Wd <-W>` to the interpreter (this is shorthand for :option:`-W default`). This enables default handling for all warnings, including those that are ignored by default. To change what action is taken for encountered warnings you simply change what diff --git a/Doc/whatsnew/2.2.rst b/Doc/whatsnew/2.2.rst index 516bed8ac02..421846de111 100644 --- a/Doc/whatsnew/2.2.rst +++ b/Doc/whatsnew/2.2.rst @@ -759,7 +759,7 @@ Here are the changes 2.2 introduces: * Python 2.2 supports some command-line arguments for testing whether code will works with the changed division semantics. Running python with :option:`-Q - warn` will cause a warning to be issued whenever division is applied to two + warn <-Q>` will cause a warning to be issued whenever division is applied to two integers. You can use this to find code that's affected by the change and fix it. By default, Python 2.2 will simply perform classic division without a warning; the warning will be turned on by default in Python 2.3. diff --git a/Doc/whatsnew/2.3.rst b/Doc/whatsnew/2.3.rst index aebd0e716fd..5db3e2489e2 100644 --- a/Doc/whatsnew/2.3.rst +++ b/Doc/whatsnew/2.3.rst @@ -1057,7 +1057,7 @@ Here are all of the changes that Python 2.3 makes to the core Python language. * A new warning, :exc:`PendingDeprecationWarning` was added to indicate features which are in the process of being deprecated. The warning will *not* be printed by default. To check for use of features that will be deprecated in the future, - supply :option:`-Walways::PendingDeprecationWarning::` on the command line or + supply :option:`-Walways::PendingDeprecationWarning:: <-W>` on the command line or use :func:`warnings.filterwarnings`. * The process of deprecating string-based exceptions, as in ``raise "Error @@ -1734,7 +1734,7 @@ The optparse Module The :mod:`getopt` module provides simple parsing of command-line arguments. The new :mod:`optparse` module (originally named Optik) provides more elaborate command-line parsing that follows the Unix conventions, automatically creates -the output for :option:`--help`, and can perform different actions for different +the output for :option:`!--help`, and can perform different actions for different options. You start by creating an instance of :class:`OptionParser` and telling it what @@ -1973,7 +1973,7 @@ Some of the more notable changes are: the Python program as part of its execution. * The :file:`regrtest.py` script now provides a way to allow "all resources - except *foo*." A resource name passed to the :option:`-u` option can now be + except *foo*." A resource name passed to the :option:`!-u` option can now be prefixed with a hyphen (``'-'``) to mean "remove this resource." For example, the option '``-uall,-bsddb``' could be used to enable the use of all resources except ``bsddb``. diff --git a/Doc/whatsnew/2.4.rst b/Doc/whatsnew/2.4.rst index 92855211181..00a996dcf90 100644 --- a/Doc/whatsnew/2.4.rst +++ b/Doc/whatsnew/2.4.rst @@ -1483,8 +1483,8 @@ Some of the changes to Python's build process and to the C API are: intended as an aid to people developing the Python core. Providing :option:`----enable-profiling` to the :program:`configure` script will let you profile the interpreter with :program:`gprof`, and providing the - :option:`----with-tsc` switch enables profiling using the Pentium's Time-Stamp- - Counter register. Note that the :option:`----with-tsc` switch is slightly + :option:`--with-tsc` switch enables profiling using the Pentium's Time-Stamp- + Counter register. Note that the :option:`--with-tsc` switch is slightly misnamed, because the profiling feature also works on the PowerPC platform, though that processor architecture doesn't call that register "the TSC register". (Contributed by Jeremy Hylton.) diff --git a/Doc/whatsnew/2.5.rst b/Doc/whatsnew/2.5.rst index 740432e30f6..c8fdf44713b 100644 --- a/Doc/whatsnew/2.5.rst +++ b/Doc/whatsnew/2.5.rst @@ -1095,7 +1095,7 @@ Here are all of the changes that Python 2.5 makes to the core Python language. log all the paths searched. In Python 2.5, a new :exc:`ImportWarning` warning is triggered when an import would have picked up a directory as a package but no :file:`__init__.py` was found. This warning is silently ignored by default; - provide the :option:`-Wd` option when running the Python executable to display + provide the :option:`-Wd <-W>` option when running the Python executable to display the warning message. (Implemented by Thomas Wouters.) * The list of base classes in a class definition can now be empty. As an @@ -1126,7 +1126,7 @@ or ``exit()`` will now exit the interpreter as they expect. (Implemented by Georg Brandl.) The Python executable now accepts the standard long options :option:`--help` -and :option:`--version`; on Windows, it also accepts the :option:`/?` option +and :option:`--version`; on Windows, it also accepts the :option:`/? <-?>` option for displaying a help message. (Implemented by Georg Brandl.) .. ====================================================================== @@ -1640,7 +1640,7 @@ complete list of changes, or look through the SVN logs for all the details. * The :mod:`webbrowser` module received a number of enhancements. It's now usable as a script with ``python -m webbrowser``, taking a URL as the argument; there are a number of switches to control the behaviour (:option:`-n` for a new - browser window, :option:`-t` for a new tab). New module-level functions, + browser window, :option:`!-t` for a new tab). New module-level functions, :func:`open_new` and :func:`open_new_tab`, were added to support this. The module's :func:`open` function supports an additional feature, an *autoraise* parameter that signals whether to raise the open window when possible. A number diff --git a/Doc/whatsnew/2.7.rst b/Doc/whatsnew/2.7.rst index 9ac9cd61a75..0e543e14003 100644 --- a/Doc/whatsnew/2.7.rst +++ b/Doc/whatsnew/2.7.rst @@ -1820,12 +1820,12 @@ Consult the :mod:`unittest` module documentation for more details. The :func:`~unittest.main` function supports some other new options: -* :option:`-b` or :option:`--buffer` will buffer the standard output +* :option:`-b ` or :option:`--buffer` will buffer the standard output and standard error streams during each test. If the test passes, any resulting output will be discarded; on failure, the buffered output will be displayed. -* :option:`-c` or :option:`--catch` will cause the control-C interrupt +* :option:`-c ` or :option:`--catch` will cause the control-C interrupt to be handled more gracefully. Instead of interrupting the test process immediately, the currently running test will be completed and then the partial results up to the interruption will be reported. @@ -1839,7 +1839,7 @@ The :func:`~unittest.main` function supports some other new options: :func:`~unittest.removeHandler` decorator that can be used to mark tests that should have the control-C handling disabled. -* :option:`-f` or :option:`--failfast` makes +* :option:`-f ` or :option:`--failfast` makes test execution stop immediately when a test fails instead of continuing to execute further tests. (Suggested by Cliff Dyer and implemented by Michael Foord; :issue:`8074`.) @@ -2381,7 +2381,7 @@ Other Changes and Fixes takes an integer specifying how many tests run in parallel. This allows reducing the total runtime on multi-core machines. This option is compatible with several other options, including the - :option:`-R` switch which is known to produce long runtimes. + :option:`!-R` switch which is known to produce long runtimes. (Added by Antoine Pitrou, :issue:`6152`.) This can also be used with a new :option:`-F` switch that runs selected tests in a loop until they fail. (Added by Antoine Pitrou; :issue:`7312`.)