次のページ 前のページ 目次へ

3. フォーマットされた man page はどのようにあるべきか?

まず、一つの例をあげて、その後、詳しく説明することにする。この文書の性 質から、いくつものフォント(ボールドとかイタリック)を表示することはで きない。より詳しい説明は、「フォントに関する取り決め」を参照して欲しい。

以下が、架空のプログラム foo についての man page である。

FOO(1)                     User Manuals                    FOO(1)


名称
       foo - bar ライブラリを調整する。

形式
       foo [-bar] [-c config-file ] file ...

説明
       foo は、内部のシンボルテーブルをチューンアップして、bar 
       ライブラリを調整する。デフォルトでは、全ての baz セ
       グメントをパースして、xyzzy(1) リンカが検索できるように、
       時間の逆順に並び変える。symdef のエントリは、WBG 
       (Whiz-Bang-Gizmo:ヒューズドン法) のアルゴリズムを利用
       して圧縮される。全てのファイルは、与えられた順に処理される。

オプション
       -b     処理中に、標準出力に `busy' を出力しない。

       -c config-file
              指定されたファイル config-file をシステム全般に関
              わる設定ファイルとして、デフォルトの設定ファイル 
              /etc/foo.conf の代わりに使用する。環境変数 FOOCONF 
              に優先する。

       -a     baz セグメントに加えて、blurfl ヘッダもパースする。

       -r     再帰処理モード。大量の仮想メモリを使って超高速に
              処理を行なう。

ファイル
       /etc/foo.conf
              システム全般に関わる設定ファイル。詳細は、foo(5)を
              参照。 
       ~/.foorc
              ユーザー毎の設定ファイル。詳細は、foo(5)を参照。

環境変数
       FOOCONF
             システム全般に関わる別の設定ファイル foo.conf への
             パス名を設定。-c オプションが優先する。

診断メッセージ
      標準エラー出力に、以下の診断メッセージが表示される。

      悪いマジックナンバー      
              入力ファイルが、書庫ファイルではない。 
      baz セグメントのフォーマットが古い
              foo は新しいフォーマットの baz セグメントのみを
              処理できる。現在のバージョンでは、COBOL のオブ
              ジェクトライブラリを処理できない。 

バグ
       コマンド名は、ちゃんとコマンドの目的がわかるようなものに
       すべきである。

作者
       Jens Schweikhardt <jens@kssun3.rus.uni-stuttgart.de>

関連項目
       bar(1), foo(5), xyzzy(1)


Linux                       MARCH 1995                          1

さて、約束の説明をしよう。

名称セクション

名称のセクションは、必須のセクションである。名前のセクションがなければ Man page は、北極点での冷蔵庫なみの価値しかない。名前セクションは、カ ンマで区切られたプログラムや関数のリストとダッシュ(-) に続く説明(通常 は1行)、つまり、プログラムや関数、ファイルが果たす機能の短い説明が含 まれれた標準化された形式を持つ。makewhatis(8) は、名前セクションを利用 して whatis データベースファイルを作成する。makewhatis が利用するので、 名前セクションが必須であり、形式が標準化されているのである。groff のソー スでは、次のようにならないといけない。

     .SH 名称
     foo \-  bar ライブラリを調整する。
ここで、\- は重要である。バックスラッシュはダッシュをコマンド名や一行 説明にでてくるハイフォネーションのダッシュと区別するために必要である。

形式セクション

形式セクションは、指定できるオプションの簡単な説明が含まれる。関数の場 合、その関数を含むインクルードファイルとプロトタイプ宣言が記載され、プ ログラマは、引数の型や数、関数の返り値の型を知ることが出来る。

説明セクション

説明セクションでは、この0と1のデータの並びつまりプログラムに一体全体 どんな価値があるかについて、詳しい説明が記載される。あなたが書く場合、 あなたの持てる知識全部を書くようにする。いわば、名声の殿堂なのだ。他の プログラマやユーザの称賛を得るためには、詳しくて信頼のおける記載にしな ければならない。どの引数が何のためにあり、どのようなファイルフォーマッ トが用いられ、どのようなアルゴリズムが、プログラムの処理に用いられてい るかを説明しなければならない。

オプションセクション

オプションのセクションでは、オプションがプログラムの動作に与える影響に ついて説明される。自分のプログラムだから、オプションについてはよく知っ てるよね?

ファイルセクション

ファイルのセクションでは、プログラムまたは関数が使用するファイルを列挙 する。例えば、設定ファイル、初期ファイル、プログラムが直接操作するファ イルなどのこと。これらのファイルのフルパス名を記載し、ユーザの好みに合 わせてインストールするディレクトリを変更できるインストール処理を作るこ とはいい考えである。例えば、groff のマニュアルでは、デフォルトのプレフィ クスは /usr/local であり、通常、 /usr/local/lib/groff/* のファイルを参照する。しかし、'make prefix=/opt/gnu' と実行してインストールすると、man page での参照は、 /opt/gnu/lib/groff/* のファイルに対するように変更される。

環境変数セクション

環境変数のセクションでは、プログラムや関数に関する環境変数全てが列挙さ れ、もちろん、どう影響するかの説明がある。普通、環境変数により、パス名 やファイル名、デフォルトのオプションが指定される。

診断メッセージセクション

診断メッセージセクションには、プログラムからのよくあるエラーメッセージ の簡単な説明とエラーメッセージに基づきどうすべきかについて記載すべきだ。 プログラムを実行した時に表示されるかも知れない、システムエラーメッセー ジ(perror(3) からのもの)とか、致命的なシグナル(psignal(3) からのも の)については、説明する必要はない。

バグセクション

バグセクションは、理想を言えば、ないほうが良い。勇気があるなら、プログ ラムの制限とか、わかっているプログラムの不便なところ、他の人がおかしい とみなす機能について、書けば良い。勇気がなければ、"将来の予定" (TO DO) とでも名前を変えよう ;-)

著者のセクション

プログラムの動作とかドキュメントにエラーがいっぱいあって、バグレポート を送って欲しいのなら、著者のセクションを設けることは良い考えだが...

関連項目セクション

関連項目のセクションは、関連する man page のアルファベット順のリストで あり、慣習的に、最後におかれる。

上に説明したセクションに合わない内容については、別のセクションをつくり 出しても構わない。

では、正確には、どのようにして man page のソースを書けば良いの だろうか? そう来ると、思っていたよ、ルーク。ソースファイルは 次のようになる。

 .\" このソースファイルを次のように処理すること。
 .\" groff -man -Tascii foo.1
 .\"
 .TH FOO 1 "MARCH 1995" Linux "User Manuals"
 .SH 名称
 foo \-  bar ライブラリを調整する。
 .SH 形式
 .B foo [-bar] [-c
 .I config-file
 .B ]
 .I file
 .B ...
 .SH 説明
 .B foo 
 は、内部シンボルテーブルをチューンアップして、bar ライブラリを 
 調整する。デフォルトでは、全ての baz セグメントをパースして、
 .BR xyzzy (1)
 リンカが検索できるように、時間軸で逆順に並べ変える。
 symdef エントリは、WGB(Whiz-Bang-Gizmo:ヒューズドン法)のアルゴリズ
 ムを用いて圧縮される。全てのファイルは与えられた順に処理される。
 .SH オプション
 .IP -b
 処理中に、標準出力に `busy' を出力しない。
 .IP "-c config-file"
 指定されたファイル
 .I config-file
 をシステム全体に関連する設定ファイルとして、デフォルトの設定ファイル
 .IR /etc/foo.conf .
 の代わりに使用する。
 環境変数
 .B FOOCONF
 に優先する。
 .IP -a
 baz セグメントに加えて、blurfl ヘッダもパースする。
 .IP -r
 再帰処理モード。大量の仮想メモリを使って、超高速で処理を行なう。
 .SH ファイル
 .I /etc/foo.conf
 .RS
 システム全般に関わる設定ファイル。
 詳細は
 .BR foo (5)
 を参照。
 .RE
 .I ~/.foorc
 .RS
 ユーザー毎の設定ファイル。詳細は
 .BR foo (5)
 を参照。
 .SH 環境変数
 .IP FOOCONF
 システム全般に関わる設定ファイル
 .IR foo.conf
 へのフルパス名を設定。
 .B -c
 オプションが優先する。
 .SH 診断メッセージ
 標準エラー出力に、以下のエラーメッセージが表示される。
 悪いマジックナンバー
 .RS
 入力ファイルが、書庫ファイルではない。
 .RE
 baz セグメントのフォーマットが古い
 .RS
 .B foo
 は新しいフォーマットの baz セグメントのみを処理できる。現在のバージョ
 ンでは、COBOLのオブジェクトライブラリを、処理できない
 .SH バグ
 コマンド名は、ちゃんとコマンドの目的がわかるようなものにすべきである。
 .SH 著者
 Jens Schweikhardt <jens@kssun3.rus.uni-stuttgart.de>
 .SH "関連項目"
 .BR bar (1),
 .BR foo (5),
 .BR xyzzy (1)


次のページ 前のページ 目次へ