次のページ
前のページ
目次へ
まず、一つの例をあげて、その後、詳しく説明することにする。この文書の性
質から、いくつものフォント(ボールドとかイタリック)を表示することはで
きない。より詳しい説明は、「フォントに関する取り決め」を参照して欲しい。
以下が、架空のプログラム 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)
次のページ
前のページ
目次へ
|