UNIXのCLI用のツールを作成する場合、プログラムにヘルプや使用法を出力するにはどうすればよいですか？

私は通常を使用しますがfprintf(stderr, "help text here");、それにはいくつかの問題があります。

• まず、を使用すべきかどうかはわかりませんstderr。大丈夫ですか、それとも使用すべきstdoutですか？
• ご想像のとおり、ヘルプテキストは非常に長く、ツールのオプションの数によって異なります。今、私は通常、"strings like that\n"2番目のパラメータにいくつかを入れます。ただし、これにより、ソースコードが50行以上のヘルプテキストで埋められます。簡単に管理できるものではありません。代わりに何をすべきですか？
• ツールがCまたはCに似た言語で記述されていない場合、可能であればhere-docsを使用する傾向があります（最も顕著なのはPerlです）。私はCでそれを使用できませんが、私が使用できるようなものがありますか？
• 私はそれを入れて検討していたheaderfile.hの内側には#define HELP "help text here"、私は野生の中でそれを見たことがない、私は実際にそれを使用する必要があるかどうかわかりません。

理想的には、テキストを外部ファイルに入れて含めることができます。#includeただし、そのために使用するのは間違っているようです。どうすればいいですか？

アイデアは、ヘルプテキストを用意して、簡単に管理できるようにすることです。ソースコード内に配置することは、あまり便利ではありません。

ターゲットプラットフォームの内部から自分を刺激する

BSDのソースコードをご覧ください。たとえば、次のとおりです。

• usage(void)NetBSDの/usr/bin/unameツール[ ソース ]：

  usage(void)
  {
      fprintf(stderr, "usage: uname [-amnprsv]\n");
      exit(EXIT_FAILURE);
  }
  

• usage(void)NetBSDの/usr/bin/telnet[ ソース ]

• usage(void)OpenBSDの/bin/ls[ ソース ]

代替案をご覧ください

そして、それらが良いか悪いかを自分で決めてください。Google CodeSearchを使用して、次のような他の人を見つけることができます。

• SkyLoadの使用法[ ソース ]

ご覧のとおり、これらと上記のBSDシステム統合ツールとは異なるスタイルです。どちらか一方に従う必要があるという意味ではありません。しかし、通常は周りを見回して、一貫したソリューションに落ち着くのが良いでしょう。

50行のヘルプに対する非標準ソリューション...

50行のテキストを避けたくない場合は、テキストファイルからヘルプを読むことができます（プレーンテキスト、またはman作成した場合はソースを直接解析することもできます）。私はそれをかなりエレガントな方法で見つけます（テキストドキュメントを調べることもできます）が、コアシステムプログラムでは本質的に安全ではなく、障害点が発生します。他の人は、usageor helpメッセージに対しては重いと主張しますが、これらが高速のタイトループで呼び出されるというわけではありません...

疑わしい場合は、巨人に従ってください。

stdoutヘルプはエラーではないため、私はを使用します。

これがCでの長い助けであれば、私はhere-docsを模倣しようとします：

printf("This is the help for MyWonderfulApp\n"
       "Options are:\n"
       "    --help: display what you are reading now\n"
       "    --quiet: output nothing\n");

しかし、ほとんどの場合、専用タグmanを使用してページを作成しますnroff -man。アプリ内ヘルプは、単にそのmanページを参照するだけで構成されています。

私はあなたのだろうならば、私はただのソースを開いたのだgrep、tail、cat、your_other_favorite_unix_shell_commandそれはそこに行うのかを確認します。私は彼らのやり方がかなりよく考えられていて、多くの人々が維持できると確信しています。

stderrかstdout。エラーがある場合は本当に簡単です- stderr情報だけの場合はに書き込みます- stdout。たとえば、間違ったオプションでツールを実行した場合、エラーが表示される可能性があります。たとえばUse --help for usage、これはに属しstderrます。有効なオプション--helpを使用してツールを実行する場合は、を使用してくださいstdout。

コードの近くに長いヘルプ文字列を持たないことが望ましい場合は、しないでください。ヘッダーファイルでの#defineはまったく問題ありませんが、実際には個人的な好みです。コマンドラインツールのコードを読む必要がある場合、ユーザーが提供するオプションを処理するファイル内にヘルプ文字列を含めることをお勧めします。

私はgnu getoptsライブラリーを使用します。ヘルプ付きの例については、このサンプルプロジェクト、特にparser.yの下部にあるメインメソッドを参照してください。

中括弧で囲まれているため、使用しているvimエディターは行をまとめて折りたたむことができ、必要のないときには気づきさえしません。

Cを使用している場合、またはBoostライブラリに依存しない場合は、GNUを使用しますgetopt。それ以外の場合は、ヘルプを自動的に印刷するBoost Program Optionsを使用します。

また、オプションの処理に関しては、適切なオプションを推測することもベストプラクティスの1つです。私はGitからそれを学び、今では私のプロジェクトで同じものを使用しています。基本的に、ユーザーが未知のコマンドラインオプションを入力した場合、Damerau–Levenshtein距離を使用して最適な一致を印刷します。

例として使用できる、これに関する小さな記事を書きました。

それが役に立てば幸い ：）

明らかに、cout <<またはprintf（）コードでホールページを作成するのは面倒です。特に段落を変更して再入力する必要がある場合はなおさらです。したがって、たとえばテキストをより簡単にフォーマットできるemacsなどを使用して、別のファイルでそのテキストを編集することは明らかに良い考えです。

次に、次のsedスクリプトを使用して、そのテキストファイルを有効なCヘッダーファイルに変換できます。

s/\"/\\\"/g
s/$/\\n"/
s/^/"/
1i\
const char *helpStr = 
$a\
;

次に、ヘッダーファイルをソースコードに#include -ing すると、次のようにテキストを書き出すことができます。

cout << helpStr;