Incorporate improvements from Serhiy's PR

Co-authored-by: Serhiy Storchaka <[email protected]>

Author: ncoghlan

Doc/library/argparse.rst

@@ -14,10 +14,14 @@
 .. note::
 
    While :mod:`argparse` is the recommended standard library module for
-   *implementing* command line applications, authors of third party
+   *implementing* basic command line applications, authors of third party
    command line argument processing libraries may find that the
    lower level :mod:`optparse` module serves as a better foundation for
-   that use case.
+   that use case. ``optparse`` (or one of the third party libraries
+   based on it) may also be worth considering for applications where
+   stricter adherence to common Unix and Linux command line interface
+   conventions around the handling of option parameter values that start
+   with ``-`` is desired.
 
 --------------
 

Doc/library/getopt.rst

@@ -139,13 +139,25 @@ In a script, typical usage is something like this::
                output = a
            else:
                assert False, "unhandled option"
-       # ...
+       process(args, output=output, verbose=verbose)
 
    if __name__ == "__main__":
        main()
 
 Note that an equivalent command line interface could be produced with less code
-and more informative help and error messages by using the :mod:`argparse` module::
+and more informative help and error messages by using the :mod:`optparse` module::
+
+   import optparse
+
+   if __name__ == '__main__':
+       parser = optparse.OptionParser()
+       parser.add_option('-o', '--output')
+       parser.add_option('-v', dest='verbose', action='store_true')
+       opts, args = parser.parse_args()
+       process(args, output=opts.output, verbose=opts.verbose)
+
+An equivalent command line interface for this simple case can also be produced
+by using the :mod:`argparse` module::
 
    import argparse
 
@@ -157,8 +169,15 @@ and more informative help and error messages by using the :mod:`argparse` module
        # ... do something with args.output ...
        # ... do something with args.verbose ..
 
+In more complex cases (such as options which accept values), the behaviour
+of the ``argparse`` version may diverge from that of the ``getopt`` and
+``optparse`` versions due to the way ``argparse`` handles parameter
+values that start with ``-``.
+
 .. seealso::
 
-   Module :mod:`argparse`
-      Alternative command line option and argument parsing library.
+   Module :mod:`optparse`
+      More object-oriented command line option parsing.
 
+   Module :mod:`argparse`
+      More opinionated command line option and argument parsing library.

Doc/library/optparse.rst

@@ -46,10 +46,11 @@
 --------------
 
 :mod:`optparse` is a more convenient, flexible, and powerful library for parsing
-command-line options than the old :mod:`getopt` module.  :mod:`optparse` uses a
-more declarative style of command-line parsing: you create an instance of
-:class:`OptionParser`, populate it with options, and parse the command
-line. :mod:`optparse` allows users to specify options in the conventional
+command-line options than the minimalist :mod:`getopt` module.
+:mod:`optparse` uses a more declarative style of command-line parsing:
+you create an instance of :class:`OptionParser`,
+populate it with options, and parse the command line.
+:mod:`optparse` allows users to specify options in the conventional
 GNU/POSIX syntax, and additionally generates usage and help messages for you.
 
 Here's an example of using :mod:`optparse` in a simple script::