MAN-PAGES(7) | Linux Programmer's Manual | MAN-PAGES(7) |
man-pages - Linux の man ページを書く際の決まり事
man [section] title
このページでは、 Linux man-pages プロジェクトのマニュアルページを書く際に 従うべき決まり事について説明する。 Linux man-pages プロジェクトは Linux カーネルおよび GNU C ライブラリが提供するユーザー空間 API のドキュメント作成を行っている。Linux システムのマニュアルページのセクション 2 のページのほとんどと、セクション 3, 4, 5, 7 の多くのページが、このプロジェクトにより提供されている。このページで説明されている決まり事は、他のプロジェクトの マニュアルページを書く作者にも役立つことだろう。
マニュアルのセクションは、習慣的に以下のような定義が用いられている:
新しいマニュアルページは man(7) で説明されている groff an.tmac パッケージを使って記述すべきである。 この方針は一貫性の確保が主な理由である。既存の Linux のマニュアルページ の圧倒的多数がこれらのマクロを使って記述されている。
マニュアルページのソースコードの 1行の長さは 可能な限り 75文字を越えないようにしてほしい。 こうすることで、パッチをメール本文に載せて送る場合に、 メールクライアントによる行折り返しを回避することができる。
新しい文は行頭から開始する。 これにより、パッチの内容を確認しやすくなる。 パッチは文単位であることが多いからである。
man ページの最初の行は TH コマンドにすべきである。
.TH title section date source manual
数少ないセクション 1 と 8 のページの場合、おそらく単に GNU とだけ書くことが多いだろう。
システムコールの場合、単に Linux とだけ書く。 (以前の慣習では、マニュアルページを記載した/内容を確認したカーネルの バージョン番号を記載していた。しかし、バージョン番号が実際の内容と 一致していることはなく、そのためバージョン番号がないよりも おそらく悪い形になっていた。 今後は、バージョン番号を含めるのは避けること。)
glibc のライブラリコールや その他の一般的な GNU ライブラリのライブラリコールの場合、 単に GNU C Library, GNU と書くか、空の文字列を使う。
セクション 4 のページでは Linux を使う。
よくわからない場合は、 Linux とか GNU と書いておく。
昔から使われてきたセクション名を以下のリストに示す。
これらを使うと良いだろう。
一般的に、マニュアルページは、少なくとも
色つき
のセクションを持つのが望ましい。
新しくマニュアルページを作成する際には、だいたい以下のリストに示した
順序でセクションを配置するようにしてもらいたい。
名前 書式 設定 [通常はセクション 4 のみ] 説明 オプション [通常はセクション 1, 8 のみ] 終了ステータス [通常はセクション 1, 8 のみ] 返り値 [通常はセクション 2, 3 のみ] エラー [たいていはセクション 2, 3 のみ] 環境変数 ファイル バージョン [通常はセクション 2, 3 のみ] 属性 [通常はセクション 2, 3 のみ] 準拠 注意/備考 バグ 例 関連項目
「伝統的に使われてきた見出しが使える場合には、それを使ってほしい。」 この種の一貫性を保つことで、情報を理解しやすくなるからである。 どうしても必要な場合には、理解しやすくなるように独自の見出しを 作ってもよい (特にセクション 4 や 5 のページではこうした方が わかりやすくなる)。ただし、そうする前に、伝統的な見出しを使い、 そのセクション内にサブセクション (.SS) を設けることで 対応できないか考えてほしい。
以下のリストでは、上記のセクションのそれぞれの内容について 詳しく説明する。
.SH NAME コマンドの後に続ける行の重要な情報については man(7) を参照。この行のすべての単語は ("\-" の直後の単語も含め) 小文字にすべきである。但し、英語や技術用語の慣例として別の記載をする場合はこの限りではない。
コマンドに対しては、コマンドや引き数 (オプション) の文法を書く。 そのまま書くテキストにはボールド体を用い、置き換える引き数には イタリック体を用いる。省略可能なオプションはブラケット ([]) で囲い、 選択肢は縦棒 (|) で区切り、繰り返しには省略符号 (...) を書く。 関数に対しては、必要なデータ宣言や #include 指定を書き、関数宣言を続ける。
ヘッダーファイルから関数 (や変数) の定義を得るために 機能検査マクロ (feature test macro) を定義しなければならない場合、 書式 (SYNOPSIS) に必要な機能検査マクロを記載すべきである。 機能検査マクロについては feature_test_macros(7) で説明されている。
通常、このセクションは 4 章のマニュアルページでのみ登場する。
ファイルや標準入力をどのように処理し、標準出力や標準エラー出力を どのように生成するかといったことについて述べる。 内部動作や実装の詳細については省略する (ただしそれが動作の理解にどうしても必要なら別)。 通常の場合について記述する。 プログラムのコマンドラインオプションの説明には、 オプション のセクションを用いる。
システムコールやライブラリ関数の新しい動作や新しいフラグについて説明する際は、 変更が取り込まれたカーネルや C ライブラリのバージョンを注記に入れるように気を付けること。 フラグにこの情報の注記を入れる方法としては、推奨される方法は、 以下のように .TP リストの一部にすることである (この例はシステムコールの新しいフラグの場合)。
このセクションはセクション 1 と 8 のマニュアルページにだけ登場すべきである。
このセクションはセクション 1 と 8 のマニュアルページにだけ登場すべきである。
「エラーリストはアルファベット順にすべきである。」
これらのファイルのファイル名はフルパスで記載し、 ディレクトリの部分はユーザーの好みに合わせて インストール処理で変更できるようにする。 多くのプログラムではデフォルトのインストール先は /usr/local である。したがってベースとなるマニュアルページでも /usr/local が使われていることが多いだろう。
以下のサブセクションが定義されている。
一般に、全ての新しいインターフェイスは、マニュアルページに 「バージョン」の節を設けるべきである。 残念なことに、多くの既存のマニュアルページにこの情報は含まれていない (これらのページが書かれた時点ではそのようなポリシーはなかったからである)。 これを改善するパッチは歓迎されるが、 新しいコードを書くプログラマの観点からすれば、 おそらくこの情報が重要になるのは、 Linux 2.4 以降で追加されたカーネルインターフェイス (カーネル 2.2 からの変更) と glibc バージョン 2.1 以降で追加されたライブラリ関数 (glibc 2.0 からの変更) についてのみであろう。
syscalls(2) マニュアルページにも、いろいろなシステムコールが初めて登場した カーネルバージョンについての情報が書かれている。
様々な標準を示すのに適した用語は standards(7) に見出しでリストになっている。
セクション 2 や 3 のページでは、このセクションで システムコールや関数が準拠する POSIX.1 のバージョンと、 C99 で規定されているかに触れるべきである。 (SUS, SUSv2, XPG などの他の標準規格や、SVr4 や 4.xBSD の実装標準に ついては、説明しているコールがこれらの規格で規定されており POSIX.1 の現行バージョンで規定されていない場合以外は、 あまり深く気にする必要はない。)
そのコールがどの標準にも基づいていないが、 他のシステムで広く存在する場合は、その旨を記載すること。 そのコールが Linux 固有の場合は、その旨を記載すること。
(そうなっているページが多いが) このセクションの内容が標準のリスト だけの場合、リストの最後にピリオド ('.') を置くこと。
セクション 2 と 3 のマニュアルページでは、 Linux での注意 (Linux Notes) や glibc での注意 (Glibc Notes) という名前のサブセクション (SS) を設けると便利なこともある。
セクション 2 では、 システムコールに対する C ライブラリのラッパー関数とカーネルが提供する素のシステムコールのインターフェースの間で違いがある場合に、その違いを説明する注記を記載する際には C ライブラリとカーネル ABI の違い という見出しを使うこと。
サンプルプログラムを書く際の詳細は 以下の「サンプルプログラム」の節を参照のこと。
著者セクションは極力使用しないこと。 一般的には、著者のリストを各ページに撒き散らさない方がよい (時間がたつと、作者のリストは膨大になる可能性がある)。 マニュアルページを新規に書いたり、大幅に修正を行った場合には、 ソースファイルにコメントとして著作権表示を追加すること。 あなたがデバイスドライバの作者で、バグを報告するためのアドレスを 載せたい場合は、「バグ」セクションの後ろにこのセクションを配置すること。
リストは、 セクション番号順に、セクション内ではアルファベット順で記載する。 このリストの末尾にピリオドを置かないこと。
FOSS プロジェクトやそのドキュメントは本質的に分散して自律的に行われるので、 「関連項目」セクションに他のプロジェクトが提供するマニュアルページへの参照を含める必要がときとしてあり、多くの場合は含めるのが望ましい場合がある。
以下の節ではman-pagesプロジェクトで推奨のスタイルについて説明している。 ここで触れられていない点については、"the Chicago Manual of Style" がたいていはよい情報源になるだろう。 また、すでに使用されているスタイルについてはプロジェクトのソースツリーを検索してみてほしい。 (訳注:この章では英語の原文でのスタイルについて説明しており、日本語マニュアルにはあわない点もあるため、具体例などは英語のままとしている箇所もあります。)
可能な限り、マニュアルページの文章では性別の区別のない表現を使用すること。 性別に区別のない単数形の代名詞として "they" ("them", "themself", "their") を使用してもよい。
関数に対しては、引き数には常にイタリック体を用いる。 「たとえ書式 (SYNOPSIS) セクションであっても、このルールに従う」 関数の他の部分はボールドを指定する:
int myfunction(int argc, char **argv);
引き数名といった変数名はイタリック体を指定すべきである。
ファイル名 (パス名、またはヘッダーファイルへの参照) は常にイタリック体にする (例: <stdio.h>)。 ただし、書式 (SYNOPSIS) セクションは例外で、 インクルードファイルはボールドにする (例: #include <stdio.h>)。 標準のインクルードヘッダーファイルを参照する際は、 通常の C 言語と同様に山括弧でヘッダーファイルを囲ぬで指定する (例: <stdio.h>)。
通常、大文字で表現する特殊マクロはボールドで表す (例えば MAXINT)。 例外として NULL はボールドにしない。
エラーコードのリストを列挙する時には、コードはボールドで表す (このリストには通常 .TP マクロを用いる)。
完全なコマンドは、長い場合には、例に示すように
字下げした行にコマンドだけを記載し、コマンドの前後には空行を置くべきである。
man 7 man-pages
式は、専用の字下げした行に記載しない場合、イタリック体を指定すること。 繰り返しになるが、式を通常の文中に埋め込む場合にも、 改行できないスペースを使うとよいだろう。
そのマニュアルページの説明対象への参照は、ボールドで名前を記載する。 対象が関数 (つまり、セクション 2 や 3 のページ) の場合、 名前の後ろにローマンフォント (通常のフォント) で丸括弧の対を続ける。 例えば、 fcntl(2) のマニュアルページでは、説明対象への参照は fcntl() のように記載する。 マニュアルページのソースファイルには次のように記載するのが望ましい:
("\fB...\fP()" よりも、この形式を使うこと。 これにより、マニュアルページのソースファイルを解釈するツールを 書くのが簡単になる。)
.BR fcntl ()
別のマニュアルページへの参照は、ボールドで名前を記載し、 それに続けてセクション番号を「必ず」書く。セクション番号は ローマンフォント (通常のフォント) で書き、スペースは入れない (例: intro(2))。 マニュアルページのソースファイルには次のように記載するのが望ましい:
(相互参照にセクション番号を含めておくと、 man2html といったツールがページ間のハイパーリンクを適切に生成できる。)
.BR intro (2)
制御文字は太字で引用符なしで表記すること。 例えば ^X。
リリース 2.59 からだが、 man-pages はアメリカ英語の綴りの慣習に従っている (以前はイギリス英語とアメリカ英語が基準もなく混在して使われていた)。 新しいページやパッチは全てこの慣習に従って下さい。
よく知られた綴りの違い以外に、微妙な違いもいくつか見られる。
BSD バージョン番号の伝統的な表記方法は x.yBSD である (x.y はバージョン番号; 例: 4.2BSD)。 BSD 4.3 といった表記は避けること。
サブセクション ("SS") 見出しでは、最初の単語だけ先頭文字を大文字にし、残りの単語は小文字にすること。但し、英語の用法 (例えば、固有名詞) やプログラミング言語の要件 (例えば、識別子の名前) などで別の表記をする場合はこの限りではない。
.SS Unicode under Linux
構造体の定義やシェルのセッションログなどを本文中に記載する際は、 スペース 4個分の字下げを行う (つまり、ブロックを .in +4n と .in で囲む)。
以下の表にマニュアルページでの使用が推奨される用語を示す。これらは主にマニュアルページ間での一貫性を保つためである。
用語 | 使用を避ける単語 | 備考 |
bit mask | bitmask | |
built-in | builtin | |
Epoch | epoch | For the UNIX Epoch (00:00:00, 1 Jan 1970 UTC) |
filename | file name | |
filesystem | file system | |
hostname | host name | |
inode | i-node | |
lowercase | lower case, lower-case | |
pathname | path name | |
pseudoterminal | pseudo-terminal | |
privileged port | reserved port, system port | |
real-time | realtime, real time | |
run time | runtime | |
saved set-group-ID | saved group ID, saved set-GID | |
saved set-user-ID | saved user ID, saved set-UID | |
set-group-ID | set-GID, setgid | |
set-user-ID | set-UID, setuid | |
superuser | super user, super-user | |
superblock | super block, super-block | |
timestamp | time stamp | |
timezone | time zone | |
uppercase | upper case, upper-case | |
usable | useable | |
user space | userspace | |
username | user name | |
zeros | zeroes |
以下の修飾子としての複合語におけるハイフンの議論も参照。
以下の表にマニュアルページでの使用を避けるべき用語を示す。 推奨される表現も合わせて記載している。 これらは主にマニュアルページ間での一貫性を保つためである。
使用を避ける | 使用を推奨 | 備考 |
32bit | 32-bit | 8-bit, 16-bit なども同様 |
current process | calling process | カーネルプログラマーがマニュアルページを書く際によくする間違い |
manpage | man page, manual page | |
minus infinity | negative infinity | |
non-root | unprivileged user | |
non-superuser | unprivileged user | |
nonprivileged | unprivileged | |
OS | operating system | |
plus infinity | positive infinity | |
pty | pseudoterminal | |
tty | terminal | |
Unices | UNIX systems | |
Unixes | UNIX systems |
商標については正しい綴りと大文字小文字を使うこと。以下は時々綴りの間違いがある商標の正しい綴りのリストである。
DG/UX
HP-UX
UNIX
UnixWare
null pointer (ヌルポインター) は何もないものを指すポインターで、通常は定数 NULL で示される。 一方、 NUL は null byte (ヌルバイト、値 0 のバイト) で、 C では文字定数 '\0' と表現される。
ポインターとして推奨される用語は "null pointer" (ヌルポインター) もしくは単に "NULL" である。 "NULL pointer" と記載するのは避けること。
バイトとして推奨される用語は "null byte" (ヌルバイト) である。 "NUL" と記載するのは避けること。 "NUL" は "NULL" と間違われることが非常に多いからである。 また、 "zero byte" (ゼロバイト) と "null character" (ヌル文字) も避けること。 C の文字列を終端するバイトは "the terminating null byte" (終端ヌルバイト)、 文字列の説明として使う場合には "null-terminated" (ヌル終端された) と記載すべきである。 "NUL-terminated" の使用は避けること。
ハイパーリンクについては、 .UR/.UE マクロの組を使うこと (groff_man(7) 参照)。ページを以下のようにレンダリングする場合に、このマクロはウェブブラウザーで使用できる正しいハイパーリンクを生成してくれる。
BROWSER=firefox man -H pagename
一般的には、 "e.g.", "i.e.", "etc.", "a.k.a." などの省略形の使用は避けるべきである。 代わりに完全な形の単語を使うこと ("for example" (例えば), "that is" (つまり), "and so on" (〜など), "also known as" (別名))。
これらの省略形の使用が認められる唯一の場所は、 短い括弧で囲まれた余談 ("(e.g., like this one)") の場合である。
ここで記載しているように、これらの省略形では必ずピリオドを入れること。 また、"e.g." と "i.e." では常に後にカンマも付けること。
*roff で em によるダッシュ—この部分の両端にある記号—を書くには "\(em" を使う。 (ASCII 端末では em によるダッシュは通常ハイフン 2 つとして表示されるが、別の活版印刷の場合などでは長いダッシュとして表示されることもある。) em によるダッシュの両側にはスペースを置かないこと。
何かを修飾する際 (すなわち後続の名詞を限定する場合) 複合語にはハイフンを入れること。いくつか例を挙げる。
32-bit value (32 ビット値)
command-line argument
(コマンドライン引き数)
floating-point number (浮動小数点数)
run-time check (実行時チェック)
user-space function
(ユーザー空間関数)
wide-character string
(ワイド文字の文字列)
一般的に最近の英語の傾向では、"multi", "non", "pre", "re", "sub" などの接尾辞の後ろにはハイフンを付けない。 これらの接尾辞が単純な接尾語との普通の英語の組み合わせの場合には、 マニュアルページでは基本的にこのルールに従う。 以下のリストに推奨される形式での例をいくつか挙げる。
interprocess
multithreaded
multiprocess
nonblocking
nondefault
nonempty
noninteractive
nonnegative
nonportable
nonzero
preallocated
precreate
prerecorded
reestablished
reinitialize
rearm
reread
subcomponent
subdirectory
subsystem
接尾語が通常の英単語以外 (商標、固有名詞、頭字語、複合語) と組み合わされる場合は、ハイフンを使うこと。以下に例を挙げる。
non-ASCII
non-English
non-NULL
non-real-time
最後に、"re-create" と "recreate" は異なる別の動詞である点に注意すること。たいていの場合、使おうと思っているのは前者であろう。
本当の意味でのマイナス文字が必要な場合は (-1 といった数字や ls -l といった先頭にダッシュのオプションを記載する場合など)、マニュアルページの原文では以下の表記を使うこと。
\-
このガイドラインはサンプルコードの場合にも適用される。
ASCII と UTF-8 の両方で正しくレンダリングされるシングルクォート (一重引用符) を生成するには、マニュアルページの原文では以下の表記を使うこと。
\(aqC\(aq
ここで C が括弧で囲まれる文字である。このガイドラインはサンプルコードの場合にも適用される。
マニュアルページには、システムコールやライブラリ関数の使い方を示す サンプルプログラムを含めることができる。 その際には、以下の点に留意すべきである。
exit(EXIT_SUCCESS);
exit(EXIT_FAILURE);
プログラムを終了するのに以下を使うのは避けること。
.SS プログラムのソース
説明文がシェルセッションのログを含む場合は必ずこのようにすること。
プログラムの使い方や他のシステムの特徴を示すためにシェルのセッションログを含める場合、
man-pages パッケージに含まれるマニュアルページの体裁の標準的な例については、 pipe(2) と fcntl(2) を参照すること。
man(1), man2html(1), groff(7), groff_man(7), man(7), mdoc(7)
この man ページは Linux man-pages プロジェクトのリリース 3.79 の一部 である。プロジェクトの説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。
2014-12-31 | Linux |