bpo-9694: Fix misleading phrase "optional arguments" (GH-23858)

2 files changed, 39 insertions, 38 deletions

diff --git a/Doc/howto/argparse.rst b/Doc/howto/argparse.rst
index 76d8e6b..a97d10c 100644
--- a/Doc/howto/argparse.rst
+++ b/Doc/howto/argparse.rst
@@ -83,7 +83,7 @@ Following is a result of running the code:
    $ python3 prog.py --help
    usage: prog.py [-h]
 
-   optional arguments:
+   options:
      -h, --help  show this help message and exit
    $ python3 prog.py --verbose
    usage: prog.py [-h]
@@ -130,7 +130,7 @@ And running the code:
    positional arguments:
      echo
 
-   optional arguments:
+   options:
      -h, --help  show this help message and exit
    $ python3 prog.py foo
    foo
@@ -172,7 +172,7 @@ And we get:
    positional arguments:
      echo        echo the string you use here
 
-   optional arguments:
+   options:
      -h, --help  show this help message and exit
 
 Now, how about doing something even more useful::
@@ -241,7 +241,7 @@ And the output:
    $ python3 prog.py --help
    usage: prog.py [-h] [--verbosity VERBOSITY]
 
-   optional arguments:
+   options:
      -h, --help            show this help message and exit
      --verbosity VERBOSITY
                            increase output verbosity
@@ -289,7 +289,7 @@ And the output:
    $ python3 prog.py --help
    usage: prog.py [-h] [--verbose]
 
-   optional arguments:
+   options:
      -h, --help  show this help message and exit
      --verbose   increase output verbosity
 
@@ -332,7 +332,7 @@ And here goes:
    $ python3 prog.py --help
    usage: prog.py [-h] [-v]
 
-   optional arguments:
+   options:
      -h, --help     show this help message and exit
      -v, --verbose  increase output verbosity
 
@@ -440,7 +440,7 @@ And the output:
    positional arguments:
      square                display a square of a given number
 
-   optional arguments:
+   options:
      -h, --help            show this help message and exit
      -v {0,1,2}, --verbosity {0,1,2}
                            increase output verbosity
@@ -468,7 +468,8 @@ verbosity argument (check the output of ``python --help``)::
        print(answer)
 
 We have introduced another action, "count",
-to count the number of occurrences of a specific optional arguments:
+to count the number of occurrences of specific options.
+
 
 .. code-block:: shell-session
 
@@ -489,7 +490,7 @@ to count the number of occurrences of a specific optional arguments:
    positional arguments:
      square           display a square of a given number
 
-   optional arguments:
+   options:
      -h, --help       show this help message and exit
      -v, --verbosity  increase output verbosity
    $ python3 prog.py 4 -vvv
@@ -626,7 +627,7 @@ Output:
      x                the base
      y                the exponent
 
-   optional arguments:
+   options:
      -h, --help       show this help message and exit
      -v, --verbosity
    $ python3 prog.py 4 2 -v
@@ -750,7 +751,7 @@ but not both at the same time:
      x              the base
      y              the exponent
 
-   optional arguments:
+   options:
      -h, --help     show this help message and exit
      -v, --verbose
      -q, --quiet
diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index 4542961..80e0f01 100644
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -57,7 +57,7 @@ be run at the command line and provides useful help messages:
    positional arguments:
     N           an integer for the accumulator
 
-   optional arguments:
+   options:
     -h, --help  show this help message and exit
     --sum       sum the integers (default: find the max)
 
@@ -217,14 +217,14 @@ The help for this program will display ``myprogram.py`` as the program name
    $ python myprogram.py --help
    usage: myprogram.py [-h] [--foo FOO]
 
-   optional arguments:
+   options:
     -h, --help  show this help message and exit
     --foo FOO   foo help
    $ cd ..
    $ python subdir/myprogram.py --help
    usage: myprogram.py [-h] [--foo FOO]
 
-   optional arguments:
+   options:
     -h, --help  show this help message and exit
     --foo FOO   foo help
 
@@ -235,7 +235,7 @@ To change this default behavior, another value can be supplied using the
    >>> parser.print_help()
    usage: myprogram [-h]
 
-   optional arguments:
+   options:
     -h, --help  show this help message and exit
 
 Note that the program name, whether determined from ``sys.argv[0]`` or from the
@@ -249,7 +249,7 @@ specifier.
    >>> parser.print_help()
    usage: myprogram [-h] [--foo FOO]
 
-   optional arguments:
+   options:
     -h, --help  show this help message and exit
     --foo FOO   foo of the myprogram program
 
@@ -269,7 +269,7 @@ arguments it contains::
    positional arguments:
     bar          bar help
 
-   optional arguments:
+   options:
     -h, --help   show this help message and exit
     --foo [FOO]  foo help
 
@@ -284,7 +284,7 @@ The default message can be overridden with the ``usage=`` keyword argument::
    positional arguments:
     bar          bar help
 
-   optional arguments:
+   options:
     -h, --help   show this help message and exit
     --foo [FOO]  foo help
 
@@ -307,7 +307,7 @@ various arguments::
 
    A foo that bars
 
-   optional arguments:
+   options:
     -h, --help  show this help message and exit
 
 By default, the description will be line-wrapped so that it fits within the
@@ -329,7 +329,7 @@ argument to :class:`ArgumentParser`::
 
    A foo that bars
 
-   optional arguments:
+   options:
     -h, --help  show this help message and exit
 
    And that's how you'd foo a bar
@@ -403,7 +403,7 @@ epilog_ texts in command-line help messages::
 
    this description was indented weird but that is okay
 
-   optional arguments:
+   options:
     -h, --help  show this help message and exit
 
    likewise for this epilog whose whitespace will be cleaned up and whose words
@@ -432,7 +432,7 @@ should not be line-wrapped::
       exactly the way
       I want it
 
-   optional arguments:
+   options:
     -h, --help  show this help message and exit
 
 :class:`RawTextHelpFormatter` maintains whitespace for all sorts of help text,
@@ -454,7 +454,7 @@ default values to each of the argument help messages::
    positional arguments:
     bar         BAR! (default: [1, 2, 3])
 
-   optional arguments:
+   options:
     -h, --help  show this help message and exit
     --foo FOO   FOO! (default: 42)
 
@@ -473,7 +473,7 @@ as the regular formatter does)::
    positional arguments:
      float
 
-   optional arguments:
+   options:
      -h, --help  show this help message and exit
      --foo int
 
@@ -592,7 +592,7 @@ older arguments with the same option string.  To get this behavior, the value
    >>> parser.print_help()
    usage: PROG [-h] [-f FOO] [--foo FOO]
 
-   optional arguments:
+   options:
     -h, --help  show this help message and exit
     -f FOO      old foo help
     --foo FOO   new foo help
@@ -623,7 +623,7 @@ help will be printed:
    $ python myprogram.py --help
    usage: myprogram.py [-h] [--foo FOO]
 
-   optional arguments:
+   options:
     -h, --help  show this help message and exit
     --foo FOO   foo help
 
@@ -636,7 +636,7 @@ This can be achieved by passing ``False`` as the ``add_help=`` argument to
    >>> parser.print_help()
    usage: PROG [--foo FOO]
 
-   optional arguments:
+   options:
     --foo FOO  foo help
 
 The help option is typically ``-h/--help``. The exception to this is
@@ -649,7 +649,7 @@ the help options::
    >>> parser.print_help()
    usage: PROG [+h]
 
-   optional arguments:
+   options:
      +h, ++help  show this help message and exit
 
 
@@ -1203,7 +1203,7 @@ argument::
    positional arguments:
     bar     one of the bars to be frobbled
 
-   optional arguments:
+   options:
     -h, --help  show this help message and exit
     --foo   foo the bars before frobbling
 
@@ -1221,7 +1221,7 @@ specifiers include the program name, ``%(prog)s`` and most keyword arguments to
    positional arguments:
     bar     the bar to frobble (default: 42)
 
-   optional arguments:
+   options:
     -h, --help  show this help message and exit
 
 As the help string supports %-formatting, if you want a literal ``%`` to appear
@@ -1235,7 +1235,7 @@ setting the ``help`` value to ``argparse.SUPPRESS``::
    >>> parser.print_help()
    usage: frobble [-h]
 
-   optional arguments:
+   options:
      -h, --help  show this help message and exit
 
 
@@ -1262,7 +1262,7 @@ will be referred to as ``FOO``.  An example::
    positional arguments:
     bar
 
-   optional arguments:
+   options:
     -h, --help  show this help message and exit
     --foo FOO
 
@@ -1279,7 +1279,7 @@ An alternative name can be specified with ``metavar``::
    positional arguments:
     XXX
 
-   optional arguments:
+   options:
     -h, --help  show this help message and exit
     --foo YYY
 
@@ -1297,7 +1297,7 @@ arguments::
    >>> parser.print_help()
    usage: PROG [-h] [-x X X] [--foo bar baz]
 
-   optional arguments:
+   options:
     -h, --help     show this help message and exit
     -x X X
     --foo bar baz
@@ -1701,7 +1701,7 @@ Sub-commands
          a     a help
          b     b help
 
-     optional arguments:
+     options:
        -h, --help  show this help message and exit
        --foo   foo help
 
@@ -1711,13 +1711,13 @@ Sub-commands
      positional arguments:
        bar     bar help
 
-     optional arguments:
+     options:
        -h, --help  show this help message and exit
 
      >>> parser.parse_args(['b', '--help'])
      usage: PROG b [-h] [--baz {X,Y,Z}]
 
-     optional arguments:
+     options:
        -h, --help     show this help message and exit
        --baz {X,Y,Z}  baz help
 
@@ -1734,7 +1734,7 @@ Sub-commands
      >>> parser.parse_args(['-h'])
      usage:  [-h] {foo,bar} ...
 
-     optional arguments:
+     options:
        -h, --help  show this help message and exit
 
      subcommands: