.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
-.TH MAN\-PAGES 7 2013\-02\-24 Linux "Linux Programmer's Manual"
+.\"
+.\" Japanese Version Copyright (c) 2007 Akihiro MOTOKI
+.\" all rights reserved.
+.\" Translated 2007-06-13, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.54
+.\" Updated 2007-07-04, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.59
+.\" Updated 2007-09-03, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.64
+.\" 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 2014\-12\-31 Linux "Linux Programmer's Manual"
.SH 名前
man\-pages \- Linux の man ページを書く際の決まり事
.SH 書式
\fBman\fP [\fIsection\fP] \fItitle\fP
.SH 説明
-This page describes the conventions that should be employed when writing man
-pages for the Linux \fIman\-pages\fP project, which documents the user\-space API
-provided by the Linux kernel and the GNU C library. The project thus
-provides most of the pages in Section 2, as well as many of the pages that
-appear in Sections 3, 4, 5, and 7 of the man pages on a Linux system. The
-conventions described on this page may also be useful for authors writing
-man pages for other projects.
+このページでは、 Linux \fIman\-pages\fP プロジェクトのマニュアルページを書く際に 従うべき決まり事について説明する。 Linux
+\fIman\-pages\fP プロジェクトは Linux カーネルおよび GNU C ライブラリが提供するユーザー空間 API
+のドキュメント作成を行っている。Linux システムのマニュアルページのセクション 2 のページのほとんどと、セクション 3, 4, 5, 7
+の多くのページが、このプロジェクトにより提供されている。このページで説明されている決まり事は、他のプロジェクトの
+マニュアルページを書く作者にも役立つことだろう。
.SS マニュアルページのセクション
.PP
マニュアルのセクションは、習慣的に以下のような定義が用いられている:
.TP 10
\fB1 コマンド (プログラム)\fP
-シェルの中からユーザが実行できるコマンド。
+ã\82·ã\82§ã\83«ã\81®ä¸ã\81\8bã\82\89ã\83¦ã\83¼ã\82¶ã\83¼ã\81\8cå®\9fè¡\8cã\81§ã\81\8dã\82\8bã\82³ã\83\9eã\83³ã\83\89ã\80\82
.TP
\fB2 システムコール\fP
カーネルが処理しなければならない関数。
man ページが属するセクション番号 (例: \fI7\fP)。
.TP
\fIdate\fP
-最新のリビジョンの日付\(emman ページに変更を加えたときには 必ずこれを変更すること。 これが最も一般的なバージョン管理方法である。 日付は
-YYYY\-MM\-DD の形式で記載すべきである。
+man ページに最後に些細でない変更が行われた日付。 (\fIman\-pages\fP プロジェクトでは、
+このタイムスタンプの必要な更新はスクリプトで自動的に行われるので、 パッチの中でこの日付を手動で更新する必要はない。) 日付は YYYY\-MM\-DD
+形式で記載すること。
.TP
\fIsource\fP
コマンド、関数、システムコールの出自。
環境変数
ファイル
バージョン [通常はセクション 2, 3 のみ]
+属性 [通常はセクション 2, 3 のみ]
準拠
注意/備考
バグ
以下のリストでは、上記のセクションのそれぞれの内容について 詳しく説明する。
.TP 14
\fB名前 (NAME)\fP
-The name of this manual page. See \fBman\fP(7) for important details of the
-line(s) that should follow the \fB.SH NAME\fP command. All words in this line
-(including the word immediately following the "\e\-") should be in lowercase,
-except where English or technical terminological convention dictates
-otherwise.
+このマニュアルページの名前
+
+\&\fB.SH NAME\fP コマンドの後に続ける行の重要な情報については \fBman\fP(7) を参照。この行のすべての単語は ("\e\-"
+の直後の単語も含め) 小文字にすべきである。但し、英語や技術用語の慣例として別の記載をする場合はこの限りではない。
.TP
\fB書式 (SYNOPSIS)\fP
-コマンドや関数のインターフェースを簡潔に記述する。 コマンドに対しては、コマンドや引き数 (オプション) の文法を書く。
-そのまま書くテキストにはボールド体を用い、置き換える引き数には イタリック体を用いる。省略可能なオプションはブラケット ([]) で囲い、 選択肢は縦棒
-(|) で区切り、繰り返しには省略符号 (...) を書く。 関数に対しては、必要なデータ宣言や \fB#include\fP 指定を書き、関数宣言を続ける。
+コマンドや関数インターフェースの簡潔な概要
+
+コマンドに対しては、コマンドや引き数 (オプション) の文法を書く。 そのまま書くテキストにはボールド体を用い、置き換える引き数には
+イタリック体を用いる。省略可能なオプションはブラケット ([]) で囲い、 選択肢は縦棒 (|) で区切り、繰り返しには省略符号 (...) を書く。
+関数に対しては、必要なデータ宣言や \fB#include\fP 指定を書き、関数宣言を続ける。
.\" FIXME . Say something here about compiler options
-ヘッダファイルから関数 (や変数) の定義を得るために 機能検査マクロ (feature test macro) を定義しなければならない場合、 書式
+ã\83\98ã\83\83ã\83\80ã\83¼ã\83\95ã\82¡ã\82¤ã\83«ã\81\8bã\82\89é\96¢æ\95° (ã\82\84å¤\89æ\95°) ã\81®å®\9a義ã\82\92å¾\97ã\82\8bã\81\9fã\82\81ã\81« æ©\9fè\83½æ¤\9cæ\9f»ã\83\9eã\82¯ã\83 (feature test macro) ã\82\92å®\9a義ã\81\97ã\81ªã\81\91ã\82\8cã\81°ã\81ªã\82\89ã\81ªã\81\84å ´å\90\88ã\80\81 æ\9b¸å¼\8f
(SYNOPSIS) に必要な機能検査マクロを記載すべきである。 機能検査マクロについては \fBfeature_test_macros\fP(7)
で説明されている。
.TP
\fBCONFIGURATION\fP
-デバイスの設定詳細。 通常、このセクションは 4 章のマニュアルページでのみ登場する。
+デバイスの設定詳細。
+
+通常、このセクションは 4 章のマニュアルページでのみ登場する。
.TP
\fB説明 (DESCRIPTION)\fP
+プログラム・関数・フォーマットの動作・目的。
+
.\" If there is some kind of input grammar or complex set of subcommands,
.\" consider describing them in a separate
.\" .B USAGE
.\" section (and just place an overview in the
.\" .B DESCRIPTION
.\" section).
-プログラム・関数・フォーマットの動作・目的を説明する。 ファイルや標準入力をどのように処理し、標準出力や標準エラー出力を
-どのように生成するかといったことについて述べる。 内部動作や実装の詳細については省略する (ただしそれが動作の理解にどうしても必要なら別)。
-通常の場合について記述する。 プログラムのコマンドライン・オプションの説明には、 \fBオプション\fP のセクションを用いる。
+ファイルや標準入力をどのように処理し、標準出力や標準エラー出力を どのように生成するかといったことについて述べる。
+内部動作や実装の詳細については省略する (ただしそれが動作の理解にどうしても必要なら別)。 通常の場合について記述する。
+プログラムのコマンドラインオプションの説明には、 \fBオプション\fP のセクションを用いる。
+
+システムコールやライブラリ関数の新しい動作や新しいフラグについて説明する際は、 変更が取り込まれたカーネルや C
+ライブラリのバージョンを注記に入れるように気を付けること。 フラグにこの情報の注記を入れる方法としては、推奨される方法は、 以下のように \fB.TP\fP
+リストの一部にすることである (この例はシステムコールの新しいフラグの場合)。
+.RS 22
+.TP
+ \fBXYZ_FLAG\fP (Linux 3.7 以降)
+フラグの説明...
+.RE
+.IP
+バージョン情報を入れておくのは、 古いバージョンのカーネルや C ライブラリを使わざるを得ないユーザーにとって、 特に有用である
+(例えば、組み込みシステムではよくあることである)。
.TP
\fBオプション (OPTIONS)\fP
+プログラムが受け付けるコマンドラインオプションとその場合プログラムの振舞いがどう変わるかの説明。
+
.\" .TP
.\" .B USAGE
.\" describes the grammar of any sublanguage this implements.
-プログラムが受け付けるコマンドライン・オプションと、 その場合プログラムの振舞いがどう変わるかを説明する。 このセクションはセクション 1 と 8
-のマニュアルページにだけ登場すべきである。
+このセクションはセクション 1 と 8 のマニュアルページにだけ登場すべきである。
.TP
\fB終了ステータス (EXIT STATUS)\fP
-プログラムの終了ステータスの値と、それらの値に対応する状況を列挙する。 このセクションはセクション 1 と 8
-のマニュアルページにだけ登場すべきである。
+プログラムの終了ステータスの値とそれらの値に対応する状況の一覧。
+
+このセクションはセクション 1 と 8 のマニュアルページにだけ登場すべきである。
.TP
\fB返り値 (RETURN VALUE)\fP
セクション 2 と 3 のページの場合、このセクションに ライブラリルーチンが呼び出し元に返す値のリストを記載する。
.TP
\fBエラー (ERRORS)\fP
セクション 2 と 3 のマニュアルページでは、 エラーが発生した場合に \fIerrno\fP に設定される可能性がある値のリストを記載する。
-リストには、エラーの値とエラーの原因についての情報を書く。 「エラーリストはアルファベット順にすべきである。」
+リストには、エラーの値とエラーの原因についての情報を書く。
+
+「エラーリストはアルファベット順にすべきである。」
.TP
\fB環境変数 (ENVIRONMENT)\fP
-ã\83\97ã\83ã\82°ã\83©ã\83 ã\82\84é\96¢æ\95°ã\81«å½±é\9f¿ã\81\99ã\82\8bç\92°å¢\83å¤\89æ\95°ã\82\92ã\83ªã\82¹ã\83\88ã\81\97ã\80\81ã\81\9dã\82\8cã\82\89ã\81®å\8a¹æ\9e\9cã\82\92æ\9b¸ã\81\8f。
+ã\83\97ã\83ã\82°ã\83©ã\83 ã\82\84é\96¢æ\95°ã\81«å½±é\9f¿ã\81\99ã\82\8bç\92°å¢\83å¤\89æ\95°ã\81®ä¸\80覧ã\81¨ã\80\81ã\81\9dã\82\8cã\82\89ã\81®å½±é\9f¿ã\81®èª¬æ\98\8e。
.TP
\fBファイル (FILES)\fP
+プログラムや関数が用いるファイルの一覧。 設定ファイル、起動ファイル、プログラムが直接操作するファイルなど。
+
.\" May 07: Almost no current man pages have a DIAGNOSTICS section;
.\" "RETURN VALUE" or "EXIT STATUS" is preferred.
.\" .TP
.\" .B USAGE
.\" section).
.\" However, please include security information somewhere!
-プログラムや関数が用いるファイルを列記する。 例えば、設定ファイル、起動ファイル、プログラムが直接操作するファイルなどである。
これらのファイルのファイル名はフルパスで記載し、 ディレクトリの部分はユーザーの好みに合わせて インストール処理で変更できるようにする。
多くのプログラムではデフォルトのインストール先は \fI/usr/local\fP である。したがってベースとなるマニュアルページでも
\fI/usr/local\fP が使われていることが多いだろう。
.TP
+\fB属性 (ATTRIBUTES)\fP
+そのページで説明している関数の種々の属性の概要を、サブセクションに分けて説明する。
+
+以下のサブセクションが定義されている。
+.sp
+.RS
+.TP
+\fBマルチスレッディング (pthreads(7) 参照)\fP
+このサブセクションでは、マルチスレッドアプリケーションに関連する属性について説明する。
+.RS
+.IP * 3
+その関数がスレッドセーフかどうか。
+.IP *
+その関数が取り消しポイント (cancellation point) かどうか。
+.IP *
+その関数が非同期で安全にキャンセルできるか (async\-cancel\-safe かどうか)。
+.RE
+.IP
+これらの属性の詳細は \fBpthreads\fP(7) で説明されている。
+.RE
+.TP
\fBバージョン (VERSIONS)\fP
システムコールやライブラリ関数が登場したり、動作の重要な変更が行われた、 Linux カーネルや glibc のバージョンについての簡潔な概要。
+
一般に、全ての新しいインターフェイスは、マニュアルページに 「バージョン」の節を設けるべきである。
残念なことに、多くの既存のマニュアルページにこの情報は含まれていない (これらのページが書かれた時点ではそのようなポリシーはなかったからである)。
これを改善するパッチは歓迎されるが、 新しいコードを書くプログラマの観点からすれば、 おそらくこの情報が重要になるのは、 Linux 2.4
\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 の現行バージョンで規定されていない場合以外は、
+あまり深く気にする必要はない。)
そのコールがどの標準にも基づいていないが、 他のシステムで広く存在する場合は、その旨を記載すること。 そのコールが Linux
固有の場合は、その旨を記載すること。
(そうなっているページが多いが) このセクションの内容が標準のリスト だけの場合、リストの最後にピリオド (\(aq.\(aq) を置くこと。
.TP
\fB注意 (NOTES)\fP
-その他の注意点を書く。 セクション 2 と 3 のマニュアルページでは、 \fILinux での注意 (Linux Notes)\fP や \fIglibc
-での注意 (Glibc Notes)\fP という名前のサブセクション (\fBSS\fP) を設けると便利なこともある。
+その他の注記。
+
+セクション 2 と 3 のマニュアルページでは、 \fILinux での注意 (Linux Notes)\fP や \fIglibc での注意 (Glibc
+Notes)\fP という名前のサブセクション (\fBSS\fP) を設けると便利なこともある。
+
+セクション 2 では、 システムコールに対する C
+ライブラリのラッパー関数とカーネルが提供する素のシステムコールのインターフェースの間で違いがある場合に、その違いを説明する注記を記載する際には \fIC
+ライブラリとカーネル ABI の違い\fP という見出しを使うこと。
.TP
\fBバグ (BUGS)\fP
-å\88¶é\99\90ã\83»ç\9f¥ã\82\89ã\82\8cã\81¦ã\81\84ã\82\8bæ¬ é\99¥ã\82\84ä¸\8d便ã\81ªç\82¹ã\80\81ã\81\9dã\81®ä»\96ä¸\8dæ\80\9dè°ã\81ªå\8b\95ä½\9cã\81ªã\81©ã\82\92æ\9b¸ã\81\8f。
+å\88¶é\99\90ã\80\81ç\9f¥ã\82\89ã\82\8cã\81¦ã\81\84ã\82\8bæ¬ é\99¥ã\82\84ä¸\8d便ã\81ªç\82¹ã\80\81ã\81\9dã\81®ä»\96ä¸\8dæ\80\9dè°ã\81ªå\8b\95ä½\9cã\81ªã\81©。
.TP
\fB例 (EXAMPLE)\fP
-この関数・ファイル・コマンドをどのように使うかを示した ひとつまたは複数の例を記述する。 サンプルプログラムを書く際の詳細は
-以下の「サンプルプログラム」の節を参照のこと。
+この関数、ファイル、コマンドをどのように使うかを示す、1〜2 個の例。
+
+サンプルプログラムを書く際の詳細は 以下の「サンプルプログラム」の節を参照のこと。
.TP
\fB著者 (AUTHORS)\fP
-文書またはプログラムの著者を列記する。 \fB著者セクションは極力使用しないこと。\fP 一般的には、著者のリストを各ページに撒き散らさない方がよい
+文書やプログラムの著者の一覧。
+
+\fB著者セクションは極力使用しないこと。\fP 一般的には、著者のリストを各ページに撒き散らさない方がよい
(時間がたつと、作者のリストは膨大になる可能性がある)。 マニュアルページを新規に書いたり、大幅に修正を行った場合には、
ソースファイルにコメントとして著作権表示を追加すること。 あなたがデバイスドライバの作者で、バグを報告するためのアドレスを
載せたい場合は、「バグ」セクションの後ろにこのセクションを配置すること。
.TP
\fB関連項目 (SEE ALSO)\fP
-関連するマニュアルページを、コンマ区切りのリストで、 セクション番号順に、セクション内ではアルファベット順で記載する。 可能なら関連する他の文書も書く。
-慣習では、このセクションは最後に置く。 リストの末尾にピリオドを置かないこと。
+関連するマニュアルページのコンマ区切りのリスト。 可能なら関連する他の文書も書く。
+
+リストは、 セクション番号順に、セクション内ではアルファベット順で記載する。 このリストの末尾にピリオドを置かないこと。
.IP
-Where the SEE ALSO list contains many long manual page names, to improve the
-visual result of the output, it may be useful to employ the \fI.ad l\fP (don't
-right justify) and \fI.nh\fP (don't hyphenate) directives. Hyphenation of
-individual page names can be prevented by preceding words with the string
-"\e%".
+関連項目のリストに長いマニュアルページ名が多く含まれる場合には、出力を見やすくするために \fI.ad l\fP (右揃えをしない) や \fI.nh\fP
+(ハイフンによる折り返しをしない) を活用するとよい。個々のページ名のハイフンによる折り返しは、単語の前に "\e%" を付けることで防ぐことができる。
+
+FOSS プロジェクトやそのドキュメントは本質的に分散して自律的に行われるので、
+「関連項目」セクションに他のプロジェクトが提供するマニュアルページへの参照を含める必要がときとしてあり、多くの場合は含めるのが望ましい場合がある。
+.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 はアメリカ英語の綴りの慣習に従っている。 新しいページやパッチは全てこの慣習に従って下さい。
-.SS Capitalization
-In subsection ("SS") headings capitalize the first word in heading, but
-otherwise use lower case, except where English usage (e.g., proper nouns) or
-programming language requirements (e.g., identifier names) dictate
-otherwise.
+リリース 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
-*
-サンプルプログラムは、 インタフェースについて文章で簡単に説明できる以上のことを示す場合にだけ
-必要かつ有用である。インタフェースを呼び出す以外に何もしないサンプル プログラムは普通はほとんど役に立たない。
-.TP
-*
+.IP *
+サンプルプログラムは、 インターフェースについて文章で簡単に説明できる以上のことを示す場合にだけ
+必要かつ有用である。インターフェースを呼び出す以外に何もしないサンプル プログラムは普通はほとんど役に立たない。
+.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.50 の一部
+この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.78 の一部
である。プロジェクトの説明とバグ報告に関する情報は
http://www.kernel.org/doc/man\-pages/ に書かれている。
OSDN Git Service
