bpo-43862: Enhance -W cmdline option documentation (GH-25439)

The -W format is "action:message:category:module:lineno".

Update also the Python manual page.

1 files changed, 40 insertions, 23 deletions

diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst
index a39cfd6..09d8fa9 100644
--- a/Doc/using/cmdline.rst
+++ b/Doc/using/cmdline.rst
@@ -380,25 +380,8 @@ Miscellaneous options
 .. _using-on-warnings:
 .. cmdoption:: -W arg
 
-   Warning control.  Python's warning machinery by default prints warning
-   messages to :data:`sys.stderr`.  A typical warning message has the following
-   form:
-
-   .. code-block:: none
-
-       file:line: category: message
-
-   By default, each warning is printed once for each source line where it
-   occurs.  This option controls how often warnings are printed.
-
-   Multiple :option:`-W` options may be given; when a warning matches more than
-   one option, the action for the last matching option is performed.  Invalid
-   :option:`-W` options are ignored (though, a warning message is printed about
-   invalid options when the first warning is issued).
-
-   Warnings can also be controlled using the :envvar:`PYTHONWARNINGS`
-   environment variable and from within a Python program using the
-   :mod:`warnings` module.
+   Warning control. Python's warning machinery by default prints warning
+   messages to :data:`sys.stderr`.
 
    The simplest settings apply a particular action unconditionally to all
    warnings emitted by a process (even those that are otherwise ignored by
@@ -411,14 +394,48 @@ Miscellaneous options
        -Wonce     # Warn once per Python process
        -Wignore   # Never warn
 
-   The action names can be abbreviated as desired (e.g. ``-Wi``, ``-Wd``,
-   ``-Wa``, ``-We``) and the interpreter will resolve them to the appropriate
-   action name.
+   The action names can be abbreviated as desired and the interpreter will
+   resolve them to the appropriate action name. For example, ``-Wi`` is the
+   same as ``-Wignore``.
+
+   The full form of argument is::
+
+       action:message:category:module:lineno
+
+   Empty fields match all values; trailing empty fields may be omitted. For
+   example ``-W ignore::DeprecationWarning`` ignores all DeprecationWarning
+   warnings.
+
+   The *action* field is as explained above but only applies to warnings that
+   match the remaining fields.
+
+   The *message* field must match the whole warning message; this match is
+   case-insensitive.
+
+   The *category* field matches the warning category
+   (ex: ``DeprecationWarning``). This must be a class name; the match test
+   whether the actual warning category of the message is a subclass of the
+   specified warning category.
+
+   The *module* field matches the (fully-qualified) module name; this match is
+   case-sensitive.
+
+   The *lineno* field matches the line number, where zero matches all line
+   numbers and is thus equivalent to an omitted line number.
+
+   Multiple :option:`-W` options can be given; when a warning matches more than
+   one option, the action for the last matching option is performed. Invalid
+   :option:`-W` options are ignored (though, a warning message is printed about
+   invalid options when the first warning is issued).
+
+   Warnings can also be controlled using the :envvar:`PYTHONWARNINGS`
+   environment variable and from within a Python program using the
+   :mod:`warnings` module. For example, the :func:`warnings.filterwarnings`
+   function can be used to use a regular expression on the warning message.
 
    See :ref:`warning-filter` and :ref:`describing-warning-filters` for more
    details.
 
-
 .. cmdoption:: -x
 
    Skip the first line of the source, allowing use of non-Unix forms of