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 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:
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", 
                  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 optparse encounters either "-h" or "-help" on the command-line,
or if you just call 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, optparse exits after printing the help text.)
There's a lot going on here to help optparse generate the best possible help message:
usage = "usage: %prog [options] arg1 arg2"
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, optparse uses a bland but sensible
default: ``usage: %prog [options]", which is fine if your script
doesn't take any positional arguments.
-m MODE, --mode=MODE
Here, ``MODE'' is called the meta-variable: it stands for the argument
that the user is expected to supply to -m/--mode.  By default,
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 --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.
%default in
the help string--optparse will replace it with str() of the
option's default value.  If an option has no default value (or the
default value is None), %default expands to none.
See About this document... for information on suggesting changes.