web-dev-qa-db-ja.com

コマンドライン/シェルのヘルプテキストに「標準」フォーマットはありますか？

そうでない場合、事実上の標準はありますか？基本的に私は次のようなコマンドラインのヘルプテキストを書いています：

usage: app_name [options] required_input required_input2
  options:
    -a, --argument     Does something
    -b required     Does something with "required"
    -c, --command required     Something else
    -d [optlistitem1 optlistitem 2 ... ]     Something with list

基本的にはさまざまなツールのヘルプテキストを読むだけで作成しましたが、ガイドラインや何かのリストはありますか？たとえば、角括弧または括弧を使用しますか？間隔の使用方法引数がリストの場合はどうなりますか？ありがとう！

shellcommand-linecommand-line-arguments
196
Yifan

通常、ヘルプ出力には次のものが含まれます。

  • アプリの機能の説明
  • 使用構文：
    • [options]を使用して、オプションの場所を示します
    • arg_nameは必須の単一引数です
    • [arg_name]はオプションの単数引数
    • arg_name...必要な引数の多くがあります（これはまれです）
    • [arg_name...]は、任意の数を指定できる引数の
    • arg_nameは、説明的な短い名前で、小文字のスネークケースでなければなりません。
  • きれいにフォーマットされたオプションのリスト、それぞれ：
    • 短い説明を持つ
    • デフォルト値がある場合は、デフォルト値を表示します
    • 該当する場合、可能な値を表示する
    • オプションが短い形式（-lなど）または長い形式（--listなど）を受け入れることができる場合は、説明が同じになるため、同じ行に一緒に含めるようにしてください。
  • コマンドライン引数のソースである可能性のある設定ファイルまたは環境変数の場所の簡単なインジケーター。 GREP_OPTS
  • マニュアルページがある場合は、そのように示してください。

さらに、このメッセージをトリガーするために-hと--helpの両方を受け入れるのが良い形式であることに注意してくださいand必須の引数を省略します。

135
davetron5000

docopt をご覧ください。これは、コマンドライン引数を文書化（および自動的に解析）するための正式な標準です。

例えば...

Usage:
  my_program command --option <argument>
  my_program [<optional-argument>]
  my_program --another-option=<with-argument>
  my_program (--either-that-option | <or-this-argument>)
  my_program <repeating-argument> <repeating-argument>...
67
Lily Finley

Microsoftには コマンドライン構文 があります

  • 大括弧または中括弧のないテキスト

    示されているとおりに入力する必要がある項目

  • <山括弧内のテキスト>

    値を指定する必要があるプレースホルダー

  • [角括弧内のテキスト]

    オプション品

  • {中括弧内のテキスト}

    必須アイテムのセット。いずれかを選択してください

  • 縦線（|）

    相互に排他的なアイテムの区切り記号。いずれかを選択してください

  • 省略記号（…）

    繰り返すことができるアイテム

22
Steely Wing

ほとんどがPOSIX準拠のOSであるLinuxを実行しています。 POSIX規格： ユーティリティ引数の構文 。

12
MotherDawg

GNUコーディング標準は、このようなことの良いリファレンスです。 このセクション は--helpの出力を扱います。この場合、あまり具体的ではありません。おそらく、短いオプションと長いオプション、および簡潔な説明を示す表を印刷することで間違いはありません。読みやすくするために、すべての引数の間隔を正しくとるようにしてください。ツールの詳細な説明を提供するために、おそらくmanページ（および場合によってはinfoマニュアル）を提供する必要があります。

8
pmr

マイクロソフトには独自の コマンドライン標準仕様 ：

このドキュメントは、コマンドラインユーティリティの開発者を対象としています。集合的に、私たちの目標は、一貫した構成可能なコマンドラインユーザーエクスペリエンスを提供することです。これにより、ユーザーは概念（構文、命名、動作など）のコアセットを学習し、その知識を多数のコマンドセットでの作業に変換できるようになります。これらのコマンドは、標準化された形式でデータの標準化されたストリームを出力できる必要があります。これにより、出力テキストのストリームを解析する負担をかけずに簡単に構成できます。このドキュメントは、シェルの特定の実装、ユーティリティのセット、またはコマンド作成テクノロジーに依存しないように書かれています。ただし、付録J-Windows Powershellを使用してMicrosoft Command Line Standardを実装すると、Windows PowerShellを使用してこれらのガイドラインの多くを無料で実装する方法が示されます。

7
Jared Harley

例として、tarのような公式プロジェクトに従います。私の意見ではmsgを助けます。できるだけシンプルでわかりやすい説明にする必要があります。使用例も良いです。 「標準的なヘルプ」は本当に必要ありません。

0
rluks

はい、あなたは正しい軌道に乗っています。

はい、角括弧はオプションのアイテムの通常のインジケータです。

通常、スケッチしたように、上部にコマンドラインの概要があり、詳細が続きます。理想的には各オプションのサンプルがあります。 （あなたの例は各オプションの説明の間に行を示していますが、それは編集の問題であり、実際のプログラムは空白行なしでインデントされたオプションのリストを出力すると仮定します。

新しい傾向（これに対処するPOSIX仕様があるかもしれません）は、マニュアルのマニュアルページシステムを排除し、program --help出力の一部としてマンページに含まれるすべての情報を含めます。この追加情報には、詳細な説明、概念の説明、使用例、既知の制限とバグ、バグの報告方法、および関連コマンドの「関連項目」セクションが含まれます。

これがお役に立てば幸いです。

0
shellter