man - 約束事その他の説明 - Linux コマンド集 一覧表

man - man ページを整形するマクロ

groff -Tascii -man file ...

groff -Tps -man file ...

man [ section ] title

このマニュアルページでは、 "groff tmac.an" のマクロパッケージ (しばしば man マクロパッケージとも呼ばれることも多い) とマニュアルページ (man page) を 作成する際の決まり事について説明する。このマクロパッケージは、 Linux の man ページを書いたり移植したりするときに、 開発者が用いるものである。 このマクロパッケージはバージョン間での互換性が高く、 man page の移植にあたっては大きな問題はないだろう (但し、NET-2 BSD release は例外である。 こちらでは mdoc と呼ばれる全く異なるマクロパッケージが使用されている。 mdoc (7)を参照)。

NET-2 BSD の man ページも、 groff のオプションとして -man の代わりに -mdoc を指定するだけで、利用することができる。 -mandoc オプションを使えばどのマクロパッケージが用いられているか 自動的に検出できるので、このオプションを使うのがお薦めである。

man ページの (コメント行を除く) はじめのコマンドは、 以下のようにする必要がある。

.TH title section date source manual ,

それぞれ:

title

man ページのタイトル (例: MAN ).

section

man ページが属するセクション番号 (例: 7 ).

date

最新のリビジョンの日付 \(em man ページに変更を加えたときには 必ずこれを変更すること。 これが最も一般的なバージョン管理方法である。

source

コマンドの出自。
バイナリには次のようなものを用いる: GNU , NET-2 , SLS Distribution , MCC Distribution .
システムコールには、対象としている現在のカーネルバージョンを用いる: "Linux 0.99.11"
ライブラリコールには関数の出自を用いる: GNU , 4.3BSD , Linux DLL 4.4.1 .

manual

マニュアルのタイトル (例: Linux Programmer's Manual ).

なお BSD の mdoc フォーマットのページは TH コマンドではなく Dd コマンドから始まる。

マニュアルのセクションは、習慣的に以下のような定義が用いられている:

1 コマンド

シェルの中からユーザが実行できるコマンド。

2 システムコール

カーネルが処理しなければならない関数。

3 ライブラリコール

libc の関数の大部分。例えば   qsort (3) など。

4 スペシャルファイル

/dev 以下にあるファイル。

5 ファイルのフォーマットと規約

/etc/passwd などの人間に可読であるファイルのフォーマット。

6 ゲーム

7 約束事その他

標準的なファイルシステム配置、ネットワークプロトコル、 ASCII などの文字コード、などなどに関する説明 (この man ページもここに入る)。

8 システム管理コマンド

  mount (8) のような root のみが実行可能なコマンド。

9 カーネルルーチン

このマニュアルセクションは廃止された。 かつてはここに Linux カーネルのドキュメントを置くのが良いことだと 考えられていた。しかし、文書化されたものは非常に少なく、 またそれらもすでに古いものとなってしまった。 カーネル開発者にとって、もっとよい情報源が他にあるだろう。

セクションは .SH ではじまり、見出し名がそれに続く。 スペースが含まれている名前を .SH と同じ行に置く場合は、見出し名はダブルクォートで囲む。 昔から使われてきた見出し名には以下のようなものがある。 これらを使うと良いだろう: 名前 (NAME), 書式 (SYNOPSIS), 説明 (DESCRIPTION), 返り値 (RETURN VALUE), 終了ステータス (EXIT STATUS), エラー処理 (ERROR HANDLING), エラー (ERRORS), オプション (OPTIONS), 利用法 (USAGE), 例 (EXAMPLES), ファイル (FILES), 環境変数 (ENVIRONMENT), 診断メッセージ (DIAGNOSTICS), セキュリティ (SECURITY), 準拠 (CONFORMING TO), 注意/備考 (NOTES), バグ (BUGS), 著者 (AUTHOR), 関連項目 (SEE ALSO)。 これらの見出し名のどれかが適用できる場合は、それを使ってほしい。 この種の一貫性を保つことで、情報を理解しやすくなるからである。 ただし、もっと理解しやすくなるような場合には、 どんどん新しい見出し名を作ってほしい。 NAME (名前) という見出しだけは必ず置かないといけない。 この見出しは一番最初のセクションにすべきで、見出しの 次の行にはプログラムの説明を一行で書く。

.SH NAME
chess \- the game of chess

このフォーマットに従い、コマンド名に続くシングルダッシュ (-) の前には必ずバックスラッシュを置くこと。 この文法は、   makewhatis (8) プログラムが   whatis (1) や   apropos (1) コマンド用の (コマンドの短い説明の) データベースを生成する際に利用される。

良く用いられる他のセクションと、そこに書く内容とをいくつか示す:

書式 (SYNOPSIS)

コマンドや関数のインターフェースを簡潔に記述する。 コマンドに対しては、コマンドや引き数 (オプション) の文法を書く。 そのまま書くテキストにはボールド体を用い、置き換える引き数には イタリックを用いる。省略可能なオプションはブラケット ([]) で囲い、 選択肢は縦棒 (|) で区切り、繰り返しには省略符号 (...) を書く。 関数に対しては、必要なデータ宣言や #include 指定を書き、関数宣言を続ける。

説明 (DESCRIPTION)

コマンド・関数・フォーマットの動作・目的を説明する。 ファイルや標準入力をどのように処理し、標準出力や標準エラー出力を どのように生成するかといったことについて述べる。 内部動作や実装の詳細については省略する (ただしそれが動作の理解にどうしても必要なら別)。 通常の場合について記述する。オプションの情報には オプション のセクションを用いる。 入力にある種の文法があったり、複雑なサブコマンドがある場合は、 それらは 利用法 のセクションに分離することを考えるとよい ( 説明 のセクションには概要だけを置くようにする)。

返り値 (RETURN VALUE)

ライブラリルーチンが呼び出し元に返す値のリストを与える。 それらの値が返された場合の状態に対する説明も書く。

終了ステータス (EXIT STATUS)

プログラムの終了ステータスの値と、それらの値に対応する状況をリストする

オプション (OPTIONS)

プログラムが受け付けるオプションと、 その場合プログラムの振舞いがどう変わるかを記述する。

利用法 (USAGE)

コマンドなどが実装している副言語 (sublanguage) の文法を記述する。

例 (EXAMPLES)

この関数・ファイル・コマンドをどのように使うかを示した ひとつまたは複数の例を記述する。

ファイル (FILES)

プログラムや関数が用いるファイルを列記する。 例えば、設定ファイル、起動ファイル、プログラムが直接操作するファイルなどである。 これらのファイルのファイル名はフルパスで記載し、 ディレクトリの部分はユーザーの好みに合わせて インストール処理で変更できるようにする。 多くのプログラムではデフォルトのインストール先は /usr/local である。したがってベースとなるマニュアルページでも /usr/local が使われていることが多いだろう。

環境変数 (ENVIRONMENT)

プログラムや関数に影響する環境変数をリストし、それらの効果を書く。

診断メッセージ (DIAGNOSTICS)

ごく一般的なエラーメッセージの概要と、 それらをどう扱うかについて述べる。プログラムの実行時に現れる システムエラーメッセージや致命的シグナルを全部説明する必要はない。 ただしそれらがプログラムに対して 何らかの特殊な意味を持っている場合は別である。

セキュリティ (SECURITY)

セキュリティ関連の話題・問題について述べる。 避けるべき設定や環境・セキュリティ上の問題を引き起こすコマンド などについて警告する。それらが明らかでない場合には、これは特に重要である。 セキュリティに関する話題は、必ずしも独立したセクションにする必要はない。 もし理解しやすければ、セキュリティの情報は他のセクション (例えば 説明 や 利用法 など) に書いてもよい。 しかし、セキュリティの情報はどこかには書いておいてほしい!

準拠 (CONFORMING TO)

説明対象が実装している標準や規格を書く。

注意 (NOTES)

その他の注意点を書く。

バグ (BUGS)

制限・知られている欠陥や不便な点、その他不思議な動作などを書く。

著者 (AUTHOR)

文書またはプログラムの著者を列記し、 バグレポートをメールで送ることができるようにする。

関連項目 (SEE ALSO)

関連する man ページをアルファベット順にリストする。 可能なら関連する他の文書も書く。 慣習では、このセクションは最後に置く。

UNIXの世界では man ページについて勝手な慣習がたくさんあるが、 数百ある Linux 特有の man ページでは、以下のような標準が用いられている:
関数に対しては、引き数には常にイタリックを用いる。 「たとえ書式 (SYNOPSIS) セクションであっても、このルールに従う」 関数の他の部分はボールドを指定する:
int myfunction(int argc , char ** argv );

ファイル名は常にイタリックにする (例: /usr/include/stdio.h ),ただし書式 (SYNOPSIS) セクションは例外で、 インクルードファイルはボールドにする (例: #include <stdio.h> )。通常、大文字で表現する特殊マクロはボールドで表す (e.g., MAXINT ).
エラーコードのリストを列挙する時には、コードはボールドで表す (このリストには通常 .TP マクロを用いる).
他の man ページへの参照 (もしくは現在の man ページの別のセクションへの参照) はボールドにする。 マニュアルセクションの番号を与える場合には、数字はローマンフォント (通常のフォント) とし、スペースは取り除く (例: man (7))。

タイプフェイスを選択するコマンドは以下のように指定する:

.B

ボールド。

.BI

ボールドとイタリックとを交互に (特に関数指定に便利)。

.BR

ボールドとローマンとを交互に (特に他のマニュアルページを参照するときに便利)。

.I

イタリック。

.IB

イタリックとボールドとを交互に。

.IR

イタリックとローマンとを交互に。

.RB

ローマンとボールドとを交互に。

.RI

ローマンとイタリックとを交互に。

.SB

スモールとボールドを交互に。

.SM

スモール (頭字語などに用いる)

慣例としては、各コマンドは 6 つまでの引き数を持つ事が可能だが、 GNU の実装では制限はないようだ (しかし移植性を保持するためには 引き数は 6 までに限っておくのが良いだろう)。 引き数はスペースで区切られる。 スペースを含んだ引き数を与えるには、ダブルクォートで囲えばよい。 すべての引き数はスペースを取り除いて並べられるので、 .BR コマンドを使えば、単語はボールドで、句読点をローマンで表すことができる。 引き数が全く与えられなければ、 そのコマンドは次の行のテキストに適用される。

以下に、他のマクロや定義済みの文字列を示す。 特に記述がない限り、マクロを使うと改行が行われる (テキストの現在の行を終了する)。 多くのマクロは 「優先インデント (prevailing indent)」を設定したり、使用する。 優先インデントの値は、どのマクロからもパラメータ i によって指定できる (以下に示す)。 マクロでは i を省略することもでき、その場合は現在の優先インデントの値が用いられる。 これにより結果として、インデントされた段落が連続している場合、 インデントの値を再指定しなくてもインデント量を同じにすることができる。 通常の (インデントされていない) 段落が登場すると、 優先インデントの値はデフォルトの値 (0.5 インチ) にリセットされる。 デフォルトでは、与えたインデントの値は ens 単位である。 インデントの単位には ens や ems を用いるとよい。これらの単位は フォントサイズが変更されると自動的に調整されるからである。 他の重要なマクロ定義は以下の通り:

通常の段落

相対マージンインデント

段落をインデントするマクロ

ハイパーテキストリンク用のマクロ

その他のマクロ

定義済みの文字列

技術的には man は troff のマクロパッケージだが、実際には多数の別のツールが man ページのファイルを処理しており、それらは troff の全ての機能を 実装していないこともある。したがって、他のツールでも正しく処理できるように、 troff のあまり一般的でない機能は、可能ならば用いないのが望ましい。 様々な troff プリプロセッサ も用いないほうが良いだろう (やむを得ない場合は   tbl (1) は用いても良い。しかし 2 列の表なら、代わりに IP や TP コマンドを用いてみよう)。 計算機能も用いない方が良いだろう。他のツールのほとんどはこれらを処理できない。 他のフォーマットに変換が容易な、単純なコマンドを使うようにしよう。 以下の troff コマンドは、使っても問題ないと考えてよいだろう (多くの場合、変換コマンドによって無視されるかもしれないが)。 \" , . , ad , bp , br , ce , de , ds , el , ie , if , fi , ft , hy , ig , in , na , ne , nf , nh , ps , so , sp , ti , tr

troff のエスケープシーケンスの多くも利用できる (これらのエスケープシーケンスは \ で始まる)。 バックスラッシュ文字を通常のテキストとして使いたい場合は \e とする。 利用できる他のシーケンスには以下のようなものがある (x や xx は任意の文字, N は任意の数字): \' , \` , \- , \. , \" , \% , \*x , \*(xx , \(xx , \$N , \nx , \n(xx , \fx , \f(xx .グラフィックの描画にはエスケープシーケンスは用いないほうが良い。

bp (改頁) にはオプションパラメータを用いないこと。 sp (垂直スペース) には正の値のみを用いること。 man や mdoc マクロパッケージにあるマクロと、 名前が同じで機能の異なるマクロを定義 ( de )しないこと。そのような再定義は無視される可能性が高い。 正方向へのインデント ( in )には、負のインデントを対応させること (このマクロの代わりに RS と RE マクロを使った方がよいのだが)。 条件テスト ( if , ie )は状態として 't' または 'n' だけを持つようにすること。 変換 ( tr )には無視できるものだけを使うこと。 フォントの変更 ( ft と \f エスケープシーケンス) には 1, 2, 3, 4, R, I, B, P, CW のみを用いること (ft コマンドの場合はパラメータを指定しなくてもよい)。

この制限を越えて機能を用いる場合は、いくつかのツールを使って、 その結果を注意してチェックすること。追加した機能が安全だと 確信したら、この文書の管理者にその安全なコマンドまたはシーケンスを 教えてほしい。リストに追加する。

テキストにはぜひとも完全な URL (または URI) を書くようにすること。   man2html (1) のようなツールは、これらを自動的にハイパーテキストリンクに変換する。 新たに取り入れられた URL マクロを関連情報へのリンクに用いても良い。 URL を書く場合は、 例えば <http://www.kernelnotes.org> のように完全な形式で書き、 ツールによる URL 自動検知ができるようにすること。

これらのファイルを処理するツールは、ファイルをオープンして 最初の空白以外の文字を調べる。行の先頭にピリオド (.) またはシングルクォート (') があると、これは troff ベースの ファイル (man や mdoc) であるとみなす。左角括弧 (<) は SGML/XML ベースのファイル (HTML や Docbook) であるとみなす。 それ以外は単純な ASCII テキスト ("catman" の結果など) とみなす。

多くの man ページは、最初の行が '\" とスペースで始まっており、 そこにはそのページが処理されるべきプリプロセスを表す文字が書いてある。 troff 以外の変換プログラムへの移植性のため、   tbl (1) や、 Linux が自動的に検知できるもの以外は使わないようにすることを勧める。 しかし、この情報を記述して、書いたページが他の (より低機能な) システムでも 扱えるようにしたい場合もあるかも知れない。 以下にこれらの文字によって起動されるプリプロセッサの定義を示す:

e

eqn(1)

g

grap(1)

p

pic(1)

r

refer(1)

t

tbl(1)

v

vgrind(1)

/usr/share/groff/ [*/] tmac/tmac.an
/usr/man/whatis

mdoc や DocBook に比べると、 マクロの多くは書式 (フォントタイプやスペーシングなど) に関するものであり、 意味上のもの (このテキストは他のページへの参照である、など) ではない (HTML ですら意味的なマーキングに思える)。 このため、 man フォーマットを他のメディアへ変換したり、 フォーマットを他のメディアで有効なものにしたり、 相互参照を自動的に挿入したりすることが困難になっている。 上に挙げたような安全なサブセットを守れば、 将来別のリファレンスページフォーマットへ変換する作業が簡単になるだろう。

Sun のマクロである TX は定義されていない。

James Clark (jjc@jclark.com) がマクロパッケージの実装を書いた。
Rickard E. Faith (faith@cs.unc.edu) がこのマニュアルページの最初の版を書いた。
Jens Schweikhardt (schweikh@noc.fdn.de) は Linux Man-Page Mini-HOWTO を書いた (本マニュアルページもこの文書の影響を受けている)。 David A. Wheeler (dwheeler@ida.org) はこのマニュアルページを大きく変更し、 セクションやマクロに関する細かな情報を追加するなどを行った。

  apropos (1),   groff (1),   man (1),   man2html (1),  mdoc (7),  mdoc.samples (7),   groff_man (7),  groff_www (7),  whatis (1)