Provided by: manpages-ja_0.5.0.0.20131015+dfsg-2_all 
名前
man-pages - Linux の man ページを書く際の決まり事
書式
man [section] title
説明
このページでは、 Linux man-pages プロジェクトのマニュアルページを書く際に 従うべき決まり事
について説明する。 Linux man-pages プロジェクトは Linux カーネルおよび GNU C ライブラリが
提供するユーザ空間 API のドキュメント作成を行っている。Linux システムのマニュアルページの
セクション 2 のページのほとんどと、セクション 3, 4, 5, 7 の多くのページが、このプロジェク
トにより提供されている。このページで説明されている決まり事は、他のプロジェクトの マニュア
ルページを書く作者にも役立つことだろう。
マニュアルページのセクション
マニュアルのセクションは、習慣的に以下のような定義が用いられている:
1 コマンド (プログラム)
シェルの中からユーザが実行できるコマンド。
2 システムコール
カーネルが処理しなければならない関数。
3 ライブラリコール
libc の関数の大部分。
4 スペシャルファイル (デバイス)
/dev 以下にあるファイル。
5 ファイルのフォーマットと規約
/etc/passwd などの人が読めるファイルのフォーマット。
6 ゲーム
7 概要、約束事、その他
様々な事柄の概要、慣習、プロトコル、文字集合の規格、その他雑多なこと。
8 システム管理コマンド
mount(8) のような root のみが実行可能なコマンド。
マクロパッケージ
新しいマニュアルページは man(7) で説明されている groff an.tmac パッケージを使って記述すべ
きである。 この方針は一貫性の確保が主な理由である。既存の Linux のマニュアルページ の圧倒
的多数がこれらのマクロを使って記述されている。
ソースファイルの配置に関する決まり事
マニュアルページのソースコードの 1行の長さは 可能な限り 75文字を越えないようにしてほしい。
こうすることで、パッチをメール本文に載せて送る場合に、 メールクライアントによる行折り返し
を回避することができる。
新しい文は行頭から開始する。 これにより、パッチの内容を確認しやすくなる。 パッチは文単位で
あることが多いからである。
タイトル行
man ページの最初の行は TH コマンドにすべきである。
.TH title section date source manual
個々の説明:
title man ページのタイトル。全部大文字で記載する (例: MAN-PAGES)。
section man ページが属するセクション番号 (例: 7)。
date 最新のリビジョンの日付—man ページに変更を加えたときには 必ずこれを変更す
ること。 これが最も一般的なバージョン管理方法である。 日付は YYYY-MM-DD
の形式で記載すべきである。
source コマンド、関数、システムコールの出自。
数少ないセクション 1 と 8 のページの場合、おそらく単に GNU とだけ書くこと
が多いだろう。
システムコールの場合、単に Linux とだけ書く。 (以前の慣習では、マニュアル
ページを記載した/内容を確認したカーネルの バージョン番号を記載してい
た。しかし、バージョン番号が実際の内容と 一致していることはなく、そのため
バージョン番号がないよりも おそらく悪い形になっていた。 今後は、バージョ
ン番号を含めるのは避けること。)
glibc のライブラリコールや その他の一般的な GNU ライブラリのライブラリ
コールの場合、 単に GNU C Library, GNU と書くか、空の文字列を使う。
セクション 4 のページでは Linux を使う。
よくわからない場合は、 Linux とか GNU と書いておく。
manual マニュアルのタイトル (例: man-pages パッケージのセクション 2 および 3 の
ページの場合には、 Linux Programmer's Manual を使うこと)。
マニュアルページのセクション
昔から使われてきたセクション名を以下のリストに示す。 これらを使うと良いだろう。 一般的
に、マニュアルページは、少なくとも 色つき のセクションを持つのが望ましい。 新しくマニュア
ルページを作成する際には、だいたい以下のリストに示した 順序でセクションを配置するようにし
てもらいたい。
名前
書式
設定 [通常はセクション 4 のみ]
説明
オプション [通常はセクション 1, 8 のみ]
終了ステータス [通常はセクション 1, 8 のみ]
返り値 [通常はセクション 2, 3 のみ]
エラー [たいていはセクション 2, 3 のみ]
環境変数
ファイル
属性 [通常はセクション 2, 3 のみ]
バージョン [通常はセクション 2, 3 のみ]
準拠
注意/備考
バグ
例
関連項目
「伝統的に使われてきた見出しが使える場合には、それを使ってほしい。」 この種の一貫性を保つ
ことで、情報を理解しやすくなるからである。 どうしても必要な場合には、理解しやすくなるよう
に独自の見出しを 作ってもよい (特にセクション 4 や 5 のページではこうした方が わかりやすく
なる)。ただし、そうする前に、伝統的な見出しを使い、 そのセクション内にサブセクション (.SS)
を設けることで 対応できないか考えてほしい。
以下のリストでは、上記のセクションのそれぞれの内容について 詳しく説明する。
名前 (NAME) マニュアルページの名前。 .SH NAME コマンドの後に続ける行の重要な情報について
は man(7) を参照。この行のすべての単語は ("\-" の直後の単語も含め) 小文字に
すべきである。但し、英語や技術用語の慣例として別の記載をする場合はこの限りで
はない。
書式 (SYNOPSIS)
コマンドや関数のインターフェースを簡潔に記述する。 コマンドに対しては、コマ
ンドや引き数 (オプション) の文法を書く。 そのまま書くテキストにはボールド体
を用い、置き換える引き数には イタリック体を用いる。省略可能なオプションはブ
ラケット ([]) で囲い、 選択肢は縦棒 (|) で区切り、繰り返しには省略符号 (...)
を書く。 関数に対しては、必要なデータ宣言や #include 指定を書き、関数宣言を
続ける。
ヘッダファイルから関数 (や変数) の定義を得るために 機能検査マクロ (feature
test macro) を定義しなければならない場合、 書式 (SYNOPSIS) に必要な機能検査
マクロを記載すべきである。 機能検査マクロについては feature_test_macros(7)
で説明されている。
CONFIGURATION デバイスの設定詳細。 通常、このセクションは 4 章のマニュアルページでのみ登場
する。
説明 (DESCRIPTION)
プログラム・関数・フォーマットの動作・目的を説明する。 ファイルや標準入力を
どのように処理し、標準出力や標準エラー出力を どのように生成するかといったこ
とについて述べる。 内部動作や実装の詳細については省略する (ただしそれが動作
の理解にどうしても必要なら別)。 通常の場合について記述する。 プログラムのコ
マンドライン・オプションの説明には、 オプション のセクションを用いる。
システムコールやライブラリ関数の新しい動作や新しいフラグについて説明する際
は、 変更が取り込まれたカーネルや C ライブラリのバージョンを注記に入れるよう
に気を付けること。 フラグにこの情報の注記を入れる方法としては、推奨される方
法は、 以下のように .TP リストの一部にすることである (この例はシステムコール
の新しいフラグの場合)。
XYZ_FLAG (Linux 3.7 以降)
フラグの説明...
バージョン情報を入れておくのは、 古いバージョンのカーネルや C ライブラリを使
わざるを得ないユーザにとって、 特に有用である (例えば、組み込みシステムでは
よくあることである)。
オプション (OPTIONS)
プログラムが受け付けるコマンドライン・オプションと、 その場合プログラムの振
舞いがどう変わるかを説明する。 このセクションはセクション 1 と 8 のマニュア
ルページにだけ登場すべきである。
終了ステータス (EXIT STATUS)
プログラムの終了ステータスの値と、それらの値に対応する状況を列挙する。 この
セクションはセクション 1 と 8 のマニュアルページにだけ登場すべきである。
返り値 (RETURN VALUE)
セクション 2 と 3 のページの場合、このセクションに ライブラリルーチンが呼び
出し元に返す値のリストを記載する。 それらの値が返された場合の状態に対する説
明も書く。
エラー (ERRORS)
セクション 2 と 3 のマニュアルページでは、 エラーが発生した場合に errno に設
定される可能性がある値のリストを記載する。 リストには、エラーの値とエラーの
原因についての情報を書く。 「エラーリストはアルファベット順にすべきであ
る。」
環境変数 (ENVIRONMENT)
プログラムや関数に影響する環境変数をリストし、それらの効果を書く。
ファイル (FILES)
プログラムや関数が用いるファイルを列記する。 例えば、設定ファイル、起動ファ
イル、プログラムが直接操作するファイルなどである。 これらのファイルのファイ
ル名はフルパスで記載し、 ディレクトリの部分はユーザーの好みに合わせて インス
トール処理で変更できるようにする。 多くのプログラムではデフォルトのインス
トール先は /usr/local である。したがってベースとなるマニュアルページでも
/usr/local が使われていることが多いだろう。
属性 (ATTRIBUTES)
そのページで説明している関数の種々の属性の概要を、サブセクションに分けて説明
する。以下のサブセクションが定義されている。
マルチスレッディング (pthreads(7) 参照)
このサブセクションでは、マルチスレッドアプリケーションに関連する属性
について説明する。
* その関数がスレッドセーフかどうか。
* その関数が取り消しポイント (cancellation point) かどうか。
* その関数が非同期で安全にキャンセルできるか (async-cancel-safe かど
うか)。
これらの属性の詳細は pthreads(7) で説明されている。
バージョン (VERSIONS)
システムコールやライブラリ関数が登場したり、動作の重要な変更が行われた、
Linux カーネルや glibc のバージョンについての簡潔な概要。 一般に、全ての新し
いインターフェイスは、マニュアルページに 「バージョン」の節を設けるべきであ
る。 残念なことに、多くの既存のマニュアルページにこの情報は含まれていない
(これらのページが書かれた時点ではそのようなポリシーはなかったからである)。
これを改善するパッチは歓迎されるが、 新しいコードを書くプログラマの観点から
すれば、 おそらくこの情報が重要になるのは、 Linux 2.4 以降で追加されたカーネ
ルインターフェイス (カーネル 2.2 からの変更) と glibc バージョン 2.1 以降で
追加されたライブラリ関数 (glibc 2.0 からの変更) についてのみであろう。
syscalls(2) マニュアルページにも、いろいろなシステムコールが初めて登場した
カーネルバージョンについての情報が書かれている。
準拠 (CONFORMING TO)
そのマニュアルページで説明している関数やコマンドに関連する 標準規格や慣習に
ついて記載する。 セクション 2 や 3 のページでは、このセクションで システム
コールや関数が準拠する POSIX.1 のバージョンと、 C99 で規定されているかに触れ
るべきである。 (SUS, SUSv2, XPG などの他の標準規格や、SVr4 や 4.xBSD の実装
標準に ついては、説明しているコールがこれらの規格で規定されており POSIX.1 の
現行バージョンで規定されていない場合以外は、 あまり深く気にする必要はない。)
(standards(7) 参照。)
そのコールがどの標準にも基づいていないが、 他のシステムで広く存在する場合
は、その旨を記載すること。 そのコールが Linux 固有の場合は、その旨を記載する
こと。
(そうなっているページが多いが) このセクションの内容が標準のリスト だけの場
合、リストの最後にピリオド ('.') を置くこと。
注意 (NOTES) その他の注意点を書く。 セクション 2 と 3 のマニュアルページでは、 Linux での
注意 (Linux Notes) や glibc での注意 (Glibc Notes) という名前のサブセクショ
ン (SS) を設けると便利なこともある。
バグ (BUGS) 制限・知られている欠陥や不便な点、その他不思議な動作などを書く。
例 (EXAMPLE) この関数・ファイル・コマンドをどのように使うかを示した ひとつまたは複数の例
を記述する。 サンプルプログラムを書く際の詳細は 以下の「サンプルプログラ
ム」の節を参照のこと。
著者 (AUTHORS)
文書またはプログラムの著者を列記する。 著者セクションは極力使用しないこと。
一般的には、著者のリストを各ページに撒き散らさない方がよい (時間がたつと、作
者のリストは膨大になる可能性がある)。 マニュアルページを新規に書いたり、大幅
に修正を行った場合には、 ソースファイルにコメントとして著作権表示を追加する
こと。 あなたがデバイスドライバの作者で、バグを報告するためのアドレスを 載せ
たい場合は、「バグ」セクションの後ろにこのセクションを配置すること。
関連項目 (SEE ALSO)
関連するマニュアルページを、コンマ区切りのリストで、 セクション番号順に、セ
クション内ではアルファベット順で記載する。 可能なら関連する他の文書も書く。
慣習では、このセクションは最後に置く。 リストの末尾にピリオドを置かないこ
と。
関連項目のリストに長いマニュアルページ名が多く含まれる場合には、出力を見やす
くするために .ad l (右揃えをしない) や .nh (ハイフンによる折り返しをしない)
を活用するとよい。個々のページ名のハイフンによる折り返しは、単語の前に "\%"
を付けることで防ぐことができる。
フォントの慣習
関数に対しては、引き数には常にイタリック体を用いる。 「たとえ書式 (SYNOPSIS) セクションで
あっても、このルールに従う」 関数の他の部分はボールドを指定する:
int myfunction(int argc, char **argv);
引き数名といった変数名はイタリック体を指定すべきである。
ファイル名 (パス名、または /usr/include ディレクトリ内のファイルへの参照) は常にイタリック
体にする (例: <stdio.h>)。 ただし、書式 (SYNOPSIS) セクションは例外で、 インクルードファイ
ルはボールドにする (例: #include <stdio.h>)。 /usr/include 以下の標準のインクルードファイ
ルを参照する際は、 通常の C 言語と同様に山括弧でヘッダファイルを囲ぬで指定する (例：
<stdio.h>)。
通常、大文字で表現する特殊マクロはボールドで表す (例えば MAXINT)。 例外として NULL はボー
ルドにしない。
エラーコードのリストを列挙する時には、コードはボールドで表す (このリストには通常 .TP マク
ロを用いる)。
完全なコマンドは、長い場合には、例に示すように 字下げした行にコマンドだけを記載すべきであ
る。
man 7 man-pages
コマンドが短い場合は、 man 7 man-pages のようにイタリック体で文中に埋め込んで記載してもよ
い。 この場合、コマンド内の適切な位置に、改行できないスペース ("\ ") を使うとよいかもしれ
ない。 コマンドオプションも -l のようにイタリック体で記載すべきである。
式は、専用の字下げした行に記載しない場合、イタリック体を指定すること。 繰り返しになる
が、式を通常の文中に埋め込む場合にも、 改行できないスペースを使うとよいだろう。
そのマニュアルページの説明対象への参照は、ボールドで名前を記載する。 対象が関数 (つま
り、セクション 2 や 3 のページ) の場合、 名前の後ろにローマンフォント (通常のフォント) で
丸括弧の対を続ける。 例えば、 fcntl(2) のマニュアルページでは、説明対象への参照は fcntl()
のように記載する。 マニュアルページのソースファイルには次のように記載するのが望ましい:
.BR fcntl ()
("\fB...\fP()" よりも、この形式を使うこと。 これにより、マニュアルページのソースファイルを
解釈するツールを 書くのが簡単になる。)
別のマニュアルページへの参照は、ボールドで名前を記載し、 それに続けてセクション番号を「必
ず」書く。セクション番号は ローマンフォント (通常のフォント) で書き、スペースは入れない
(例: intro(2))。 マニュアルページのソースファイルには次のように記載するのが望ましい:
.BR intro (2)
(相互参照にセクション番号を含めておくと、 man2html といったツールがページ間のハイパーリン
クを適切に生成できる。)
綴り (spelling)
リリース 2.59 からだが、 man-pages はアメリカ英語の綴りの慣習に従っている。 新しいページや
パッチは全てこの慣習に従って下さい。
大文字表記
サブセクション ("SS") 見出しでは、最初の単語だけ先頭文字を大文字にし、残りの単語は小文字に
すること。但し、英語の用法 (例えば、固有名詞) やプログラミング言語の要件 (例えば、識別子の
名前) などで別の表記をする場合はこの限りではない。
サンプルプログラムとシェルのセッション
マニュアルページには、システムコールやライブラリ関数の使い方を示す サンプルプログラムを含
めることができる。 その際には、以下の点に留意すべきである。
* サンプルプログラムは C で記載すること。
* サンプルプログラムは、 インタフェースについて文章で簡単に説明できる以上のことを示す場合
にだけ 必要かつ有用である。インタフェースを呼び出す以外に何もしないサンプル プログラム
は普通はほとんど役に立たない。
* サンプルプログラムはかなり短めにすること (100行未満が望ましく、50行未満が理想的であ
る)。
* サンプルプログラムでは、システムコールやライブラリ関数を呼び出した後で エラーチェックを
行うこと。
* サンプルプログラムは完結していて、 cc -Wall でコンパイルした際に警告なしでコンパイルで
きること。
* 可能かつ適切な場合には、サンプルプログラムで 入力により動作を変化させるなどの実験を行う
とよい (理想的には、コマンドライン引き数や、プログラムが読み込む入力データ 経由で、動作
を変化させるのがよい)。
* サンプルプログラムは、K&R (Kernighan and Ritchie) スタイルで書き、 字下げはスペース 4文
字で行う。 (ソースコードで TAB 文字を使うのは避けること。)
サンプルプログラムがどんな風になっていればよいかの例については、 wait(2) と pipe(2) を参
照すること。
プログラムの使い方や他のシステムの特徴を示すためにシェルのセッション例 を含める場合、ユー
ザの入力文をボールドにして、システムが生成する 出力と区別できるようにすること。
構造体の定義、シェルのセッションログなどの字下げ
構造体の定義やシェルのセッションログなどを本文中に記載する際は、 スペース 4個分の字下げを
行う (つまり、ブロックを .in +4n と .in で囲む)。
例
man-pages パッケージに含まれるマニュアルページの体裁の標準的な例については、 pipe(2) と
fcntl(2) を参照すること。
関連項目
man(1), man2html(1), groff(7), groff_man(7), man(7), mdoc(7)
この文書について
この man ページは Linux man-pages プロジェクトのリリース 3.54 の一部 である。プロジェクト
の説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。