###
6.20.2.4 ヘルプを作成する

どのスクリプトでも使うことになる機能の最後の一つは、`optparse` の機能を使ったヘルプメッセージの生成です。やらなければならないことは、 オプションを追加する際に help 値を指定することだけです。 新たなパーザを作成し、ユーザに優しい (ドキュメント付きになっている) オプションを追加していきましょう:

    usage = "usage: %prog [options] arg1 arg2"
    parser = OptionParser(usage=usage)
    parser.add_option("-v", "--verbose",
                      action="store_true", dest="verbose", default=1,
                      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'")

`optparse` がコマンドラインの解析中に -h か ---help に遭遇するか、または単に `parser.print_help()` を呼び出すと、以下の内容を 標準出力に出力します:

    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'

`optparse` に可能な限り親切なヘルプメッセージを出力させる 上で役に立つと思われることを以下にざっと述べます:

- スクリプト自体の使用法メッセージ (usage) を以下のようにして定義 します:

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

  `optparse` は、使用法メッセージ文字列中の "%prog" に 現在のスクリプト名、すなわち `os.path.basename(sys.argv[0])` を展開します。展開された文字列は、詳細なオプションヘルプの前に 出力されます。

  使用法メッセージ文字列を与えなければ、`optparse` は面白みの ない、とはいえ気の利いたデフォルト値: ``usage: %prog [options]'' を使います。スクリプトが固定引数を採っていなければ、この値で かまわないでしょう。

- 各オプションはヘルプ文字列を定義していますが、行の折り返しに ついて悩むことはありません -- `optparse` が行を折り返し、 ヘルプメッセージ出力の見栄えがよくなるよう気を配ります。

- 値をとるオプションについては、そのことを示す内容が ヘルプメッセージ内に自動的に生成されます。例えば、``mode'' オプションは:

      -mMODE, --mode=MODE

  となります。ここで、``MODE'' はメタ変数と呼ばれます: この値は ユーザが -m/--mode に対して指定するよう スクリプトが期待している引数を表します。デフォルトでは、 `optparse` は目的変数の名前を大文字に変換して、メタ変数として使います。 時にこれは期待通りの値になりません -- 例えば、上の例の filename オプションでは明示的に `metavar="FILE"` を設定しており、その結果 自動生成されたオプション説明は以下のようになります:

      -fFILE, --file=FILE

  この機能は重要なもので、それは表示スペースを節約するといった理由 にとどまりません: 上の例では、手作業で書かれたヘルプテキストの 中では、メタ変数として ``FILE'' を使っています。その結果、 ユーザに対して、堅苦しく表現された書法 ``-fFILE'' とくだけた 意味付け説明 ``write output to FILE'' が対応しているという情報 を与えます。これは、ヘルプテキストをエンドユーザに対してより明快で より有用にする上では、単純でありながら効果的な手法です。

数多くのオプションを扱うときには、オプションをグループ化すると ヘルプメッセージ出力をよりよくする上で便利です。`OptionParser` は複数のオプショングループを収めることができ、各グループは 複数のオプションを収めることができます。

上で定義されたパーザに続けて `OptionGroup` を追加するのは 簡単です:

    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)

このコードは以下のヘルプ出力になります:

    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.