マニュアルページに例がないのはなぜですか？

ほとんどのマニュアルページにいくつかの一般的な例が含まれていない理由はありますか？彼らは通常、すべての可能なオプションを説明しますが、それは初心者にとって「通常」使用される方法を理解することをさらに難しくします。

それはマニュアルページに依存します...伝統的に、彼らは例のセクションを含んでいます-しかし、何らかの理由で通常Linuxのマニュアルページから欠落しています（そして私は他のGNUコマンドを使用していると思います-これは最近のほとんどです）。一方、Solarisでは、ほとんどすべてのマニュアルページにサンプルセクションがあり、多くの場合、いくつかのサンプルが含まれています。

私が推測した場合、FSF / GNUは長い間、manページの使用を推奨しておらず、ユーザーはドキュメントの代わりに情報を使用することを好みます。infoページは、manページより包括的になる傾向があり、通常は行う例が挙げられます。 infoまた、ページはより「局所的」です。つまり、関連するコマンド（たとえば、ファイルを検索するためのコマンド）を一緒に見つけることができます。

別の理由としては、GNUとそのmanページが、互いに異なる多くの異なるオペレーティングシステムで使用されている可能性があります（異なるLinuxディストリビューションの間には多くの違いがあります）。パブリッシャーが特定のOS /ディストリビューションに関連する例を追加したことが意図された可能性があります-これは明らかにめったに行われません。

また、manページは「初心者を教える」ことを意図していないことも付け加えます。UNIXはコンピューターの専門家（旧称「ハッカー」）によって開発され、コンピューターの専門家が使用することを目的としています。したがって、マニュアルページは初心者に教えるためではなく、不明瞭なオプションや奇妙なファイル形式のリマインダーが必要なコンピューターの専門家を迅速に支援するために作成されました。

man-ページはこうして意図されています

• あなたの記憶をリフレッシュするためのクイックリファレンス。コマンドの呼び出し方法を示し、使用可能なオプションをリストします。
• コマンドのすべての側面についての詳細で、通常は非常に技術的な説明。仲間のコンピューターの専門家のために、コンピューターの専門家によって書かれています。
• コマンドが使用する環境変数とファイル（つまり、構成ファイル）のリスト。
• 他のドキュメント（例：本）、および他のmanページへの参照-例：構成ファイルと関連/類似のコマンドの形式について。

そうは言っmanても、manページ自体を歩くよりも使用法を説明できるので、ページに例が必要であることに非常に同意します。あまりにも悪い例は一般的にLinux manページでは利用できません...

Solarisのマニュアルページのサンプル部分のサンプル-zfs（1M）：

（...）
例
     例1 ZFSファイルシステム階層を作成する

     次のコマンドは、pool / homeという名前のファイルシステムを作成します
     また、pool / home / bobという名前のファイルシステム。マウントポイント
     / export / homeは親ファイルシステムに設定されており、
     子ファイルシステムによって自動的に継承されます。

       ＃zfs createプール/ホーム
       ＃zfs set mountpoint = / export / home pool / home
       ＃zfs create pool / home / bob

     例2 ZFSスナップショットを作成する

     次のコマンドは、昨日という名前のスナップショットを作成します。
     このスナップショットは、必要に応じて.zfs / snapshotにマウントされます
     pool / home / bobファイルシステムのルートにあるディレクトリ。

       ＃zfs snapshot pool / home / bob @ yesterday

     例3複数のスナップショットの作成と破棄

     次のコマンドは、昨日の名前のスナップショットを作成します
     プール/ホームおよびそのすべての子孫ファイルシステム。各
     スナップショットは、必要に応じて.zfs / snapshotディレクトリにマウントされます
     そのファイルシステムのルートで。2番目のコマンドは破棄します
     新しく作成されたスナップショット。

       ＃zfs snapshot -r pool / home @ yesterday
       ＃zfs destroy -r pool / home @ yesterday

SunOS 5.11最終変更日：2012年7月23日51

システム管理コマンドzfs（1M）

     例4ファイルシステムの圧縮の無効化と有効化

     次のコマンドは、次の圧縮プロパティを無効にします。
（...）

この特定のmanページには、16個の（！）そのような例が付属しています... Solarisへの称賛！
（そして、私はこのコマンドのマニュアルページ全体を読むのではなく、私自身がほとんどこれらの例に従っていることを認めます...）

これに対する良い答えはないと思います。それは文化的なことです。一部のマニュアルページには使用例があります。例man rsync。manページの作成者に書き込み、サンプルの使用法を追加するように依頼するか、（はるかに良い）サンプルの使用例を自分で提供することで、カルチャを変更しようとすることができます。フリーソフトウェアの作成者にパッチ、特にドキュメントパッチを提供すると、単純なリクエストよりも約1万倍の期待される結果が得られる可能性があります。

場合によります：

• おもしろいと思うプログラムのほとんどは、最初は問題を解決し、後で解決策を改善するために、一定期間にわたって開発されます。プログラムの開発者は、知っておくべき重要なことを説明します（そして、ドキュメントは彼らが解決していた問題ではありませんでした）。

• 一部のプログラムでは、開発者は特定のプログラム（またはライブラリ）の使用方法を示すサンプルプログラムまたはスクリプトを提供することを好みます。繰り返しますが、これは問題を解決するために行われます：プログラムをテストしやすくします。

  いくつかの例は、ユーザーからのバグレポートに基づいている場合があり、短い場合はマニュアルで場所を見つけます。長い例がマニュアルで提供されることはめったにありません。短い例には、些細で反復的な傾向があり、ユーザーにプログラムの動作に関する十分に整理された説明ほどの洞察を実際に提供しないという問題があります。

• 場合によっては、開発プロセスに関係のない他の人が提供するドキュメントがあります。つまり、開発者はドキュメントのレビューを除いて参加しませんでした。そのような努力は無視できます。

マニュアルページの代わりを探している場合は、常にbro pagesを試すことができます。これは、コマンドに対してさまざまな例を示しているだけで、コミュニティが提出した例のリストから投票できます。たとえば、コマンドbro tarは以下を提供します。