.\" Updated 2008-08-09, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v3.05
.\" Updated 2013-05-04, Akihiro MOTOKI <amotoki@gmail.com>
.\" Updated 2013-07-24, Akihiro MOTOKI <amotoki@gmail.com>
+.\" Updated 2013-08-21, Akihiro MOTOKI <amotoki@gmail.com>, LDP v3.53
.\"
-.TH MAN\-PAGES 7 2013\-07\-24 Linux "Linux Programmer's Manual"
+.TH MAN\-PAGES 7 2014\-03\-16 Linux "Linux Programmer's Manual"
.SH 名前
man\-pages \- Linux の man ページを書く際の決まり事
.SH 書式
man ページが属するセクション番号 (例: \fI7\fP)。
.TP
\fIdate\fP
-最新のリビジョンの日付\(emman ページに変更を加えたときには 必ずこれを変更すること。 これが最も一般的なバージョン管理方法である。 日付は
-YYYY\-MM\-DD の形式で記載すべきである。
+最新のリビジョンの日付\(emman ページに些細でない変更を加えたときには必ずこれを変更すること。 日付は YYYY\-MM\-DD
+の形式で記載すべきである。
.TP
\fIsource\fP
コマンド、関数、システムコールの出自。
エラー [たいていはセクション 2, 3 のみ]
環境変数
ファイル
-属性 [通常はセクション 2, 3 のみ]
バージョン [通常はセクション 2, 3 のみ]
+属性 [通常はセクション 2, 3 のみ]
準拠
注意/備考
バグ
どのように生成するかといったことについて述べる。 内部動作や実装の詳細については省略する (ただしそれが動作の理解にどうしても必要なら別)。
通常の場合について記述する。 プログラムのコマンドライン・オプションの説明には、 \fBオプション\fP のセクションを用いる。
-When describing new behavior or new flags for a system call or library
-function, be careful to note the kernel or C library version that introduced
-the change. The preferred method of noting this information for flags is as
-part of a \fB.TP\fP list, in the following form (here, for a new system call
-flag):
+システムコールやライブラリ関数の新しい動作や新しいフラグについて説明する際は、 変更が取り込まれたカーネルや C
+ライブラリのバージョンを注記に入れるように気を付けること。 フラグにこの情報の注記を入れる方法としては、推奨される方法は、 以下のように \fB.TP\fP
+リストの一部にすることである (この例はシステムコールの新しいフラグの場合)。
.RS 22
.TP
\fBXYZ_FLAG\fP (Linux 3.7 以降)
-Description of flag...
+フラグの説明...
.RE
.IP
-Including version information is especially useful to users who are
-constrained to using older kernel or C library versions (which is typical in
-embedded systems, for example).
+バージョン情報を入れておくのは、 古いバージョンのカーネルや C ライブラリを使わざるを得ないユーザにとって、 特に有用である
+(例えば、組み込みシステムではよくあることである)。
.TP
\fBオプション (OPTIONS)\fP
.\" .TP
\fBsyscalls\fP(2) マニュアルページにも、いろいろなシステムコールが初めて登場した カーネルバージョンについての情報が書かれている。
.TP
\fB準拠 (CONFORMING TO)\fP
-そのマニュアルページで説明している関数やコマンドに関連する 標準規格や慣習について記載する。 セクション 2 や 3 のページでは、このセクションで
-システムコールや関数が準拠する POSIX.1 のバージョンと、 C99 で規定されているかに触れるべきである。 (SUS, SUSv2, XPG
-などの他の標準規格や、SVr4 や 4.xBSD の実装標準に ついては、説明しているコールがこれらの規格で規定されており POSIX.1
-の現行バージョンで規定されていない場合以外は、 あまり深く気にする必要はない。) (\fBstandards\fP(7) 参照。)
+そのマニュアルページで説明している関数やコマンドに関連する 標準規格や慣習について記載する。 様々な標準を示すのに適した用語は
+\fBstandards\fP(7) に見出しでリストになっている。 セクション 2 や 3 のページでは、このセクションで システムコールや関数が準拠する
+POSIX.1 のバージョンと、 C99 で規定されているかに触れるべきである。 (SUS, SUSv2, XPG などの他の標準規格や、SVr4 や
+4.xBSD の実装標準に ついては、説明しているコールがこれらの規格で規定されており POSIX.1 の現行バージョンで規定されていない場合以外は、
+あまり深く気にする必要はない。) (\fBstandards\fP(7) 参照。)
そのコールがどの標準にも基づいていないが、 他のシステムで広く存在する場合は、その旨を記載すること。 そのコールが Linux
固有の場合は、その旨を記載すること。
.IP
関連項目のリストに長いマニュアルページ名が多く含まれる場合には、出力を見やすくするために \fI.ad l\fP (右揃えをしない) や \fI.nh\fP
(ハイフンによる折り返しをしない) を活用するとよい。個々のページ名のハイフンによる折り返しは、単語の前に "\e%" を付けることで防ぐことができる。
+.SH スタイルガイド
+以下の節では\fIman\-pages\fPプロジェクトで推奨のスタイルについて説明している。 ここで触れられていない点については、"the Chicago
+Manual of Style" がたいていはよい情報源になるだろう。
+また、すでに使用されているスタイルについてはプロジェクトのソースツリーを検索してみてほしい。
+(訳注：この章では英語の原文でのスタイルについて説明しており、日本語マニュアルにはあわない点もあるため、具体例などは英語のままとしている箇所もあります。)
+.SS 性別の区別のない表現の使用
+可能な限り、マニュアルページの文章では性別の区別のない表現を使用すること。 性別に区別のない単数形の代名詞として "they" ("them",
+"themself", "their") を使用してもよい。
.SS フォントの慣習
.PP
関数に対しては、引き数には常にイタリック体を用いる。 「たとえ書式 (SYNOPSIS) セクションであっても、このルールに従う」
.PP
引き数名といった変数名はイタリック体を指定すべきである。
.PP
-ファイル名 (パス名、または \fI/usr/include\fP ディレクトリ内のファイルへの参照) は常にイタリック体にする (例:
-\fI<stdio.h>\fP)。 ただし、書式 (SYNOPSIS) セクションは例外で、 インクルードファイルはボールドにする (例:
-\fB#include <stdio.h>\fP)。 \fI/usr/include\fP 以下の標準のインクルードファイルを参照する際は、 通常の
-C 言語と同様に山括弧でヘッダファイルを囲ぬで指定する (例： \fI<stdio.h>\fP)。
+ファイル名 (パス名、またはヘッダーファイルへの参照) は常にイタリック体にする (例: \fI<stdio.h>\fP)。 ただし、書式
+(SYNOPSIS) セクションは例外で、 インクルードファイルはボールドにする (例: \fB#include <stdio.h>\fP)。
+標準のインクルードヘッダファイルを参照する際は、 通常の C 言語と同様に山括弧でヘッダファイルを囲ぬで指定する (例：
+\fI<stdio.h>\fP)。
.PP
通常、大文字で表現する特殊マクロはボールドで表す (例えば \fBMAXINT\fP)。 例外として NULL はボールドにしない。
.PP
エラーコードのリストを列挙する時には、コードはボールドで表す (このリストには通常 \fB\&.TP\fP マクロを用いる)。
.PP
-å®\8cå\85¨ã\81ªã\82³ã\83\9eã\83³ã\83\89ã\81¯ã\80\81é\95·ã\81\84å ´å\90\88ã\81«ã\81¯ã\80\81ä¾\8bã\81«ç¤ºã\81\99ã\82\88ã\81\86ã\81« å\97ä¸\8bã\81\92ã\81\97ã\81\9fè¡\8cã\81«ã\82³ã\83\9eã\83³ã\83\89ã\81 ã\81\91ã\82\92è¨\98è¼\89ã\81\99べきである。
+å®\8cå\85¨ã\81ªã\82³ã\83\9eã\83³ã\83\89ã\81¯ã\80\81é\95·ã\81\84å ´å\90\88ã\81«ã\81¯ã\80\81ä¾\8bã\81«ç¤ºã\81\99ã\82\88ã\81\86ã\81« å\97ä¸\8bã\81\92ã\81\97ã\81\9fè¡\8cã\81«ã\82³ã\83\9eã\83³ã\83\89ã\81 ã\81\91ã\82\92è¨\98è¼\89ã\81\97ã\80\81ã\82³ã\83\9eã\83³ã\83\89ã\81®å\89\8då¾\8cã\81«ã\81¯ç©ºè¡\8cã\82\92ç½®ã\81\8fべきである。
.in +4n
.nf
.fi
.in
コマンドが短い場合は、 \fIman 7 man\-pages\fP のようにイタリック体で文中に埋め込んで記載してもよい。
-この場合、コマンド内の適切な位置に、改行できないスペース ("\e\ ") を使うとよいかもしれない。 コマンドオプションも \fI\-l\fP
-ã\81®ã\82\88ã\81\86ã\81«ã\82¤ã\82¿ã\83ªã\83\83ã\82¯ä½\93ã\81§è¨\98è¼\89ã\81\99ã\81¹ã\81\8dã\81§ã\81\82ã\82\8bã\80\82
+この場合、コマンド内の適切な位置に、改行できないスペース ("\e\ ") を使うとよいかもしれない。 コマンドオプションも (\fI\-l\fP のように)
+イタリック体で記載すべきである。
.PP
式は、専用の字下げした行に記載しない場合、イタリック体を指定すること。 繰り返しになるが、式を通常の文中に埋め込む場合にも、
改行できないスペースを使うとよいだろう。
.fi
(相互参照にセクション番号を含めておくと、 \fBman2html\fP といったツールがページ間のハイパーリンクを適切に生成できる。)
+
+制御文字は太字で引用符なしで表記すること。 例えば \fB^X\fP。
.SS "綴り (spelling)"
-リリース 2.59 からだが、 \fIman\-pages\fP はアメリカ英語の綴りの慣習に従っている。 新しいページやパッチは全てこの慣習に従って下さい。
+リリース 2.59 からだが、 \fIman\-pages\fP はアメリカ英語の綴りの慣習に従っている
+(以前はイギリス英語とアメリカ英語が基準もなく混在して使われていた)。 新しいページやパッチは全てこの慣習に従って下さい。
+
+よく知られた綴りの違い以外に、微妙な違いもいくつか見られる。
+.IP * 3
+アメリカ英語では "backward", "upward", "toward" を使う傾向にあるが、イギリス英語では "backwards",
+"upwards", "towards" などを使う方が多い。
+.SS "BSD バージョン番号"
+BSD バージョン番号の伝統的な表記方法は \fIx.yBSD\fP である (\fIx.y\fP はバージョン番号; 例: 4.2BSD)。 \fIBSD 4.3\fP
+といった表記は避けること。
.SS 大文字表記
サブセクション ("SS") 見出しでは、最初の単語だけ先頭文字を大文字にし、残りの単語は小文字にすること。但し、英語の用法 (例えば、固有名詞)
やプログラミング言語の要件 (例えば、識別子の名前) などで別の表記をする場合はこの限りではない。
+
+\&.SS Unicode under Linux
+
+.SS 構造体の定義、シェルのセッションログなどの字下げ、など
+構造体の定義やシェルのセッションログなどを本文中に記載する際は、 スペース 4個分の字下げを行う (つまり、ブロックを \fI.in\ +4n\fP と
+\&\fI.in\fP で囲む)。
+.SS 推奨用語
+以下の表にマニュアルページでの使用が推奨される用語を示す。これらは主にマニュアルページ間での一貫性を保つためである。
+.TS
+l l l
+---
+l l l.
+用語 使用を避ける単語 備考
+
+bit mask bitmask
+built\-in builtin
+Epoch epoch T{
+For the UNIX Epoch (00:00:00, 1 Jan 1970 UTC)
+T}
+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 T{
+reserved port,
+system port
+T}
+real\-time T{
+realtime,
+real time
+T}
+run time runtime
+saved set\-group\-ID T{
+saved group ID,
+saved set\-GID
+T}
+saved set\-user\-ID T{
+saved user ID,
+saved set\-UID
+T}
+set\-group\-ID set\-GID, setgid
+set\-user\-ID set\-UID, setuid
+superuser T{
+super user,
+super\-user
+T}
+superblock T{
+super block,
+super\-block
+T}
+timestamp time stamp
+timezone time zone
+uppercase upper case, upper\-case
+usable useable
+user space userspace
+username user name
+zeros zeroes
+.TE
+.PP
+以下の\fI修飾子としての複合語におけるハイフン\fPの議論も参照。
+.SS 使用を避ける用語
+以下の表にマニュアルページでの使用を避けるべき用語を示す。 推奨される表現も合わせて記載している。
+これらは主にマニュアルページ間での一貫性を保つためである。
+.TS
+l l l
+---
+l l l.
+使用を避ける 使用を推奨 備考
+
+32bit 32\-bit T{
+8\-bit, 16\-bit なども同様
+T}
+current process calling process T{
+カーネルプログラマーがマニュアルページを書く際によくする間違い
+T}
+manpage T{
+man page, manual page
+T}
+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
+.TE
+.SS 商標
+商標については正しい綴りと大文字小文字を使うこと。以下は時々綴りの間違いがある商標の正しい綴りのリストである。
+
+ DG/UX
+ HP\-UX
+ UNIX
+ UnixWare
+.SS "NULL, NUL, ヌルポインター、ヌル文字"
+\fInull pointer\fP (\fIヌルポインター\fP) は何もないものを指すポインターで、通常は定数 \fINULL\fP で示される。 一方、
+\fINUL\fP は \fInull byte\fP (\fIヌルバイト\fP、値 0 のバイト) で、 C では文字定数 \fI\(aq\e0\(aq\fP と表現される。
+
+ポインターとして推奨される用語は "null pointer" (ヌルポインター) もしくは単に "NULL" である。 "NULL pointer"
+と記載するのは避けること。
+
+バイトとして推奨される用語は "null byte" (ヌルバイト) である。 "NUL" と記載するのは避けること。 "NUL" は "NULL"
+と間違われることが非常に多いからである。 また、 "zero byte" (ゼロバイト) と "null character" (ヌル文字)
+も避けること。 C の文字列を終端するバイトは "the terminating null byte" (終端ヌルバイト)、
+文字列の説明として使う場合には "null\-terminated" (ヌル終端された) と記載すべきである。 "NUL\-terminated"
+の使用は避けること。
+.SS ハイパーリンク
+ハイパーリンクについては、 \fI.UR\fP/\fI.UE\fP マクロの組を使うこと (\fBgroff_man\fP(7)
+参照)。ページを以下のようにレンダリングする場合に、このマクロはウェブブラウザーで使用できる正しいハイパーリンクを生成してくれる。
+
+ BROWSER=firefox man \-H pagename
+.SS "e.g., i.e., etc., a.k.a. などの使用"
+一般的には、 "e.g.", "i.e.", "etc.", "a.k.a." などの省略形の使用は避けるべきである。 代わりに完全な形の単語を使うこと
+("for example" (例えば), "that is" (つまり), "and so on" (〜など), "also known as"
+(別名))。
+
+これらの省略形の使用が認められる唯一の場所は、 \fI短い\fP括弧で囲まれた余談 ("(e.g., like this one)") の場合である。
+
+ここで記載しているように、これらの省略形では必ずピリオドを入れること。 また、"e.g." と "i.e." では常に後にカンマも付けること。
+.SS "em によるダッシュ"
+*roff で em によるダッシュ\(emこの部分の両端にある記号\(emを書くには "\e(em" を使う。 (ASCII 端末では em
+によるダッシュは通常ハイフン 2 つとして表示されるが、別の活版印刷の場合などでは長いダッシュとして表示されることもある。) em
+によるダッシュの両側にはスペースを\fI置かないこと\fP。
+.SS 修飾子としての複合語におけるハイフン
+何かを修飾する際 (すなわち後続の名詞を限定する場合) 複合語にはハイフンを入れること。いくつか例を挙げる。
+
+ 32\-bit value (32 ビット値)
+ command\-line argument (コマンドライン引き数)
+ floating\-point number (浮動小数点数)
+ run\-time check (実行時チェック)
+ user\-space function (ユーザー空間関数)
+ wide\-character string (ワイド文字の文字列)
+.SS "multi, non, pre, re, sub などとの組み合わせでのハイフン"
+一般的に最近の英語の傾向では、"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" は異なる別の動詞である点に注意すること。たいていの場合、使おうと思っているのは前者であろう。
+.SS 本当のマイナス文字
+本当の意味でのマイナス文字が必要な場合は (\-1 といった数字や \fIls\ \-l\fP
+といった先頭にダッシュのオプションを記載する場合など)、マニュアルページの原文では以下の表記を使うこと。
+
+ \e\-
+
+このガイドラインはサンプルコードの場合にも適用される。
+.SS 文字定数
+ASCII と UTF\-8 の両方で正しくレンダリングされるシングルクォート (一重引用符)
+を生成するには、マニュアルページの原文では以下の表記を使うこと。
+
+ \e(aqC\e(aq
+
+ここで \fIC\fP が括弧で囲まれる文字である。このガイドラインはサンプルコードの場合にも適用される。
.SS サンプルプログラムとシェルのセッション
マニュアルページには、システムコールやライブラリ関数の使い方を示す サンプルプログラムを含めることができる。 その際には、以下の点に留意すべきである。
-.TP 3
-*
+.IP * 3
サンプルプログラムは C で記載すること。
-.TP
-*
+.IP *
サンプルプログラムは、 インタフェースについて文章で簡単に説明できる以上のことを示す場合にだけ
必要かつ有用である。インタフェースを呼び出す以外に何もしないサンプル プログラムは普通はほとんど役に立たない。
-.TP
-*
+.IP *
サンプルプログラムはかなり短めにすること (100行未満が望ましく、50行未満が理想的である)。
-.TP
-*
+.IP *
サンプルプログラムでは、システムコールやライブラリ関数を呼び出した後で エラーチェックを行うこと。
-.TP
-*
+.IP *
サンプルプログラムは完結していて、 \fIcc\ \-Wall\fP でコンパイルした際に警告なしでコンパイルできること。
-.TP
-*
+.IP *
可能かつ適切な場合には、サンプルプログラムで 入力により動作を変化させるなどの実験を行うとよい
(理想的には、コマンドライン引き数や、プログラムが読み込む入力データ 経由で、動作を変化させるのがよい)。
-.TP
-*
+.IP *
サンプルプログラムは、K&R (Kernighan and Ritchie) スタイルで書き、 字下げはスペース 4文字で行う。 (ソースコードで
TAB 文字を使うのは避けること。)
+.IP *
+一貫性を保つため、すべてのサンプルプログラムは以下のいずれかで終了すること。
+
+ exit(EXIT_SUCCESS);
+ exit(EXIT_FAILURE);
+
+プログラムを終了するのに以下を使うのは避けること。
+
+ exit(0);
+ exit(1);
+ return n;
+.IP *
+プログラムソースの前に説明文がある場合は、\fIプログラムソース\fPの見出しをソースコードの前に付けること。
+
+\&.SS プログラムのソース
+
+説明文がシェルセッションのログを含む場合は必ずこのようにすること。
+.PP
+プログラムの使い方や他のシステムの特徴を示すためにシェルのセッションログを含める場合、
+.IP * 3
+セッションログをソースコードの前に置くこと
+.IP *
+セッションログをスペース 4 つで字下げすること
+.IP *
+ユーザの入力文をボールドにして、システムが生成する出力と区別できるようにすること
.PP
サンプルプログラムがどんな風になっていればよいかの例については、 \fBwait\fP(2) と \fBpipe\fP(2) を参照すること。
-
-プログラムの使い方や他のシステムの特徴を示すためにシェルのセッション例 を含める場合、ユーザの入力文をボールドにして、システムが生成する
-出力と区別できるようにすること。
-.SS 構造体の定義、シェルのセッションログなどの字下げ
-構造体の定義やシェルのセッションログなどを本文中に記載する際は、 スペース 4個分の字下げを行う (つまり、ブロックを \fI.in\ +4n\fP と
-\&\fI.in\fP で囲む)。
.SH 例
\fIman\-pages\fP パッケージに含まれるマニュアルページの体裁の標準的な例については、 \fBpipe\fP(2) と \fBfcntl\fP(2)
を参照すること。
\fBman\fP(1), \fBman2html\fP(1), \fBgroff\fP(7), \fBgroff_man\fP(7), \fBman\fP(7),
\fBmdoc\fP(7)
.SH この文書について
-この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.53 の一部
+この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.65 の一部
である。プロジェクトの説明とバグ報告に関する情報は
http://www.kernel.org/doc/man\-pages/ に書かれている。
OSDN Git Service
