###
6.20.2.4 Generating help

The last feature that you will use in every script is `optparse`'s ability to generate help messages. All you have to do is supply a help argument when you add an option. Let's create a new parser and populate it 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", "--file", dest="filename",
                      metavar="FILE", help="write output to FILE"),
    parser.add_option("-m", "--mode",
                      default="intermediate",
                      help="interaction mode: one of 'novice', "
                           "'intermediate' [default], 'expert'")

If `optparse` encounters either -h or --help on the command-line, or if you just call `parser.print_help()`, it prints the following to stdout:

    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)
      -fFILE, --file=FILE  write output to FILE
      -mMODE, --mode=MODE  interaction mode: one of 'novice', 'intermediate'
                           [default], 'expert'

There's a lot going on here to help `optparse` generate the best possible help message:

- the script defines its own usage message:

      usage = "usage: %prog [options] arg1 arg2"

  `optparse` expands "`%prog`" in the usage string to the name of the current script, 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.

- every option defines a help string, and doesn't worry about line-wrapping--`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:

      -mMODE, --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:

      -fFILE, --file=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 formal syntax ``-fFILE'' 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.

When dealing with many options, it is convenient to group these options for better help output. An `OptionParser` can contain several option groups, each of which can contain several options.

Continuing with the parser defined above, adding an `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.