Expand DeprecatedOpt documentation

It is not a priori obvious how deprecated options are chosen, so
expand the docstring a bit

Change-Id: If10b45fb042b4a4d6063129b693228fd6ca86b82
Fix subparsers add_parser() regression

With SubCommandOpt, the handler() callback gets invoked with a
subparsers object which has a add_parser() method. The arguments to
this method match the arguments to the ArgumentParser constructor and
the arguments are passed to the class for our ArgumentParser instance.

However, we added a ArgumentParser subclass (_CachedArgumentParser) so
that we could sort the output of --help ... but the subclass doesn't
support all the arguments of the parent class.

glance-control is the only known example of a SubCommandOpt user which
passes unusual arguments to subparsers.add_parser(). It uses the parent
arg and blows up at startup with:

   File "./bin/glance-control", line 276, in add_command_parsers
     parser = subparsers.add_parser(server, parents=[cmd_parser])
   File "/usr/lib64/python2.7/argparse.py", line 1064, in add_parser
     parser = self._parser_class(**kwargs)
 TypeError: __init__() got an unexpected keyword argument 'parents'

It appears we broke glance-control back in June (commit 2951391), but
nobody noticed it until 1.2.0 was released and broke stable/grizzly
because we stopped using glance-control in the Havana glance unit tests
before this regression.

Closes-Bug: #1230416
Change-Id: I8d1b52e5390295726eb49af32eb7cab14c29592c
Merge "Fix subparsers add_parser() regression"