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.

13 files changed, 216 insertions, 159 deletions

diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst
index 1971136899..dcfc46f047 100644
--- a/Doc/library/codecs.rst
+++ b/Doc/library/codecs.rst
@@ -788,7 +788,7 @@ Encodings and Unicode
 
 Strings are stored internally as sequences of codepoints (to be precise
 as :c:type:`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) :c:type:`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
diff --git a/Doc/library/compileall.rst b/Doc/library/compileall.rst
index b0a2e34d91..63ddc99cdd 100644
--- a/Doc/library/compileall.rst
+++ b/Doc/library/compileall.rst
@@ -10,16 +10,53 @@ 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.
-The :option:`-b` flag may be given to write legacy ``.pyc`` file path names,
-otherwise :pep:`3147` style byte-compiled path names are written.
 
+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.
+
+.. cmdoption:: -i list
+
+   Expand list with its content (file and directory names).
+
+.. cmdoption:: -b
+
+   Write legacy ``.pyc`` file path names.  Default is to write :pep:`3147`-style
+   byte-compiled path names.
+
+
+Public functions
+----------------
 
 .. function:: compile_dir(dir, maxlevels=10, ddir=None, force=False, rx=None, quiet=False, legacy=False)
 
@@ -37,7 +74,7 @@ otherwise :pep:`3147` style byte-compiled path names are written.
    operation.
 
    If *legacy* is true, old-style ``.pyc`` file path names are written,
-   otherwise (the default), :pep:`3147` style path names are written.
+   otherwise (the default), :pep:`3147`-style path names are written.
 
 
 .. function:: compile_path(skip_curdir=True, maxlevels=0, force=False, legacy=False)
@@ -64,4 +101,3 @@ subdirectory and all its subdirectories::
 
    Module :mod:`py_compile`
       Byte-compile a single source file.
-
diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst
index 795c074348..159ab18396 100644
--- a/Doc/library/doctest.rst
+++ b/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
@@ -1377,7 +1377,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.
diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst
index 9d776983d4..70591d15f2 100644
--- a/Doc/library/exceptions.rst
+++ b/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.
 
 
diff --git a/Doc/library/getopt.rst b/Doc/library/getopt.rst
index b80af01a4c..28e1cdbf33 100644
--- a/Doc/library/getopt.rst
+++ b/Doc/library/getopt.rst
@@ -47,7 +47,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,
@@ -68,7 +68,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.
 
diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst
index 1b78fb9bc1..6bd1898134 100644
--- a/Doc/library/idle.rst
+++ b/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;
diff --git a/Doc/library/optparse.rst b/Doc/library/optparse.rst
index e7de741f97..177978f1d5 100644
--- a/Doc/library/optparse.rst
+++ b/Doc/library/optparse.rst
@@ -104,26 +104,26 @@ option
    an argument used to supply extra information to guide or customize the
    execution of a program.  There are many different syntaxes for options; the
    traditional Unix syntax is a hyphen ("-") followed by a single letter,
-   e.g. ``"-x"`` or ``"-F"``.  Also, traditional Unix syntax allows multiple
-   options to be merged into a single argument, e.g.  ``"-x -F"`` is equivalent
-   to ``"-xF"``.  The GNU project introduced ``"--"`` followed by a series of
-   hyphen-separated words, e.g.  ``"--file"`` or ``"--dry-run"``.  These are the
+   e.g. ``-x`` or ``-F``.  Also, traditional Unix syntax allows multiple
+   options to be merged into a single argument, e.g. ``-x -F`` is equivalent
+   to ``-xF``.  The GNU project introduced ``--`` followed by a series of
+   hyphen-separated words, e.g. ``--file`` or ``--dry-run``.  These are the
    only two option syntaxes provided by :mod:`optparse`.
 
    Some other option syntaxes that the world has seen include:
 
-   * a hyphen followed by a few letters, e.g. ``"-pf"`` (this is *not* the same
+   * a hyphen followed by a few letters, e.g. ``-pf`` (this is *not* the same
      as multiple options merged into a single argument)
 
-   * a hyphen followed by a whole word, e.g. ``"-file"`` (this is technically
+   * a hyphen followed by a whole word, e.g. ``-file`` (this is technically
      equivalent to the previous syntax, but they aren't usually seen in the same
      program)
 
    * a plus sign followed by a single letter, or a few letters, or a word, e.g.
-     ``"+f"``, ``"+rgb"``
+     ``+f``, ``+rgb``
 
-   * a slash followed by a letter, or a few letters, or a word, e.g. ``"/f"``,
-     ``"/file"``
+   * a slash followed by a letter, or a few letters, or a word, e.g. ``/f``,
+     ``/file``
 
    These option syntaxes are not supported by :mod:`optparse`, and they never
    will be.  This is deliberate: the first three are non-standard on any
@@ -151,9 +151,9 @@ option argument
    Typically, a given option either takes an argument or it doesn't. Lots of
    people want an "optional option arguments" feature, meaning that some options
    will take an argument if they see it, and won't if they don't.  This is
-   somewhat controversial, because it makes parsing ambiguous: if ``"-a"`` takes
-   an optional argument and ``"-b"`` is another option entirely, how do we
-   interpret ``"-ab"``?  Because of this ambiguity, :mod:`optparse` does not
+   somewhat controversial, because it makes parsing ambiguous: if ``-a`` takes
+   an optional argument and ``-b`` is another option entirely, how do we
+   interpret ``-ab``?  Because of this ambiguity, :mod:`optparse` does not
    support this feature.
 
 positional argument
@@ -171,9 +171,9 @@ For example, consider this hypothetical command-line::
 
    prog -v --report /tmp/report.txt foo bar
 
-``"-v"`` and ``"--report"`` are both options.  Assuming that :option:`--report`
-takes one argument, ``"/tmp/report.txt"`` is an option argument.  ``"foo"`` and
-``"bar"`` are positional arguments.
+``-v`` and ``--report`` are both options.  Assuming that ``--report``
+takes one argument, ``/tmp/report.txt`` is an option argument.  ``foo`` and
+``bar`` are positional arguments.
 
 
 .. _optparse-what-options-for:
@@ -258,7 +258,7 @@ Then you can start defining options.  The basic syntax is::
    parser.add_option(opt_str, ...,
                      attr=value, ...)
 
-Each option has one or more option strings, such as ``"-f"`` or ``"--file"``,
+Each option has one or more option strings, such as ``-f`` or ``--file``,
 and several option attributes that tell :mod:`optparse` what to expect and what
 to do when it encounters that option on the command line.
 
@@ -287,7 +287,7 @@ that's rarely necessary: by default it uses ``sys.argv[1:]``.)
 :meth:`parse_args` returns two values:
 
 * ``options``, an object containing values for all of your options---e.g. if
-  ``"--file"`` takes a single string argument, then ``options.file`` will be the
+  ``--file`` takes a single string argument, then ``options.file`` will be the
   filename supplied by the user, or ``None`` if the user did not supply that
   option
 
@@ -333,8 +333,8 @@ Now let's make up a fake command line and ask :mod:`optparse` to parse it::
    args = ["-f", "foo.txt"]
    (options, args) = parser.parse_args(args)
 
-When :mod:`optparse` sees the option string ``"-f"``, it consumes the next
-argument, ``"foo.txt"``, and stores it in ``options.filename``.  So, after this
+When :mod:`optparse` sees the option string ``-f``, it consumes the next
+argument, ``foo.txt``, and stores it in ``options.filename``.  So, after this
 call to :meth:`parse_args`, ``options.filename`` is ``"foo.txt"``.
 
 Some other option types supported by :mod:`optparse` are ``int`` and ``float``.
@@ -346,13 +346,13 @@ Note that this option has no long option string, which is perfectly acceptable.
 Also, there's no explicit action, since the default is ``store``.
 
 Let's parse another fake command-line.  This time, we'll jam the option argument
-right up against the option: since ``"-n42"`` (one argument) is equivalent to
-``"-n 42"`` (two arguments), the code ::
+right up against the option: since ``-n42`` (one argument) is equivalent to
+``-n 42`` (two arguments), the code ::
 
    (options, args) = parser.parse_args(["-n42"])
    print(options.num)
 
-will print ``"42"``.
+will print ``42``.
 
 If you don't specify a type, :mod:`optparse` assumes ``string``.  Combined with
 the fact that the default action is ``store``, that means our first example can
@@ -362,9 +362,9 @@ be a lot shorter::
 
 If you don't supply a destination, :mod:`optparse` figures out a sensible
 default from the option strings: if the first long option string is
-``"--foo-bar"``, then the default destination is ``foo_bar``.  If there are no
+``--foo-bar``, then the default destination is ``foo_bar``.  If there are no
 long option strings, :mod:`optparse` looks at the first short option string: the
-default destination for ``"-f"`` is ``f``.
+default destination for ``-f`` is ``f``.
 
 :mod:`optparse` also includes the built-in ``complex`` type.  Adding
 types is covered in section :ref:`optparse-extending-optparse`.
@@ -378,7 +378,7 @@ Handling boolean (flag) options
 Flag options---set a variable to true or false when a particular option is seen
 ---are quite common.  :mod:`optparse` supports them with two separate actions,
 ``store_true`` and ``store_false``.  For example, you might have a ``verbose``
-flag that is turned on with ``"-v"`` and off with ``"-q"``::
+flag that is turned on with ``-v`` and off with ``-q``::
 
    parser.add_option("-v", action="store_true", dest="verbose")
    parser.add_option("-q", action="store_false", dest="verbose")
@@ -387,8 +387,8 @@ Here we have two different options with the same destination, which is perfectly
 OK.  (It just means you have to be a bit careful when setting default values---
 see below.)
 
-When :mod:`optparse` encounters ``"-v"`` on the command line, it sets
-``options.verbose`` to ``True``; when it encounters ``"-q"``,
+When :mod:`optparse` encounters ``-v`` on the command line, it sets
+``options.verbose`` to ``True``; when it encounters ``-q``,
 ``options.verbose`` is set to ``False``.
 
 
@@ -428,7 +428,7 @@ supply a default value for each destination, which is assigned before the
 command line is parsed.
 
 First, consider the verbose/quiet example.  If we want :mod:`optparse` to set
-``verbose`` to ``True`` unless ``"-q"`` is seen, then we can do this::
+``verbose`` to ``True`` unless ``-q`` is seen, then we can do this::
 
    parser.add_option("-v", action="store_true", dest="verbose", default=True)
    parser.add_option("-q", action="store_false", dest="verbose")
@@ -486,7 +486,7 @@ user-friendly (documented) options::
                      help="interaction mode: novice, intermediate, "
                           "or expert [default: %default]")
 
-If :mod:`optparse` encounters either ``"-h"`` or ``"--help"`` on the
+If :mod:`optparse` encounters either ``-h`` or ``--help`` on the
 command-line, or if you just call :meth:`parser.print_help`, it prints the
 following to standard output:
 
@@ -513,7 +513,7 @@ help message:
 
      usage = "usage: %prog [options] arg1 arg2"
 
-  :mod:`optparse` expands ``"%prog"`` in the usage string to the name of the
+  :mod:`optparse` expands ``%prog`` in the usage string to the name of the
   current program, i.e. ``os.path.basename(sys.argv[0])``.  The expanded string
   is then printed before the detailed option help.
 
@@ -531,17 +531,17 @@ help message:
      -m MODE, --mode=MODE
 
   Here, "MODE" is called the meta-variable: it stands for the argument that the
-  user is expected to supply to :option:`-m`/:option:`--mode`.  By default,
+  user is expected to supply to ``-m``/``--mode``.  By default,
   :mod:`optparse` converts the destination variable name to uppercase and uses
   that for the meta-variable.  Sometimes, that's not what you want---for
-  example, the :option:`--filename` option explicitly sets ``metavar="FILE"``,
+  example, the ``--filename`` option explicitly sets ``metavar="FILE"``,
   resulting in this automatically-generated option description::
 
      -f FILE, --filename=FILE
 
   This is important for more than just saving space, though: the manually
-  written help text uses the meta-variable "FILE" to clue the user in that
-  there's a connection between the semi-formal syntax "-f FILE" and the informal
+  written help text uses the meta-variable ``FILE`` to clue the user in that
+  there's a connection between the semi-formal syntax ``-f FILE`` and the informal
   semantic description "write output to FILE". This is a simple but effective
   way to make your help text a lot clearer and more useful for end users.
 
@@ -593,11 +593,11 @@ argument to OptionParser::
 
    parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0")
 
-``"%prog"`` is expanded just like it is in ``usage``.  Apart from that,
+``%prog`` is expanded just like it is in ``usage``.  Apart from that,
 ``version`` can contain anything you like.  When you supply it, :mod:`optparse`
-automatically adds a ``"--version"`` option to your parser. If it encounters
+automatically adds a ``--version`` option to your parser. If it encounters
 this option on the command line, it expands your ``version`` string (by
-replacing ``"%prog"``), prints it to stdout, and exits.
+replacing ``%prog``), prints it to stdout, and exits.
 
 For example, if your script is called ``/usr/bin/foo``::
 
@@ -610,7 +610,7 @@ The following two methods can be used to print and get the ``version`` string:
 
    Print the version message for the current program (``self.version``) to
    *file* (default stdout).  As with :meth:`print_usage`, any occurrence
-   of ``"%prog"`` in ``self.version`` is replaced with the name of the current
+   of ``%prog`` in ``self.version`` is replaced with the name of the current
    program.  Does nothing if ``self.version`` is empty or undefined.
 
 .. method:: OptionParser.get_version()
@@ -633,9 +633,9 @@ usual way: raise an exception (either :exc:`optparse.OptionError` or
 
 Handling user errors is much more important, since they are guaranteed to happen
 no matter how stable your code is.  :mod:`optparse` can automatically detect
-some user errors, such as bad option arguments (passing ``"-n 4x"`` where
-:option:`-n` takes an integer argument), missing arguments (``"-n"`` at the end
-of the command line, where :option:`-n` takes an argument of any type).  Also,
+some user errors, such as bad option arguments (passing ``-n 4x`` where
+``-n`` takes an integer argument), missing arguments (``-n`` at the end
+of the command line, where ``-n`` takes an argument of any type).  Also,
 you can call :func:`OptionParser.error` to signal an application-defined error
 condition::
 
@@ -648,7 +648,7 @@ In either case, :mod:`optparse` handles the error the same way: it prints the
 program's usage message and an error message to standard error and exits with
 error status 2.
 
-Consider the first example above, where the user passes ``"4x"`` to an option
+Consider the first example above, where the user passes ``4x`` to an option
 that takes an integer::
 
    $ /usr/bin/foo -n 4x
@@ -741,8 +741,8 @@ The first step in using :mod:`optparse` is to create an OptionParser instance.
    ``version`` (default: ``None``)
       A version string to print when the user supplies a version option. If you
       supply a true value for ``version``, :mod:`optparse` automatically adds a
-      version option with the single option string ``"--version"``.  The
-      substring ``"%prog"`` is expanded the same as for ``usage``.
+      version option with the single option string ``--version``.  The
+      substring ``%prog`` is expanded the same as for ``usage``.
 
    ``conflict_handler`` (default: ``"error"``)
       Specifies what to do when options with conflicting option strings are
@@ -761,11 +761,11 @@ The first step in using :mod:`optparse` is to create an OptionParser instance.
       IndentedHelpFormatter and TitledHelpFormatter.
 
    ``add_help_option`` (default: ``True``)
-      If true, :mod:`optparse` will add a help option (with option strings ``"-h"``
-      and ``"--help"``) to the parser.
+      If true, :mod:`optparse` will add a help option (with option strings ``-h``
+      and ``--help``) to the parser.
 
    ``prog``
-      The string to use when expanding ``"%prog"`` in ``usage`` and ``version``
+      The string to use when expanding ``%prog`` in ``usage`` and ``version``
       instead of ``os.path.basename(sys.argv[0])``.
 
    ``epilog`` (default: ``None``)
@@ -809,7 +809,7 @@ Defining options
 ^^^^^^^^^^^^^^^^
 
 Each Option instance represents a set of synonymous command-line option strings,
-e.g. :option:`-f` and :option:`--file`.  You can specify any number of short or
+e.g. ``-f`` and ``--file``.  You can specify any number of short or
 long option strings, but you must specify at least one overall option string.
 
 The canonical way to create an :class:`Option` instance is with the
@@ -972,7 +972,7 @@ relevant to a particular option, or fail to pass a required option attribute,
 .. attribute:: Option.help
 
    Help text to print for this option when listing all available options after
-   the user supplies a :attr:`~Option.help` option (such as ``"--help"``).  If
+   the user supplies a :attr:`~Option.help` option (such as ``--help``).  If
    no help text is supplied, the option will be listed without help text.  To
    hide this option, use the special value :data:`optparse.SUPPRESS_HELP`.
 
@@ -1010,9 +1010,9 @@ must specify for any option using that action.
   If :attr:`~Option.type` is not supplied, it defaults to ``"string"``.
 
   If :attr:`~Option.dest` is not supplied, :mod:`optparse` derives a destination
-  from the first long option string (e.g., ``"--foo-bar"`` implies
+  from the first long option string (e.g., ``--foo-bar`` implies
   ``foo_bar``). If there are no long option strings, :mod:`optparse` derives a
-  destination from the first short option string (e.g., ``"-f"`` implies ``f``).
+  destination from the first short option string (e.g., ``-f`` implies ``f``).
 
   Example::
 
@@ -1043,7 +1043,7 @@ must specify for any option using that action.
      parser.add_option("--noisy",
                        action="store_const", const=2, dest="verbose")
 
-  If ``"--noisy"`` is seen, :mod:`optparse` will set  ::
+  If ``--noisy`` is seen, :mod:`optparse` will set  ::
 
      options.verbose = 2
 
@@ -1078,13 +1078,13 @@ must specify for any option using that action.
 
      parser.add_option("-t", "--tracks", action="append", type="int")
 
-  If ``"-t3"`` is seen on the command-line, :mod:`optparse` does the equivalent
+  If ``-t3`` is seen on the command-line, :mod:`optparse` does the equivalent
   of::
 
      options.tracks = []
      options.tracks.append(int("3"))
 
-  If, a little later on, ``"--tracks=4"`` is seen, it does::
+  If, a little later on, ``--tracks=4`` is seen, it does::
 
      options.tracks.append(int("4"))
 
@@ -1106,13 +1106,13 @@ must specify for any option using that action.
 
      parser.add_option("-v", action="count", dest="verbosity")
 
-  The first time ``"-v"`` is seen on the command line, :mod:`optparse` does the
+  The first time ``-v`` is seen on the command line, :mod:`optparse` does the
   equivalent of::
 
      options.verbosity = 0
      options.verbosity += 1
 
-  Every subsequent occurrence of ``"-v"`` results in  ::
+  Every subsequent occurrence of ``-v`` results in  ::
 
      options.verbosity += 1
 
@@ -1155,7 +1155,7 @@ must specify for any option using that action.
                        help="Input file to read data from")
      parser.add_option("--secret", help=SUPPRESS_HELP)
 
-  If :mod:`optparse` sees either ``"-h"`` or ``"--help"`` on the command line,
+  If :mod:`optparse` sees either ``-h`` or ``--help`` on the command line,
   it will print something like the following help message to stdout (assuming
   ``sys.argv[0]`` is ``"foo.py"``):
 
@@ -1269,8 +1269,8 @@ provides several methods to help you out:
 
 .. method:: OptionParser.disable_interspersed_args()
 
-   Set parsing to stop on the first non-option.  For example, if ``"-a"`` and
-   ``"-b"`` are both simple options that take no arguments, :mod:`optparse`
+   Set parsing to stop on the first non-option.  For example, if ``-a`` and
+   ``-b`` are both simple options that take no arguments, :mod:`optparse`
    normally accepts this syntax::
 
       prog -a arg1 -b arg2
@@ -1300,7 +1300,7 @@ provides several methods to help you out:
 .. method:: OptionParser.has_option(opt_str)
 
    Return true if the OptionParser has an option with option string *opt_str*
-   (e.g., ``"-q"`` or ``"--verbose"``).
+   (e.g., ``-q`` or ``--verbose``).
 
 .. method:: OptionParser.remove_option(opt_str)
 
@@ -1353,9 +1353,9 @@ intelligently and add conflicting options to it::
    parser.add_option("-n", "--noisy", ..., help="be noisy")
 
 At this point, :mod:`optparse` detects that a previously-added option is already
-using the ``"-n"`` option string.  Since ``conflict_handler`` is ``"resolve"``,
-it resolves the situation by removing ``"-n"`` from the earlier option's list of
-option strings.  Now ``"--dry-run"`` is the only way for the user to activate
+using the ``-n`` option string.  Since ``conflict_handler`` is ``"resolve"``,
+it resolves the situation by removing ``-n`` from the earlier option's list of
+option strings.  Now ``--dry-run`` is the only way for the user to activate
 that option.  If the user asks for help, the help message will reflect that::
 
    options:
@@ -1371,7 +1371,7 @@ existing OptionParser::
 
    parser.add_option("--dry-run", ..., help="new dry-run option")
 
-At this point, the original :option:`-n/--dry-run` option is no longer
+At this point, the original ``-n``/``--dry-run`` option is no longer
 accessible, so :mod:`optparse` removes it, leaving this help text::
 
    options:
@@ -1409,7 +1409,7 @@ OptionParser supports several other public methods:
 .. method:: OptionParser.print_usage(file=None)
 
    Print the usage message for the current program (``self.usage``) to *file*
-   (default stdout).  Any occurrence of the string ``"%prog"`` in ``self.usage``
+   (default stdout).  Any occurrence of the string ``%prog`` in ``self.usage``
    is replaced with the name of the current program.  Does nothing if
    ``self.usage`` is empty or not defined.
 
@@ -1473,9 +1473,9 @@ only option attribute you must specify is ``callback``, the function to call::
 
 ``callback`` is a function (or other callable object), so you must have already
 defined ``my_callback()`` when you create this callback option. In this simple
-case, :mod:`optparse` doesn't even know if :option:`-c` takes any arguments,
+case, :mod:`optparse` doesn't even know if ``-c`` takes any arguments,
 which usually means that the option takes no arguments---the mere presence of
-:option:`-c` on the command-line is all it needs to know.  In some
+``-c`` on the command-line is all it needs to know.  In some
 circumstances, though, you might want your callback to consume an arbitrary
 number of command-line arguments.  This is where writing callbacks gets tricky;
 it's covered later in this section.
@@ -1528,8 +1528,8 @@ where
 ``opt_str``
    is the option string seen on the command-line that's triggering the callback.
    (If an abbreviated long option was used, ``opt_str`` will be the full,
-   canonical option string---e.g. if the user puts ``"--foo"`` on the
-   command-line as an abbreviation for ``"--foobar"``, then ``opt_str`` will be
+   canonical option string---e.g. if the user puts ``--foo`` on the
+   command-line as an abbreviation for ``--foobar``, then ``opt_str`` will be
    ``"--foobar"``.)
 
 ``value``
@@ -1604,8 +1604,8 @@ Of course, you could do that with the ``"store_true"`` action.
 Callback example 2: check option order
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Here's a slightly more interesting example: record the fact that ``"-a"`` is
-seen, but blow up if it comes after ``"-b"`` in the command-line.  ::
+Here's a slightly more interesting example: record the fact that ``-a`` is
+seen, but blow up if it comes after ``-b`` in the command-line.  ::
 
    def check_order(option, opt_str, value, parser):
        if parser.values.b:
@@ -1622,7 +1622,7 @@ Callback example 3: check option order (generalized)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 If you want to re-use this callback for several similar options (set a flag, but
-blow up if ``"-b"`` has already been seen), it needs a bit of work: the error
+blow up if ``-b`` has already been seen), it needs a bit of work: the error
 message and the flag that it sets must be generalized.  ::
 
    def check_order(option, opt_str, value, parser):
@@ -1692,15 +1692,15 @@ For this case, you must write a callback, as :mod:`optparse` doesn't provide any
 built-in capabilities for it.  And you have to deal with certain intricacies of
 conventional Unix command-line parsing that :mod:`optparse` normally handles for
 you.  In particular, callbacks should implement the conventional rules for bare
-``"--"`` and ``"-"`` arguments:
+``--`` and ``-`` arguments:
 
-* either ``"--"`` or ``"-"`` can be option arguments
+* either ``--`` or ``-`` can be option arguments
 
-* bare ``"--"`` (if not the argument to some option): halt command-line
-  processing and discard the ``"--"``
+* bare ``--`` (if not the argument to some option): halt command-line
+  processing and discard the ``--``
 
-* bare ``"-"`` (if not the argument to some option): halt command-line
-  processing but keep the ``"-"`` (append it to ``parser.largs``)
+* bare ``-`` (if not the argument to some option): halt command-line
+  processing but keep the ``-`` (append it to ``parser.largs``)
 
 If you want an option that takes a variable number of arguments, there are
 several subtle, tricky issues to worry about.  The exact implementation you
@@ -1771,7 +1771,7 @@ To add new types, you need to define your own subclass of :mod:`optparse`'s
       def check_mytype(option, opt, value)
 
    where ``option`` is an :class:`Option` instance, ``opt`` is an option string
-   (e.g., ``"-f"``), and ``value`` is the string from the command line that must
+   (e.g., ``-f``), and ``value`` is the string from the command line that must
    be checked and converted to your desired type.  ``check_mytype()`` should
    return an object of the hypothetical type ``mytype``.  The value returned by
    a type-checking function will wind up in the OptionValues instance returned
@@ -1883,7 +1883,7 @@ For example, let's add an ``"extend"`` action.  This is similar to the standard
 ``"append"`` action, but instead of taking a single value from the command-line
 and appending it to an existing list, ``"extend"`` will take multiple values in
 a single comma-delimited string, and extend an existing list with them.  That
-is, if ``"--names"`` is an ``"extend"`` option of type ``"string"``, the command
+is, if ``--names`` is an ``"extend"`` option of type ``"string"``, the command
 line ::
 
    --names=foo,bar --names blah --names ding,dong
diff --git a/Doc/library/pydoc.rst b/Doc/library/pydoc.rst
index cbb8af851e..3ab3303c35 100644
--- a/Doc/library/pydoc.rst
+++ b/Doc/library/pydoc.rst
@@ -40,25 +40,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``.
 
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index 01dad9c2f1..c7aa214226 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -169,7 +169,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
@@ -685,7 +685,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
@@ -862,7 +862,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.
 
    .. impl-detail::
diff --git a/Doc/library/test.rst b/Doc/library/test.rst
index d4ad7a5454..58adfa2146 100644
--- a/Doc/library/test.rst
+++ b/Doc/library/test.rst
@@ -163,24 +163,23 @@ 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
+regrtest.py test_spam.py`) 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
+tests to use to be set. You do this by using the ``-u`` command-line
+option. Run :program:`python regrtest.py -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 regrtest.py -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 regrtest.py -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,
+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.
 
diff --git a/Doc/library/timeit.rst b/Doc/library/timeit.rst
index 89ea7b0255..4a0b9c257b 100644
--- a/Doc/library/timeit.rst
+++ b/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
diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst
index ee957de0e3..d463d7f462 100644
--- a/Doc/library/unittest.rst
+++ b/Doc/library/unittest.rst
@@ -154,7 +154,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::
 
    ...
@@ -206,7 +206,7 @@ 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::
+For a list of all the command-line options::
 
    python -m unittest -h
 
@@ -215,31 +215,33 @@ For a list of all the command line options::
    not modules or classes.
 
 
-failfast, catch and buffer command line options
+failfast, catch and buffer command-line options
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-unittest supports three command options.
+:program:`unittest` supports three command-line options.
 
-* :option:`-b` / :option:`--buffer`
+.. program:: unittest
 
-  The standard output and standard error streams are buffered during the test
-  run. Output during a passing test is discarded. Output is echoed normally
-  on test fail or error and is added to the failure messages.
+.. cmdoption:: -b, --buffer
 
-* :option:`-c` / :option:`--catch`
+   The standard output and standard error streams are buffered during the test
+   run. Output during a passing test is discarded. Output is echoed normally
+   on test fail or error and is added to the failure messages.
 
-  Control-C during the test run waits for the current test to end and then
-  reports all the results so far. A second control-C raises the normal
-  :exc:`KeyboardInterrupt` exception.
+.. cmdoption:: -c, --catch
 
-  See `Signal Handling`_ for the functions that provide this functionality.
+   Control-C during the test run waits for the current test to end and then
+   reports all the results so far. A second control-C raises the normal
+   :exc:`KeyboardInterrupt` exception.
 
-* :option:`-f` / :option:`--failfast`
+   See `Signal Handling`_ for the functions that provide this functionality.
 
-  Stop the test run on the first error or failure.
+.. cmdoption:: -f, --failfast
+
+   Stop the test run on the first error or failure.
 
 .. versionadded:: 3.2
-   The command line options ``-c``, ``-b`` and ``-f`` were added.
+   The command-line options :option:`-c`, :option:`-b` and :option:`-f` were added.
 
 The command line can also be used for test discovery, for running all of the
 tests in a project or just a subset.
@@ -257,18 +259,30 @@ compatible with test discovery they must all be importable from the top level
 directory of the project (in other words, they must all be in Python packages).
 
 Test discovery is implemented in :meth:`TestLoader.discover`, but can also be
-used from the command line. The basic command line usage is::
+used from the command line. The basic command-line usage is::
 
    cd project_directory
    python -m unittest discover
 
 The ``discover`` sub-command has the following options:
 
-   -v, --verbose    Verbose output
-   -s directory     Directory to start discovery ('.' default)
-   -p pattern       Pattern to match test files ('test*.py' default)
-   -t directory     Top level directory of project (default to
-                    start directory)
+.. program:: unittest discover
+
+.. cmdoption:: -v, --verbose
+
+   Verbose output
+
+.. cmdoption:: -s directory
+
+   Directory to start discovery ('.' default)
+
+.. cmdoption:: -p pattern
+
+   Pattern to match test files ('test*.py' default)
+
+.. cmdoption:: -t directory
+
+   Top level directory of project (defaults to start directory)
 
 The :option:`-s`, :option:`-p`, and :option:`-t` options can be passed in
 as positional arguments in that order. The following two command lines
@@ -1850,7 +1864,7 @@ Loading and running tests
       >>> main(module='test_module', exit=False)
 
    The ``failfast``, ``catchbreak`` and ``buffer`` parameters have the same
-   effect as the `failfast, catch and buffer command line options`_.
+   effect as the `failfast, catch and buffer command-line options`_.
 
    Calling ``main`` actually returns an instance of the ``TestProgram`` class.
    This stores the result of the tests run as the ``result`` attribute.
@@ -2013,7 +2027,7 @@ instead of as an error.
 Signal Handling
 ---------------
 
-The :option:`-c`/:option:`--catch` command line option to unittest, along with the ``catchbreak``
+The :option:`-c` command-line option to unittest, along with the ``catchbreak``
 parameter to :func:`unittest.main()`, provide more friendly handling of
 control-C during a test run. With catch break behavior enabled control-C will
 allow the currently running test to complete, and the test run will then end
diff --git a/Doc/library/webbrowser.rst b/Doc/library/webbrowser.rst
index e8f47562e1..20c091399f 100644
--- a/Doc/library/webbrowser.rst
+++ b/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