web-dev-qa-db-ja.com

manページに例がないのはなぜですか?

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

54
Deepak Joy

それはマニュアルページに依存します...伝統的に、それらはhaveに例のセクションを含めました-しかし、何らかの理由で通常Linuxのマニュアルページにはありません(そして私は他のGNUコマンド-最近のほとんどです。)一方、Solarisでは、ほとんどすべてのmanページに「例」セクションがあり、いくつかの例があります。

私が推測したとしたら、FSF/GNUは長い間、manページの使用を思いとどまらせており、代わりにドキュメントの情報を使用することをユーザーに好んでいます。 infoページは、manページよりも包括的である傾向があり、通常doには例が含まれます。 infoページもより「トピック的」です。つまり、関連するコマンド(ファイルを検索するためのコマンドなど)が一緒に見つかることがよくあります。

もう1つの理由は、GNU=とそのmanページが、互いに異なる可能性のある多くの異なるオペレーティングシステムで使用されていることです(結局のところ、異なるLinuxディストリビューション間には多くの違いがあります) )意図は、発行者が特定のOS /ディストリビューションに関連する例を追加したことである可能性があります-これは明らかにほとんど行われません。

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

したがって、man- pagesは、

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

とは言っても、manページには使用例を説明する必要があると私は強く同意します。 Linuxのmanページでは、あまりにも悪い例は一般に利用できません...

Solarisのマニュアルページのサンプル部分のサンプル-zfs(1M):

(...)
 EXAMPLES 
例1 ZFSファイルシステム階層の作成
 
次のコマンドは、pool/home [という名前のファイルシステムを作成します.____。]およびpool/home/bobという名前のファイルシステム。マウントポイント
/export/homeは親ファイルシステムに設定され、
は子ファイルシステムに自動的に継承されます。
 
#zfs create pool/home 
#zfs set mountpoint =/export/home pool/home 
#zfs create pool/home/bob 
 
例2 ZFSスナップショットの作成
 
次のコマンドは、昨日という名前のスナップショットを作成します。
このスナップショットは、pool/home/bobファイルシステムのルートにある.zfs/snapshot 
ディレクトリのオンデマンドでマウントされます。 
 
#zfs snapshot pool/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無効化と有効化ファイルシステムの圧縮
 
次のコマンドは、
(...)
の圧縮プロパティを無効にします。

この特定のmanページには、16(!)の例が付属しています... Solarisへの称賛!
(そして、私自身は、このコマンドのmanページ全体を読むのではなく、これらの例にほとんど従ったことを認めます...)

49
Baard Kopperud

これには良い答えはないと思います。それは文化的なものです。いくつかのマニュアルページには使用例があります。例えば。 man rsync。マニュアルページの作成者に書いて、サンプルの使用法を追加するよう依頼するか、(はるかに良い)サンプルの使用法の例を自分で提供することによって、文化を変更しようとすることができます。フリーソフトウェアの作者にパッチ、特にドキュメンテーションパッチを提供すると、単純な要求よりも約1万倍高い確率で目的の結果が得られます。

26
Faheem Mitha

場合によります:

  • 興味深いプログラムのほとんどは、最初は問題を解決し、後で解決策を改善するために、一定期間にわたって開発されます。プログラムの開発者は、知っておくべき重要なことを説明します(そしてdocumentationは、彼らが解決していた問題ではありませんでした)。
  • 一部のプログラムでは、開発者はサンプルprogramsまたはscriptsを提供して、特定のプログラム(またはライブラリ)の使用方法を示します。繰り返しますが、これは問題を解決するために行われます。プログラムをテストしやすくするためです。

    一部の例は、ユーザーからのバグレポートに基づいている場合があります。また、マニュアルでshortが見つかった場合。長い例がマニュアルで提供されることはめったになく、短い例はそれらが取るに足りない、反復的である傾向があり、プログラムがどのように機能するかの十分に組織化された説明ほどユーザーに洞察を提供しないという問題があります。

  • 場合によっては、開発プロセスに関与する他の人が提供するドキュメントを見つけることができますnot。つまり、開発者はドキュメントの確認以外は参加しませんでした。そのような努力は無視できます。
7
Thomas Dickey

Manページに代わるものを探している場合、いつでも bro pages を試すことができます。これは、コマンドにさまざまな例を示すだけであり、コミュニティが送信した例のリストから投票できます。たとえば、コマンドbro tarはあなたに与えます: enter image description here

6
BandW2011