--- rest25/library/optparse.rst	2008-12-19 16:58:07.000000000 +0900
+++ rest262/library/optparse.rst	2009-04-05 05:02:09.000000000 +0900
@@ -1,39 +1,32 @@
-.. % THIS FILE IS AUTO-GENERATED!  DO NOT EDIT!
-.. % (Your changes will be lost the next time it is generated.)
-
-
 :mod:`optparse` --- More powerful command line option parser
 ============================================================
 
 .. module:: optparse
    :synopsis: More convenient, flexible, and powerful command-line parsing library.
 .. moduleauthor:: Greg Ward <gward@python.net>
 
 
 .. versionadded:: 2.3
 
 .. sectionauthor:: Greg Ward <gward@python.net>
 
 
 ``optparse`` is a more convenient, flexible, and powerful library for parsing
-command-line options than ``getopt``.  ``optparse`` uses a more declarative
+command-line options than the old :mod:`getopt` module.  ``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. ``optparse`` allows users
 to specify options in the conventional GNU/POSIX syntax, and additionally
 generates usage and help messages for you.
 
-.. % An intro blurb used only when generating LaTeX docs for the Python
-.. % manual (based on README.txt).
-
 Here's an example of using ``optparse`` in a simple script::
 
    from optparse import OptionParser
    [...]
    parser = OptionParser()
    parser.add_option("-f", "--file", dest="filename",
                      help="write report to FILE", metavar="FILE")
    parser.add_option("-q", "--quiet",
                      action="store_false", dest="verbose", default=True,
                      help="don't print status messages to stdout")
 
    (options, args) = parser.parse_args()
@@ -65,26 +58,24 @@
 and ``optparse`` will print out a brief summary of your script's options::
 
    usage: <yourscript> [options]
 
    options:
      -h, --help            show this help message and exit
      -f FILE, --file=FILE  write report to FILE
      -q, --quiet           don't print status messages to stdout
 
 where the value of *yourscript* is determined at runtime (normally from
 ``sys.argv[0]``).
 
-.. % $Id: intro.txt 413 2004-09-28 00:59:13Z greg $
-
 
 .. _optparse-background:
 
 Background
 ----------
 
 :mod:`optparse` was explicitly designed to encourage the creation of programs
 with straightforward, conventional command-line interfaces.  To that end, it
 supports only the most common command-line syntax and semantics conventionally
 used under Unix.  If you are unfamiliar with these conventions, read this
 section to acquaint yourself with them.
 
@@ -96,47 +87,47 @@
 
 argument
    a string entered on the command-line, and passed by the shell to ``execl()`` or
    ``execv()``.  In Python, arguments are elements of ``sys.argv[1:]``
    (``sys.argv[0]`` is the name of the program being executed).  Unix shells also
    use the term "word".
 
    It is occasionally desirable to substitute an argument list other than
    ``sys.argv[1:]``, so you should read "argument" as "an element of
    ``sys.argv[1:]``, or of some other list provided as a substitute for
    ``sys.argv[1:]``".
 
-option   
+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 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.
+   * a plus sign followed by a single letter, or a few letters, or a word, e.g.
      ``"+f"``, ``"+rgb"``
 
-*   a slash followed by a letter, or a few letters, or a word, e.g. ``"/f"``,
+   * 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 environment,
    and the last only makes sense if you're exclusively targeting VMS, MS-DOS,
    and/or Windows.
 
 option argument
    an argument that follows an option, is closely associated with that option, and
    is consumed from the argument list when that option is. With :mod:`optparse`,
    option arguments may either be in a separate argument from their option::
 
@@ -228,26 +219,24 @@
 configuration file, or a GUI: if you make that many demands on your users, most
 of them will simply give up.
 
 In short, try to minimize the amount of information that users are absolutely
 required to supply---use sensible defaults whenever possible.  Of course, you
 also want to make your programs reasonably flexible.  That's what options are
 for.  Again, it doesn't matter if they are entries in a config file, widgets in
 the "Preferences" dialog of a GUI, or command-line options---the more options
 you implement, the more flexible your program is, and the more complicated its
 implementation becomes.  Too much flexibility has drawbacks as well, of course;
 too many options can overwhelm users and make your code much harder to maintain.
 
-.. % $Id: tao.txt 413 2004-09-28 00:59:13Z greg $
-
 
 .. _optparse-tutorial:
 
 Tutorial
 --------
 
 While :mod:`optparse` is quite flexible and powerful, it's also straightforward
 to use in most cases.  This section covers the code patterns that are common to
 any :mod:`optparse`\ -based program.
 
 First, you need to import the OptionParser class; then, early in the main
 program, create an OptionParser instance::
@@ -280,45 +269,45 @@
 encounters *option strings* and looks up options from them.
 
 Once all of your options are defined, instruct :mod:`optparse` to parse your
 program's command line::
 
    (options, args) = parser.parse_args()
 
 (If you like, you can pass a custom argument list to :meth:`parse_args`, but
 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
+* ``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
   filename supplied by the user, or ``None`` if the user did not supply that
   option
 
-*   ``args``, the list of positional arguments leftover after parsing options
+* ``args``, the list of positional arguments leftover after parsing options
 
 This tutorial section only covers the four most important option attributes:
 :attr:`action`, :attr:`type`, :attr:`dest` (destination), and :attr:`help`. Of
 these, :attr:`action` is the most fundamental.
 
 
 .. _optparse-understanding-option-actions:
 
 Understanding option actions
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Actions tell :mod:`optparse` what to do when it encounters an option on the
 command line.  There is a fixed set of actions hard-coded into :mod:`optparse`;
 adding new actions is an advanced topic covered in section
-:ref:`optparse-extending-optparse`, Extending :mod:`optparse`. Most actions tell
+:ref:`optparse-extending-optparse`. Most actions tell
 :mod:`optparse` to store a value in some variable---for example, take a string
 from the command line and store it in an attribute of ``options``.
 
 If you don't specify an option action, :mod:`optparse` defaults to ``store``.
 
 
 .. _optparse-store-action:
 
 The store action
 ^^^^^^^^^^^^^^^^
 
 The most common option action is ``store``, which tells :mod:`optparse` to take
@@ -360,26 +349,25 @@
 the fact that the default action is ``store``, that means our first example can
 be a lot shorter::
 
    parser.add_option("-f", "--file", dest="filename")
 
 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
 long option strings, :mod:`optparse` looks at the first short option string: the
 default destination for ``"-f"`` is ``f``.
 
 :mod:`optparse` also includes built-in ``long`` and ``complex`` types.  Adding
-types is covered in section :ref:`optparse-extending-optparse`, Extending
-:mod:`optparse`.
+types is covered in section :ref:`optparse-extending-optparse`.
 
 
 .. _optparse-handling-boolean-options:
 
 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"``::
 
@@ -406,25 +394,25 @@
    store a constant value
 
 ``append``
    append this option's argument to a list
 
 ``count``
    increment a counter by one
 
 ``callback``
    call a specified function
 
 These are covered in section :ref:`optparse-reference-guide`, Reference Guide
-and section :ref:`optparse-option-callbacks`, Option Callbacks.
+and section :ref:`optparse-option-callbacks`.
 
 
 .. _optparse-default-values:
 
 Default values
 ^^^^^^^^^^^^^^
 
 All of the above examples involve setting some variable (the "destination") when
 certain command-line options are seen.  What happens if those options are never
 seen?  Since we didn't supply any defaults, they are all set to ``None``.  This
 is usually fine, but sometimes you want more control.  :mod:`optparse` lets you
 supply a default value for each destination, which is assigned before the
@@ -462,104 +450,134 @@
 that counts.  For clarity, try to use one method or the other of setting default
 values, not both.
 
 
 .. _optparse-generating-help:
 
 Generating help
 ^^^^^^^^^^^^^^^
 
 :mod:`optparse`'s ability to generate help and usage text automatically is
 useful for creating user-friendly command-line interfaces.  All you have to do
 is supply a :attr:`help` value for each option, and optionally a short usage
-message for your whole program.  Here's an OptionParser populated with user-
-friendly (documented) options::
+message for your whole program.  Here's an OptionParser populated with
+user-friendly (documented) options::
 
    usage = "usage: %prog [options] arg1 arg2"
    parser = OptionParser(usage=usage)
    parser.add_option("-v", "--verbose",
                      action="store_true", dest="verbose", default=True,
                      help="make lots of noise [default]")
    parser.add_option("-q", "--quiet",
-                     action="store_false", dest="verbose", 
+                     action="store_false", dest="verbose",
                      help="be vewwy quiet (I'm hunting wabbits)")
    parser.add_option("-f", "--filename",
                      metavar="FILE", help="write output to FILE"),
    parser.add_option("-m", "--mode",
                      default="intermediate",
                      help="interaction mode: novice, intermediate, "
                           "or expert [default: %default]")
 
-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::
+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::
 
    usage: <yourscript> [options] arg1 arg2
 
    options:
      -h, --help            show this help message and exit
      -v, --verbose         make lots of noise [default]
      -q, --quiet           be vewwy quiet (I'm hunting wabbits)
      -f FILE, --filename=FILE
                            write output to FILE
      -m MODE, --mode=MODE  interaction mode: novice, intermediate, or
                            expert [default: intermediate]
 
 (If the help output is triggered by a help option, :mod:`optparse` exits after
 printing the help text.)
 
 There's a lot going on here to help :mod:`optparse` generate the best possible
 help message:
 
-*   the script defines its own usage message::
+* the script defines its own usage message::
 
      usage = "usage: %prog [options] arg1 arg2"
 
   :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.
 
   If you don't supply a usage string, :mod:`optparse` uses a bland but sensible
-  default: "``usage: %prog [options]"``, which is fine if your script doesn't take
+  default: ``"usage: %prog [options]"``, which is fine if your script doesn't take
   any positional arguments.
 
-*   every option defines a help string, and doesn't worry about line-
-  wrapping---\ :mod:`optparse` takes care of wrapping lines and making the help
-  output look good.
+* every option defines a help string, and doesn't worry about line-wrapping---
+  :mod:`optparse` takes care of wrapping lines and making the help output look
+  good.
 
-*   options that take a value indicate this fact in their automatically-
-  generated help message, e.g. for the "mode" option::
+* options that take a value indicate this fact in their automatically-generated
+  help message, e.g. for the "mode" option::
 
      -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,
   :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"``, 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 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.
 
-*   options that have a default value can include ``%default`` in the help
-  string---\ :mod:`optparse` will replace it with :func:`str` of the option's
-  default value.  If an option has no default value (or the default value is
-  ``None``), ``%default`` expands to ``none``.
-
+.. versionadded:: 2.4
+   Options that have a default value can include ``%default`` in the help
+   string---\ :mod:`optparse` will replace it with :func:`str` of the option's
+   default value.  If an option has no default value (or the default value is
+   ``None``), ``%default`` expands to ``none``.
+
+When dealing with many options, it is convenient to group these
+options for better help output.  An :class:`OptionParser` can contain
+several option groups, each of which can contain several options.
+
+Continuing with the parser defined above, adding an
+:class:`OptionGroup` to a parser is easy::
+
+    group = OptionGroup(parser, "Dangerous Options",
+                        "Caution: use these options at your own risk.  "
+                        "It is believed that some of them bite.")
+    group.add_option("-g", action="store_true", help="Group option.")
+    parser.add_option_group(group)
+
+This would result in the following help output::
+
+    usage:  [options] arg1 arg2
+
+    options:
+      -h, --help           show this help message and exit
+      -v, --verbose        make lots of noise [default]
+      -q, --quiet          be vewwy quiet (I'm hunting wabbits)
+      -fFILE, --file=FILE  write output to FILE
+      -mMODE, --mode=MODE  interaction mode: one of 'novice', 'intermediate'
+                           [default], 'expert'
+
+      Dangerous Options:
+      Caution: use of these options is at your own risk.  It is believed that
+      some of them bite.
+      -g                 Group option.
 
 .. _optparse-printing-version-string:
 
 Printing a version string
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Similar to the brief usage string, :mod:`optparse` can also print a version
 string for your program.  You have to supply the string as the ``version``
 argument to OptionParser::
 
    parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0")
 
@@ -575,25 +593,25 @@
    foo 1.0
 
 
 .. _optparse-how-optparse-handles-errors:
 
 How :mod:`optparse` handles errors
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 There are two broad classes of errors that :mod:`optparse` has to worry about:
 programmer errors and user errors.  Programmer errors are usually erroneous
 calls to ``parser.add_option()``, e.g. invalid option strings, unknown option
 attributes, missing option attributes, etc.  These are dealt with in the usual
-way: raise an exception (either ``optparse.OptionError`` or ``TypeError``) and
+way: raise an exception (either ``optparse.OptionError`` or :exc:`TypeError`) and
 let the program crash.
 
 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,
 you can call ``parser.error()`` to signal an application-defined error
 condition::
 
    (options, args) = parser.parse_args()
    [...]
@@ -614,27 +632,27 @@
 
 Or, where the user fails to pass a value at all::
 
    $ /usr/bin/foo -n
    usage: foo [options]
 
    foo: error: -n option requires an argument
 
 :mod:`optparse`\ -generated error messages take care always to mention the
 option involved in the error; be sure to do the same when calling
 ``parser.error()`` from your application code.
 
-If :mod:`optparse`'s default error-handling behaviour does not suite your needs,
-you'll need to subclass OptionParser and override ``exit()`` and/or
-:meth:`error`.
+If :mod:`optparse`'s default error-handling behaviour does not suit your needs,
+you'll need to subclass OptionParser and override its :meth:`exit` and/or
+:meth:`error` methods.
 
 
 .. _optparse-putting-it-all-together:
 
 Putting it all together
 ^^^^^^^^^^^^^^^^^^^^^^^
 
 Here's what :mod:`optparse`\ -based scripts usually look like::
 
    from optparse import OptionParser
    [...]
    def main():
@@ -648,26 +666,24 @@
                          action="store_false", dest="verbose")
        [...]
        (options, args) = parser.parse_args()
        if len(args) != 1:
            parser.error("incorrect number of arguments")
        if options.verbose:
            print "reading %s..." % options.filename
        [...]
 
    if __name__ == "__main__":
        main()
 
-.. % $Id: tutorial.txt 515 2006-06-10 15:37:45Z gward $
-
 
 .. _optparse-reference-guide:
 
 Reference Guide
 ---------------
 
 
 .. _optparse-creating-parser:
 
 Creating the parser
 ^^^^^^^^^^^^^^^^^^^
 
@@ -695,26 +711,25 @@
 
    ``option_class`` (default: optparse.Option)
       Class to use when adding options to the parser in :meth:`add_option`.
 
    ``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``.
 
    ``conflict_handler`` (default: ``"error"``)
       Specifies what to do when options with conflicting option strings are added to
-      the parser; see section :ref:`optparse-conflicts-between-options`, Conflicts
-      between options.
+      the parser; see section :ref:`optparse-conflicts-between-options`.
 
    ``description`` (default: ``None``)
       A paragraph of text giving a brief overview of your program.  :mod:`optparse`
       reformats this paragraph to fit the current terminal width and prints it when
       the user requests help (after ``usage``, but before the list of options).
 
    ``formatter`` (default: a new IndentedHelpFormatter)
       An instance of optparse.HelpFormatter that will be used for printing help text.
       :mod:`optparse` provides two concrete classes for this purpose:
       IndentedHelpFormatter and TitledHelpFormatter.
 
    ``add_help_option`` (default: ``True``)
@@ -725,30 +740,29 @@
       The string to use when expanding ``"%prog"`` in ``usage`` and ``version``
       instead of ``os.path.basename(sys.argv[0])``.
 
 
 
 .. _optparse-populating-parser:
 
 Populating the parser
 ^^^^^^^^^^^^^^^^^^^^^
 
 There are several ways to populate the parser with options.  The preferred way
 is by using ``OptionParser.add_option()``, as shown in section
-:ref:`optparse-tutorial`, the tutorial.  :meth:`add_option` can be called in one
-of two ways:
+:ref:`optparse-tutorial`.  :meth:`add_option` can be called in one of two ways:
 
-*   pass it an Option instance (as returned by :func:`make_option`)
+* pass it an Option instance (as returned by :func:`make_option`)
 
-*   pass it any combination of positional and keyword arguments that are
+* pass it any combination of positional and keyword arguments that are
   acceptable to :func:`make_option` (i.e., to the Option constructor), and it will
   create the Option instance for you
 
 The other alternative is to pass a list of pre-constructed Option instances to
 the OptionParser constructor, as in::
 
    option_list = [
        make_option("-f", "--filename",
                    action="store", type="string", dest="filename"),
        make_option("-q", "--quiet",
                    action="store_false", dest="verbose"),
        ]
@@ -776,28 +790,28 @@
 
 To define an option with only a short option string::
 
    parser.add_option("-f", attr=value, ...)
 
 And to define an option with only a long option string::
 
    parser.add_option("--foo", attr=value, ...)
 
 The keyword arguments define attributes of the new Option object.  The most
 important option attribute is :attr:`action`, and it largely determines which
 other attributes are relevant or required.  If you pass irrelevant option
-attributes, or fail to pass required ones, :mod:`optparse` raises an OptionError
-exception explaining your mistake.
+attributes, or fail to pass required ones, :mod:`optparse` raises an
+:exc:`OptionError` exception explaining your mistake.
 
-An options's *action* determines what :mod:`optparse` does when it encounters
+An option's *action* determines what :mod:`optparse` does when it encounters
 this option on the command-line.  The standard option actions hard-coded into
 :mod:`optparse` are:
 
 ``store``
    store this option's argument (default)
 
 ``store_const``
    store a constant value
 
 ``store_true``
    store a true value
 
@@ -857,25 +871,25 @@
 
 
 .. _optparse-standard-option-actions:
 
 Standard option actions
 ^^^^^^^^^^^^^^^^^^^^^^^
 
 The various option actions all have slightly different requirements and effects.
 Most actions have several relevant option attributes which you may specify to
 guide :mod:`optparse`'s behaviour; a few have required attributes, which you
 must specify for any option using that action.
 
-*   ``store`` [relevant: :attr:`type`, :attr:`dest`, ``nargs``, ``choices``]
+* ``store`` [relevant: :attr:`type`, :attr:`dest`, ``nargs``, ``choices``]
 
   The option must be followed by an argument, which is converted to a value
   according to :attr:`type` and stored in :attr:`dest`.  If ``nargs`` > 1,
   multiple arguments will be consumed from the command line; all will be converted
   according to :attr:`type` and stored to :attr:`dest` as a tuple.  See the
   "Option types" section below.
 
   If ``choices`` is supplied (a list or tuple of strings), the type defaults to
   ``choice``.
 
   If :attr:`type` is not supplied, it defaults to ``string``.
 
@@ -890,114 +904,114 @@
      parser.add_option("-p", type="float", nargs=3, dest="point")
 
   As it parses the command line  ::
 
      -f foo.txt -p 1 -3.5 4 -fbar.txt
 
   :mod:`optparse` will set  ::
 
      options.f = "foo.txt"
      options.point = (1.0, -3.5, 4.0)
      options.f = "bar.txt"
 
-*   ``store_const`` [required: ``const``; relevant: :attr:`dest`]
+* ``store_const`` [required: ``const``; relevant: :attr:`dest`]
 
   The value ``const`` is stored in :attr:`dest`.
 
   Example::
 
      parser.add_option("-q", "--quiet",
                        action="store_const", const=0, dest="verbose")
      parser.add_option("-v", "--verbose",
                        action="store_const", const=1, dest="verbose")
      parser.add_option("--noisy",
                        action="store_const", const=2, dest="verbose")
 
   If ``"--noisy"`` is seen, :mod:`optparse` will set  ::
 
      options.verbose = 2
 
-*   ``store_true`` [relevant: :attr:`dest`]
+* ``store_true`` [relevant: :attr:`dest`]
 
   A special case of ``store_const`` that stores a true value to :attr:`dest`.
 
-*   ``store_false`` [relevant: :attr:`dest`]
+* ``store_false`` [relevant: :attr:`dest`]
 
   Like ``store_true``, but stores a false value.
 
   Example::
 
      parser.add_option("--clobber", action="store_true", dest="clobber")
      parser.add_option("--no-clobber", action="store_false", dest="clobber")
 
-*   ``append`` [relevant: :attr:`type`, :attr:`dest`, ``nargs``, ``choices``]
+* ``append`` [relevant: :attr:`type`, :attr:`dest`, ``nargs``, ``choices``]
 
   The option must be followed by an argument, which is appended to the list in
   :attr:`dest`.  If no default value for :attr:`dest` is supplied, an empty list
   is automatically created when :mod:`optparse` first encounters this option on
   the command-line.  If ``nargs`` > 1, multiple arguments are consumed, and a
   tuple of length ``nargs`` is appended to :attr:`dest`.
 
   The defaults for :attr:`type` and :attr:`dest` are the same as for the ``store``
   action.
 
   Example::
 
      parser.add_option("-t", "--tracks", action="append", type="int")
 
   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::
 
      options.tracks.append(int("4"))
 
-*   ``append_const`` [required: ``const``; relevant: :attr:`dest`]
+* ``append_const`` [required: ``const``; relevant: :attr:`dest`]
 
   Like ``store_const``, but the value ``const`` is appended to :attr:`dest`; as
-  with ``append``, :attr:`dest` defaults to ``None``, and an an empty list is
+  with ``append``, :attr:`dest` defaults to ``None``, and an empty list is
   automatically created the first time the option is encountered.
 
-*   ``count`` [relevant: :attr:`dest`]
+* ``count`` [relevant: :attr:`dest`]
 
   Increment the integer stored at :attr:`dest`.  If no default value is supplied,
   :attr:`dest` is set to zero before being incremented the first time.
 
   Example::
 
      parser.add_option("-v", action="count", dest="verbosity")
 
   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  ::
 
      options.verbosity += 1
 
-*   ``callback`` [required: ``callback``; relevant: :attr:`type`, ``nargs``,
+* ``callback`` [required: ``callback``; relevant: :attr:`type`, ``nargs``,
   ``callback_args``, ``callback_kwargs``]
 
   Call the function specified by ``callback``, which is called as  ::
 
      func(option, opt_str, value, parser, *args, **kwargs)
 
-  See section :ref:`optparse-option-callbacks`, Option Callbacks for more detail.
+  See section :ref:`optparse-option-callbacks` for more detail.
 
-*   :attr:`help`
+* :attr:`help`
 
   Prints a complete help message for all the options in the current option parser.
   The help message is constructed from the ``usage`` string passed to
   OptionParser's constructor and the :attr:`help` string passed to every option.
 
   If no :attr:`help` string is supplied for an option, it will still be listed in
   the help message.  To omit an option entirely, use the special value
   ``optparse.SUPPRESS_HELP``.
 
   :mod:`optparse` automatically adds a :attr:`help` option to all OptionParsers,
   so you do not normally need to create one.
 
@@ -1018,154 +1032,154 @@
   ``sys.argv[0]`` is ``"foo.py"``)::
 
      usage: foo.py [options]
 
      options:
        -h, --help        Show this help message and exit
        -v                Be moderately verbose
        --file=FILENAME   Input file to read data from
 
   After printing the help message, :mod:`optparse` terminates your process with
   ``sys.exit(0)``.
 
-*   ``version``
+* ``version``
 
   Prints the version number supplied to the OptionParser to stdout and exits.  The
   version number is actually formatted and printed by the ``print_version()``
   method of OptionParser.  Generally only relevant if the ``version`` argument is
   supplied to the OptionParser constructor.  As with :attr:`help` options, you
   will rarely create ``version`` options, since :mod:`optparse` automatically adds
   them when needed.
 
 
 .. _optparse-option-attributes:
 
 Option attributes
 ^^^^^^^^^^^^^^^^^
 
 The following option attributes may be passed as keyword arguments to
 ``parser.add_option()``.  If you pass an option attribute that is not relevant
 to a particular option, or fail to pass a required option attribute,
-:mod:`optparse` raises OptionError.
+:mod:`optparse` raises :exc:`OptionError`.
 
-*   :attr:`action` (default: ``"store"``)
+* :attr:`action` (default: ``"store"``)
 
   Determines :mod:`optparse`'s behaviour when this option is seen on the command
   line; the available options are documented above.
 
-*   :attr:`type` (default: ``"string"``)
+* :attr:`type` (default: ``"string"``)
 
   The argument type expected by this option (e.g., ``"string"`` or ``"int"``); the
   available option types are documented below.
 
-*   :attr:`dest` (default: derived from option strings)
+* :attr:`dest` (default: derived from option strings)
 
   If the option's action implies writing or modifying a value somewhere, this
   tells :mod:`optparse` where to write it: :attr:`dest` names an attribute of the
   ``options`` object that :mod:`optparse` builds as it parses the command line.
 
-*   ``default`` (deprecated)
+* ``default`` (deprecated)
 
   The value to use for this option's destination if the option is not seen on the
   command line.  Deprecated; use ``parser.set_defaults()`` instead.
 
-*   ``nargs`` (default: 1)
+* ``nargs`` (default: 1)
 
   How many arguments of type :attr:`type` should be consumed when this option is
   seen.  If > 1, :mod:`optparse` will store a tuple of values to :attr:`dest`.
 
-*   ``const``
+* ``const``
 
   For actions that store a constant value, the constant value to store.
 
-*   ``choices``
+* ``choices``
 
   For options of type ``"choice"``, the list of strings the user may choose from.
 
-*   ``callback``
+* ``callback``
 
-  For options with action ``"callback"``, the callable to call when this option is
-  seen.  See section :ref:`optparse-option-callbacks`, Option Callbacks for detail
-  on the arguments passed to ``callable``.
+  For options with action ``"callback"``, the callable to call when this option
+  is seen.  See section :ref:`optparse-option-callbacks` for detail on the
+  arguments passed to ``callable``.
 
-*   ``callback_args``, ``callback_kwargs``
+* ``callback_args``, ``callback_kwargs``
 
   Additional positional and keyword arguments to pass to ``callback`` after the
   four standard callback arguments.
 
-*   :attr:`help`
+* :attr:`help`
 
   Help text to print for this option when listing all available options after the
   user supplies a :attr:`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 ``SUPPRESS_HELP``.
 
-*   ``metavar`` (default: derived from option strings)
+* ``metavar`` (default: derived from option strings)
 
   Stand-in for the option argument(s) to use when printing help text. See section
-  :ref:`optparse-tutorial`, the tutorial for an example.
+  :ref:`optparse-tutorial` for an example.
 
 
 .. _optparse-standard-option-types:
 
 Standard option types
 ^^^^^^^^^^^^^^^^^^^^^
 
 :mod:`optparse` has six built-in option types: ``string``, ``int``, ``long``,
 ``choice``, ``float`` and ``complex``.  If you need to add new option types, see
-section :ref:`optparse-extending-optparse`, Extending :mod:`optparse`.
+section :ref:`optparse-extending-optparse`.
 
 Arguments to string options are not checked or converted in any way: the text on
 the command line is stored in the destination (or passed to the callback) as-is.
 
 Integer arguments (type ``int`` or ``long``) are parsed as follows:
 
-*   if the number starts with ``0x``, it is parsed as a hexadecimal number
+* if the number starts with ``0x``, it is parsed as a hexadecimal number
 
-*   if the number starts with ``0``, it is parsed as an octal number
+* if the number starts with ``0``, it is parsed as an octal number
 
-*   if the number starts with ``0b``, is is parsed as a binary number
+* if the number starts with ``0b``, it is parsed as a binary number
 
-*   otherwise, the number is parsed as a decimal number
+* otherwise, the number is parsed as a decimal number
 
 
 The conversion is done by calling either ``int()`` or ``long()`` with the
 appropriate base (2, 8, 10, or 16).  If this fails, so will :mod:`optparse`,
 although with a more useful error message.
 
 ``float`` and ``complex`` option arguments are converted directly with
 ``float()`` and ``complex()``, with similar error-handling.
 
 ``choice`` options are a subtype of ``string`` options.  The ``choices`` option
 attribute (a sequence of strings) defines the set of allowed option arguments.
 ``optparse.check_choice()`` compares user-supplied option arguments against this
-master list and raises OptionValueError if an invalid string is given.
+master list and raises :exc:`OptionValueError` if an invalid string is given.
 
 
 .. _optparse-parsing-arguments:
 
 Parsing arguments
 ^^^^^^^^^^^^^^^^^
 
 The whole point of creating and populating an OptionParser is to call its
 :meth:`parse_args` method::
 
-   (options, args) = parser.parse_args(args=None, options=None)
+   (options, args) = parser.parse_args(args=None, values=None)
 
 where the input parameters are
 
 ``args``
    the list of arguments to process (default: ``sys.argv[1:]``)
 
-``options``
+``values``
    object to store option arguments in (default: a new instance of optparse.Values)
 
 and the return values are
 
 ``options``
    the same object that was passed in as ``options``, or the optparse.Values
    instance created by :mod:`optparse`
 
 ``args``
    the leftover positional arguments after all options have been processed
 
 The most common usage is to supply neither keyword argument.  If you supply
@@ -1175,40 +1189,55 @@
 
 If :meth:`parse_args` encounters any errors in the argument list, it calls the
 OptionParser's :meth:`error` method with an appropriate end-user error message.
 This ultimately terminates your process with an exit status of 2 (the
 traditional Unix exit status for command-line errors).
 
 
 .. _optparse-querying-manipulating-option-parser:
 
 Querying and manipulating your option parser
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Sometimes, it's useful to poke around your option parser and see what's there.
-OptionParser provides a couple of methods to help you out:
+The default behavior of the option parser can be customized slightly,
+and you can also poke around your option parser and see what's there.
+OptionParser provides several methods to help you out:
+
+``disable_interspersed_args()``
+  Set parsing to stop on the first non-option. Use this if you have a
+  command processor which runs another command which has options of
+  its own and you want to make sure these options don't get
+  confused. For example, each command might have a different
+  set of options.
+
+``enable_interspersed_args()``
+  Set parsing to not stop on the first non-option, allowing
+  interspersing switches with command arguments.  For example,
+  ``"-s arg1 --long arg2"`` would return ``["arg1", "arg2"]``
+  as the command arguments and ``-s, --long`` as options.
+  This is the default behavior.
 
 ``get_option(opt_str)``
    Returns the Option instance with the option string ``opt_str``, or ``None`` if
    no options have that option string.
 
-``has_option(opt_str)``
-   Return true if the OptionParser has an option with  option string ``opt_str``
-   (e.g., ``"-q"`` or ``"--verbose"``).
+``has_option(opt_str)``
+   Return true if the OptionParser has an option with option string ``opt_str``
+   (e.g., ``"-q"`` or ``"--verbose"``).
+
 ``remove_option(opt_str)``
-   If the OptionParser has an option corresponding to ``opt_str``, that option is
+   If the :class:`OptionParser` has an option corresponding to ``opt_str``, that option is
    removed.  If that option provided any other option strings, all of those option
    strings become invalid. If ``opt_str`` does not occur in any option belonging to
-   this OptionParser, raises ValueError.
+   this :class:`OptionParser`, raises :exc:`ValueError`.
 
 
 .. _optparse-conflicts-between-options:
 
 Conflicts between options
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
 If you're not careful, it's easy to define options with conflicting option
 strings::
 
    parser.add_option("-n", "--dry-run", ...)
    [...]
@@ -1221,31 +1250,31 @@
 options.  If it finds any, it invokes the current conflict-handling mechanism.
 You can set the conflict-handling mechanism either in the constructor::
 
    parser = OptionParser(..., conflict_handler=handler)
 
 or with a separate call::
 
    parser.set_conflict_handler(handler)
 
 The available conflict handlers are:
 
    ``error`` (default)
-      assume option conflicts are a programming error and raise  OptionConflictError
+      assume option conflicts are a programming error and raise :exc:`OptionConflictError`
 
    ``resolve``
       resolve option conflicts intelligently (see below)
 
 
-As an example, let's define an OptionParser that resolves conflicts
+As an example, let's define an :class:`OptionParser` that resolves conflicts
 intelligently and add conflicting options to it::
 
    parser = OptionParser(conflict_handler="resolve")
    parser.add_option("-n", "--dry-run", ..., help="do no harm")
    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
 that option.  If the user asks for help, the help message will reflect that::
 
@@ -1281,88 +1310,86 @@
 references explicitly by calling ``destroy()`` on your OptionParser once you are
 done with it.  This is particularly useful in long-running applications where
 large object graphs are reachable from your OptionParser.
 
 
 .. _optparse-other-methods:
 
 Other methods
 ^^^^^^^^^^^^^
 
 OptionParser supports several other public methods:
 
-*   ``set_usage(usage)``
+* ``set_usage(usage)``
 
   Set the usage string according to the rules described above for the ``usage``
   constructor keyword argument.  Passing ``None`` sets the default usage string;
   use ``SUPPRESS_USAGE`` to suppress a usage message.
 
-*   ``enable_interspersed_args()``, ``disable_interspersed_args()``
+* ``enable_interspersed_args()``, ``disable_interspersed_args()``
 
   Enable/disable positional arguments interspersed with options, similar to GNU
   getopt (enabled by default).  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
 
   and treats it as equivalent to  ::
 
      prog -a -b arg1 arg2
 
   To disable this feature, call ``disable_interspersed_args()``.  This restores
   traditional Unix syntax, where option parsing stops with the first non-option
   argument.
 
-*   ``set_defaults(dest=value, ...)``
+* ``set_defaults(dest=value, ...)``
 
   Set default values for several option destinations at once.  Using
   :meth:`set_defaults` is the preferred way to set default values for options,
   since multiple options can share the same destination.  For example, if several
   "mode" options all set the same destination, any one of them can set the
   default, and the last one wins::
 
      parser.add_option("--advanced", action="store_const",
                        dest="mode", const="advanced",
                        default="novice")    # overridden below
      parser.add_option("--novice", action="store_const",
                        dest="mode", const="novice",
                        default="advanced")  # overrides above setting
 
   To avoid this confusion, use :meth:`set_defaults`::
 
      parser.set_defaults(mode="advanced")
      parser.add_option("--advanced", action="store_const",
                        dest="mode", const="advanced")
      parser.add_option("--novice", action="store_const",
                        dest="mode", const="novice")
 
-.. % $Id: reference.txt 519 2006-06-11 14:39:11Z gward $
-
 
 .. _optparse-option-callbacks:
 
 Option Callbacks
 ----------------
 
 When :mod:`optparse`'s built-in actions and types aren't quite enough for your
 needs, you have two choices: extend :mod:`optparse` or define a callback option.
 Extending :mod:`optparse` is more general, but overkill for a lot of simple
 cases.  Quite often a simple callback is all you need.
 
 There are two steps to defining a callback option:
 
-*   define the option itself using the ``callback`` action
+* define the option itself using the ``callback`` action
 
-*   write the callback; this is a function (or method) that takes at least four
+* write the callback; this is a function (or method) that takes at least four
   arguments, as described below
 
 
 .. _optparse-defining-callback-option:
 
 Defining a callback option
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 As always, the easiest way to define a callback option is by using the
 ``parser.add_option()`` method.  Apart from :attr:`action`, the only option
 attribute you must specify is ``callback``, the function to call::
 
@@ -1459,41 +1486,41 @@
    is a tuple of arbitrary positional arguments supplied via the ``callback_args``
    option attribute.
 
 ``kwargs``
    is a dictionary of arbitrary keyword arguments supplied via ``callback_kwargs``.
 
 
 .. _optparse-raising-errors-in-callback:
 
 Raising errors in a callback
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The callback function should raise OptionValueError if there are any problems
+The callback function should raise :exc:`OptionValueError` if there are any problems
 with the option or its argument(s).  :mod:`optparse` catches this and terminates
 the program, printing the error message you supply to stderr.  Your message
 should be clear, concise, accurate, and mention the option at fault.  Otherwise,
 the user will have a hard time figuring out what he did wrong.
 
 
 .. _optparse-callback-example-1:
 
 Callback example 1: trivial callback
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Here's an example of a callback option that takes no arguments, and simply
 records that the option was seen::
 
    def record_foo_seen(option, opt_str, value, parser):
-       parser.saw_foo = True
+       parser.values.saw_foo = True
 
    parser.add_option("--foo", action="callback", callback=record_foo_seen)
 
 Of course, you could do that with the ``store_true`` action.
 
 
 .. _optparse-callback-example-2:
 
 Callback example 2: check option order
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Here's a slightly more interesting example: record the fact that ``"-a"`` is
@@ -1577,72 +1604,67 @@
 .. _optparse-callback-example-6:
 
 Callback example 6: variable arguments
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Things get hairy when you want an option to take a variable number of arguments.
 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:
 
-*   either ``"--"`` or ``"-"`` can be option arguments
+* either ``"--"`` or ``"-"`` can be option arguments
 
-*   bare ``"--"`` (if not the argument to some option): halt command-line
+* 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
+* 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
 choose will be based on which trade-offs you're willing to make for your
 application (which is why :mod:`optparse` doesn't support this sort of thing
 directly).
 
 Nevertheless, here's a stab at a callback for an option with variable
 arguments::
 
-   def vararg_callback(option, opt_str, value, parser):
-       assert value is None
-       done = 0
-       value = []
-       rargs = parser.rargs
-       while rargs:
-           arg = rargs[0]
-
-           # Stop if we hit an arg like "--foo", "-a", "-fx", "--file=f",
-           # etc.  Note that this also stops on "-3" or "-3.0", so if
-           # your option takes numeric values, you will need to handle
-           # this.
-           if ((arg[:2] == "--" and len(arg) > 2) or
-               (arg[:1] == "-" and len(arg) > 1 and arg[1] != "-")):
-               break
-           else:
-               value.append(arg)
-               del rargs[0]
+    def vararg_callback(option, opt_str, value, parser):
+        assert value is None
+        value = []
+
+        def floatable(str):
+            try:
+                float(str)
+                return True
+            except ValueError:
+                return False
+
+        for arg in parser.rargs:
+            # stop on --foo like options
+            if arg[:2] == "--" and len(arg) > 2:
+                break
+            # stop on -a, but not on -3 or -3.0
+            if arg[:1] == "-" and len(arg) > 1 and not floatable(arg):
+                break
+            value.append(arg)
 
+        del parser.rargs[:len(value)]
         setattr(parser.values, option.dest, value)
 
    [...]
-   parser.add_option("-c", "--callback",
-                     action="callback", callback=varargs)
-
-The main weakness with this particular implementation is that negative numbers
-in the arguments following ``"-c"`` will be interpreted as further options
-(probably causing an error), rather than as arguments to ``"-c"``.  Fixing this
-is left as an exercise for the reader.
-
-.. % $Id: callbacks.txt 415 2004-09-30 02:26:17Z greg $
+   parser.add_option("-c", "--callback", dest="vararg_attr",
+                     action="callback", callback=vararg_callback)
 
 
 .. _optparse-extending-optparse:
 
 Extending :mod:`optparse`
 -------------------------
 
 Since the two major controlling factors in how :mod:`optparse` interprets
 command-line options are the action and type of each option, the most likely
 direction of extension is to add new actions and new types.
 
 
@@ -1657,32 +1679,32 @@
 
 :attr:`TYPES` is a tuple of type names; in your subclass, simply define a new
 tuple :attr:`TYPES` that builds on the standard one.
 
 :attr:`TYPE_CHECKER` is a dictionary mapping type names to type-checking
 functions.  A type-checking function has the following signature::
 
    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 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 by
+object of the hypothetical type ``mytype``.  The value returned by a
+type-checking function will wind up in the OptionValues instance returned by
 :meth:`OptionParser.parse_args`, or be passed to a callback as the ``value``
 parameter.
 
-Your type-checking function should raise OptionValueError if it encounters any
-problems.  OptionValueError takes a single string argument, which is passed as-
-is to OptionParser's :meth:`error` method, which in turn prepends the program
+Your type-checking function should raise :exc:`OptionValueError` if it encounters any
+problems.  :exc:`OptionValueError` takes a single string argument, which is passed
+as-is to :class:`OptionParser`'s :meth:`error` method, which in turn prepends the program
 name and the string ``"error:"`` and prints everything to stderr before
 terminating the process.
 
 Here's a silly example that demonstrates adding a ``complex`` option type to
 parse Python-style complex numbers on the command line.  (This is even sillier
 than it used to be, because :mod:`optparse` 1.3 added built-in support for
 complex numbers, but never mind.)
 
 First, the necessary imports::
 
    from copy import copy
    from optparse import Option, OptionValueError
@@ -1790,41 +1812,38 @@
        ALWAYS_TYPED_ACTIONS = Option.ALWAYS_TYPED_ACTIONS + ("extend",)
 
        def take_action(self, action, dest, opt, value, values, parser):
            if action == "extend":
                lvalue = value.split(",")
                values.ensure_value(dest, []).extend(lvalue)
            else:
                Option.take_action(
                    self, action, dest, opt, value, values, parser)
 
 Features of note:
 
-*   ``extend`` both expects a value on the command-line and stores that value
+* ``extend`` both expects a value on the command-line and stores that value
   somewhere, so it goes in both :attr:`STORE_ACTIONS` and :attr:`TYPED_ACTIONS`
 
-*   to ensure that :mod:`optparse` assigns the default type of ``string`` to
+* to ensure that :mod:`optparse` assigns the default type of ``string`` to
   ``extend`` actions, we put the ``extend`` action in ``ALWAYS_TYPED_ACTIONS`` as
   well
 
-*   :meth:`MyOption.take_action` implements just this one new action, and passes
+* :meth:`MyOption.take_action` implements just this one new action, and passes
   control back to :meth:`Option.take_action` for the standard :mod:`optparse`
   actions
 
-*   ``values`` is an instance of the optparse_parser.Values class, which
+* ``values`` is an instance of the optparse_parser.Values class, which
   provides the very useful :meth:`ensure_value` method. :meth:`ensure_value` is
   essentially :func:`getattr` with a safety valve; it is called as  ::
 
      values.ensure_value(attr, value)
 
   If the ``attr`` attribute of ``values`` doesn't exist or is None, then
   ensure_value() first sets it to ``value``, and then returns 'value. This is very
   handy for actions like ``extend``, ``append``, and ``count``, all of which
   accumulate data in a variable and expect that variable to be of a certain type
   (a list for the first two, an integer for the latter).  Using
   :meth:`ensure_value` means that scripts using your action don't have to worry
   about setting a default value for the option destinations in question; they can
   just leave the default as None and :meth:`ensure_value` will take care of
   getting it right when it's needed.
-
-.. % $Id: extending.txt 517 2006-06-10 16:18:11Z gward $
-
