まず、一つの例をあげて、その後、詳しく説明することにする。この文書の性 質から、いくつものフォント（ボールドとかイタリック）を表示することはで きない。より詳しい説明は、「フォントに関する取り決め」を参照して欲しい。
以下が、架空のプログラム 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 は、北極点での冷蔵庫なみの価値しかない。名前セクションは、カ ンマで区切られたプログラムや関数のリストとダッシュ(-) に続く説明（通常 は１行）、つまり、プログラムや関数、ファイルが果たす機能の短い説明が含 まれれた標準化された形式を持つ。makewhatis(8) は、名前セクションを利用 して whatis データベースファイルを作成する。makewhatis が利用するので、 名前セクションが必須であり、形式が標準化されているのである。groff のソー スでは、次のようにならないといけない。
.SH 名称
foo \- bar ライブラリを調整する。
ここで、\- は重要である。バックスラッシュはダッシュをコマンド名や一行
説明にでてくるハイフォネーションのダッシュと区別するために必要である。
形式セクションは、指定できるオプションの簡単な説明が含まれる。関数の場 合、その関数を含むインクルードファイルとプロトタイプ宣言が記載され、プ ログラマは、引数の型や数、関数の返り値の型を知ることが出来る。
説明セクションでは、この０と１のデータの並びつまりプログラムに一体全体 どんな価値があるかについて、詳しい説明が記載される。あなたが書く場合、 あなたの持てる知識全部を書くようにする。いわば、名声の殿堂なのだ。他の プログラマやユーザの称賛を得るためには、詳しくて信頼のおける記載にしな ければならない。どの引数が何のためにあり、どのようなファイルフォーマッ トが用いられ、どのようなアルゴリズムが、プログラムの処理に用いられてい るかを説明しなければならない。
オプションのセクションでは、オプションがプログラムの動作に与える影響に ついて説明される。自分のプログラムだから、オプションについてはよく知っ てるよね？
ファイルのセクションでは、プログラムまたは関数が使用するファイルを列挙
する。例えば、設定ファイル、初期ファイル、プログラムが直接操作するファ
イルなどのこと。これらのファイルのフルパス名を記載し、ユーザの好みに合
わせてインストールするディレクトリを変更できるインストール処理を作るこ
とはいい考えである。例えば、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)