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

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

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

答え1

マニュアルページによって異なります。伝統的に持つ例を含むセクションが含まれています。ただし、何らかの理由でLinuxのマニュアルページにはそのセクションがないことがよくあります。 (他のコマンドは現在ほとんどのGNUコマンドを使用していると仮定しています。)一方、たとえばSolarisでは、ほとんどすべてのマニュアルページに「例」セクションが含まれており、多くの例が含まれています。

推測すると、FSF / GNUは長い間manページの使用を抑制し、ユーザーが情報を文書として使用することを好みました。infoページはマニュアルページよりも包括的な傾向があり、一般的にする例を含めてください。 infoページはさらに「トピック」です。つまり、関連するコマンド(ファイルの検索に使用されるコマンドなど)を一緒に見つけることができることがよくあります。

もう1つの理由は、GNUとそのページが異なるさまざまなオペレーティングシステムで使用されるためですman(最終的にLinuxディストリビューションには多くの違いがあります)。出版社の意図は、おそらく特定のオペレーティングシステム/ディストリビューションに関連する例を追加することでしたが、これはほとんど行われていないようです。

manまた、このページは「初心者を教える」ことが決してないことを付け加えたいと思います。 UNIXは、コンピュータの専門家(以前の用語「ハッカー」)がコンピュータの専門家が使用できるように開発されました。したがって、マニュアルページは初心者を教えるためではなく、あいまいなオプションや奇妙なファイル形式を思い出させる必要があるコンピュータの専門家にすばやく助けるためのものです。これは、マニュアルページを分割する方法に反映されます。

man-ページは、次のように意図されます。

  • 記憶を更新するためのクイックリファレンスは、コマンドの呼び出し方法を示し、利用可能なオプションをリストします。
  • 深く徹底した(しばしば非常に技術的)説明みんなコマンドのすべての側面。コンピュータの専門家が他のコンピュータの専門家のために書いた。
  • コマンドで使用される環境変数とファイル(構成ファイルなど)のリスト。
  • 他の文書(本など)や他のmanページへの参照 - 例:構成ファイルと関連/類似コマンドの形式。

つまり、manマニュアルページ自体を調べるよりも使い方をよく説明するため、ページに例があるはずだということには全く同意します。残念ながら、man一般的にLinuxページには例はありません...

Solaris のマニュアルページの例セクションの例 - zfs(1M):

(...)
はい
     例1 ZFSファイルシステム階層の作成

     次のコマンドは pool/home というファイルシステムを生成します。
     そしてpool / home / bobというファイルシステムがあります。マウントポイント
     /export/home は親ファイルシステムに設定されます。
     サブファイルシステムから自動的に継承されます。

       # zfs はプール/ホームを作成します。
       # zfs set mountpoint=/export/home プール/ホーム
       # zfs は /home/bob プールを生成します。

     例2 ZFSスナップショットの作成

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

       #zfsスナッププール/home/bob@yesterday

     例3複数のスナップショットの作成と削除

     次のコマンドは、昨日と呼ばれるスナップショットを作成します。
     pool / homeとすべてのサブファイルシステム。各
     スナップショットは、要求に応じて.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 ファイルシステム圧縮の無効化と有効化

     次のコマンドは圧縮属性を無効にします。
(...)

この特定のマニュアルページには、これらの例の16(!)が含まれています... Solarisに賛辞を送ります!
(私はこのコマンドの完全なマニュアルページを読むのではなく、この例に直接従ったことを認めています...)

答え2

私はこの質問に対する良い答えがないと思います。これは文化的な問題です。一部のマニュアルページには使用例があります。たとえばman rsync。マニュアルページの作成者に手紙を書いて、いくつかの例の使用法を追加するように依頼するか(より良い場合)、自分で提供して文化を変えようとすることができます。フリーソフトウェアの作成者にパッチ、特にドキュメントパッチを提供する場合、希望する結果を得る可能性は単純な要求より約10,000倍高くなります。

答え3

時によって異なります:

  • 興味のあるほとんどのプログラムは、最初は問題を解決し、後で解決策を改善するために一定期間にわたって開発されました。プログラム開発者は、知っておくべき重要であると考えられるものを説明します。文書解決すべき問題ではありません。)

  • 一部のプログラムでは、開発者は提供例を好む。プログラムまたはスクリプト与えられたプログラム(またはライブラリ)を使用する方法を示します。繰り返しますが、これは問題を解決するために行われます。つまり、プログラムをより簡単にテストできるようにすることです。

    一部の例は、ユーザーのバグレポートに基づいている場合があります。短いマニュアルで場所を探します。長い例はマニュアルではほとんど提供されておらず、短い例の問題はマイナーで反復的な傾向があり、実際にプログラムがどのように機能するかについて十分に構成された説明ほどユーザーに多くの洞察を提供しないことです。

  • 場合によっては、他の人が提供した文書を見つけることができます。いいえ開発プロセスに参加してください。つまり、開発者は文書を確認する以外には関与しません。この努力はわずかです。

答え4

マニュアルページの代替案を探している場合は、いつでもお試しください。ブラザーズページ、これは単にコマンドのさまざまな例を表示し、コミュニティから送信された例のリストから投票できます。たとえば、このコマンドはbro tar以下を提供します。ここに画像の説明を入力してください。

関連情報