.\" 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\-03\-16 Linux "Linux Programmer's Manual"
+.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 説明
このページでは、 Linux \fIman\-pages\fP プロジェクトのマニュアルページを書く際に 従うべき決まり事について説明する。 Linux
-\fIman\-pages\fP プロジェクトは Linux カーネルおよび GNU C ライブラリが提供するユーザ空間 API
+\fIman\-pages\fP プロジェクトは Linux カーネルおよび GNU C ライブラリが提供するユーザー空間 API
のドキュメント作成を行っている。Linux システムのマニュアルページのセクション 2 のページのほとんどと、セクション 3, 4, 5, 7
の多くのページが、このプロジェクトにより提供されている。このページで説明されている決まり事は、他のプロジェクトの
マニュアルページを書く作者にも役立つことだろう。
マニュアルのセクションは、習慣的に以下のような定義が用いられている:
.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
コマンド、関数、システムコールの出自。
以下のリストでは、上記のセクションのそれぞれの内容について 詳しく説明する。
.TP 14
\fB名前 (NAME)\fP
-マニュアルページの名前。 \fB.SH NAME\fP コマンドの後に続ける行の重要な情報については \fBman\fP(7) を参照。この行のすべての単語は
-("\e\-" の直後の単語も含め) 小文字にすべきである。但し、英語や技術用語の慣例として別の記載をする場合はこの限りではない。
+このマニュアルページの名前
+
+\&\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).
-ã\83\97ã\83ã\82°ã\83©ã\83 ã\83»é\96¢æ\95°ã\83»ã\83\95ã\82©ã\83¼ã\83\9eã\83\83ã\83\88ã\81®å\8b\95ä½\9cã\83»ç\9b®ç\9a\84ã\82\92説æ\98\8eã\81\99ã\82\8bã\80\82 ã\83\95ã\82¡ã\82¤ã\83«ã\82\84æ¨\99æº\96å\85¥å\8a\9bã\82\92ã\81©ã\81®ã\82\88ã\81\86ã\81«å\87¦ç\90\86ã\81\97ã\80\81æ¨\99æº\96å\87ºå\8a\9bã\82\84æ¨\99æº\96ã\82¨ã\83©ã\83¼å\87ºå\8a\9bã\82\92
-どのように生成するかといったことについて述べる。 内部動作や実装の詳細については省略する (ただしそれが動作の理解にどうしても必要なら別)。
-通常の場合について記述する。 プログラムのコマンドライン・オプションの説明には、 \fBオプション\fP のセクションを用いる。
+ã\83\95ã\82¡ã\82¤ã\83«ã\82\84æ¨\99æº\96å\85¥å\8a\9bã\82\92ã\81©ã\81®ã\82\88ã\81\86ã\81«å\87¦ç\90\86ã\81\97ã\80\81æ¨\99æº\96å\87ºå\8a\9bã\82\84æ¨\99æº\96ã\82¨ã\83©ã\83¼å\87ºå\8a\9bã\82\92 ã\81©ã\81®ã\82\88ã\81\86ã\81«ç\94\9fæ\88\90ã\81\99ã\82\8bã\81\8bã\81¨ã\81\84ã\81£ã\81\9fã\81\93ã\81¨ã\81«ã\81¤ã\81\84ã\81¦è¿°ã\81¹ã\82\8bã\80\82
+内部動作や実装の詳細については省略する (ただしそれが動作の理解にどうしても必要なら別)。 通常の場合について記述する。
+プログラムのコマンドラインオプションの説明には、 \fBオプション\fP のセクションを用いる。
システムコールやライブラリ関数の新しい動作や新しいフラグについて説明する際は、 変更が取り込まれたカーネルや C
ライブラリのバージョンを注記に入れるように気を付けること。 フラグにこの情報の注記を入れる方法としては、推奨される方法は、 以下のように \fB.TP\fP
フラグの説明...
.RE
.IP
-バージョン情報を入れておくのは、 古いバージョンのカーネルや C ライブラリを使わざるを得ないユーザにとって、 特に有用である
+ã\83\90ã\83¼ã\82¸ã\83§ã\83³æ\83\85å ±ã\82\92å\85¥ã\82\8cã\81¦ã\81\8aã\81\8fã\81®ã\81¯ã\80\81 å\8f¤ã\81\84ã\83\90ã\83¼ã\82¸ã\83§ã\83³ã\81®ã\82«ã\83¼ã\83\8dã\83«ã\82\84 C ã\83©ã\82¤ã\83\96ã\83©ã\83ªã\82\92使ã\82\8fã\81\96ã\82\8bã\82\92å¾\97ã\81ªã\81\84ã\83¦ã\83¼ã\82¶ã\83¼ã\81«ã\81¨ã\81£ã\81¦ã\80\81 ç\89¹ã\81«æ\9c\89ç\94¨ã\81§ã\81\82ã\82\8b
(例えば、組み込みシステムではよくあることである)。
.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
.TP
\fBバージョン (VERSIONS)\fP
システムコールやライブラリ関数が登場したり、動作の重要な変更が行われた、 Linux カーネルや glibc のバージョンについての簡潔な概要。
+
一般に、全ての新しいインターフェイスは、マニュアルページに 「バージョン」の節を設けるべきである。
残念なことに、多くの既存のマニュアルページにこの情報は含まれていない (これらのページが書かれた時点ではそのようなポリシーはなかったからである)。
これを改善するパッチは歓迎されるが、 新しいコードを書くプログラマの観点からすれば、 おそらくこの情報が重要になるのは、 Linux 2.4
\fBsyscalls\fP(2) マニュアルページにも、いろいろなシステムコールが初めて登場した カーネルバージョンについての情報が書かれている。
.TP
\fB準拠 (CONFORMING TO)\fP
-そのマニュアルページで説明している関数やコマンドに関連する 標準規格や慣習について記載する。 様々な標準を示すのに適した用語は
-\fBstandards\fP(7) に見出しでリストになっている。 セクション 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
関連項目のリストに長いマニュアルページ名が多く含まれる場合には、出力を見やすくするために \fI.ad l\fP (右揃えをしない) や \fI.nh\fP
(ハイフンによる折り返しをしない) を活用するとよい。個々のページ名のハイフンによる折り返しは、単語の前に "\e%" を付けることで防ぐことができる。
+
+FOSS プロジェクトやそのドキュメントは本質的に分散して自律的に行われるので、
+「関連項目」セクションに他のプロジェクトが提供するマニュアルページへの参照を含める必要がときとしてあり、多くの場合は含めるのが望ましい場合がある。
.SH スタイルガイド
-The following subsections describe the preferred style for the \fIman\-pages\fP
-project. For details not covered below, the Chicago Manual of Style is
-usually a good source; try also grepping for preexisting usage in the
-project source tree.
-.SS "Use of gender\-neutral language"
-As far as possible, use gender\-neutral language in the text of man pages.
-Use of "they" ("them", "themself", "their") as a gender\-neutral singular
-pronoun is acceptable.
+以下の節では\fIman\-pages\fPプロジェクトで推奨のスタイルについて説明している。 ここで触れられていない点については、"the Chicago
+Manual of Style" がたいていはよい情報源になるだろう。
+また、すでに使用されているスタイルについてはプロジェクトのソースツリーを検索してみてほしい。
+(訳注：この章では英語の原文でのスタイルについて説明しており、日本語マニュアルにはあわない点もあるため、具体例などは英語のままとしている箇所もあります。)
+.SS 性別の区別のない表現の使用
+可能な限り、マニュアルページの文章では性別の区別のない表現を使用すること。 性別に区別のない単数形の代名詞として "they" ("them",
+"themself", "their") を使用してもよい。
.SS フォントの慣習
.PP
関数に対しては、引き数には常にイタリック体を用いる。 「たとえ書式 (SYNOPSIS) セクションであっても、このルールに従う」
.PP
ファイル名 (パス名、またはヘッダーファイルへの参照) は常にイタリック体にする (例: \fI<stdio.h>\fP)。 ただし、書式
(SYNOPSIS) セクションは例外で、 インクルードファイルはボールドにする (例: \fB#include <stdio.h>\fP)。
-æ¨\99æº\96ã\81®ã\82¤ã\83³ã\82¯ã\83«ã\83¼ã\83\89ã\83\98ã\83\83ã\83\80ã\83\95ã\82¡ã\82¤ã\83«ã\82\92å\8f\82ç\85§ã\81\99ã\82\8bé\9a\9bã\81¯ã\80\81 é\80\9a常ã\81® C è¨\80èª\9eã\81¨å\90\8cæ§\98ã\81«å±±æ\8b¬å¼§ã\81§ã\83\98ã\83\83ã\83\80ファイルを囲ぬで指定する (例：
+æ¨\99æº\96ã\81®ã\82¤ã\83³ã\82¯ã\83«ã\83¼ã\83\89ã\83\98ã\83\83ã\83\80ã\83¼ã\83\95ã\82¡ã\82¤ã\83«ã\82\92å\8f\82ç\85§ã\81\99ã\82\8bé\9a\9bã\81¯ã\80\81 é\80\9a常ã\81® C è¨\80èª\9eã\81¨å\90\8cæ§\98ã\81«å±±æ\8b¬å¼§ã\81§ã\83\98ã\83\83ã\83\80ã\83¼ファイルを囲ぬで指定する (例：
\fI<stdio.h>\fP)。
.PP
通常、大文字で表現する特殊マクロはボールドで表す (例えば \fBMAXINT\fP)。 例外として NULL はボールドにしない。
.fi
(相互参照にセクション番号を含めておくと、 \fBman2html\fP といったツールがページ間のハイパーリンクを適切に生成できる。)
-Control characters should be written in bold face, with no quotes; for
-example, \fB^X\fP.
+制御文字は太字で引用符なしで表記すること。 例えば \fB^X\fP。
.SS "綴り (spelling)"
リリース 2.59 からだが、 \fIman\-pages\fP はアメリカ英語の綴りの慣習に従っている
(以前はイギリス英語とアメリカ英語が基準もなく混在して使われていた)。 新しいページやパッチは全てこの慣習に従って下さい。
-Aside from the well\-known spelling differences, there are a few other
-subtleties to watch for:
+よく知られた綴りの違い以外に、微妙な違いもいくつか見られる。
.IP * 3
-American English tends to use the forms "backward", "upward", "toward", and
-so on rather than the British forms "backwards", "upwards", "towards", and
-so on.
-.SS "BSD version numbers"
-The classical scheme for writing BSD version numbers is \fIx.yBSD\fP, where
-\fIx.y\fP is the version number (e.g., 4.2BSD). Avoid forms such as \fIBSD
-4.3\fP.
+アメリカ英語では "backward", "upward", "toward" を使う傾向にあるが、イギリス英語では "backwards",
+"upwards", "towards" などを使う方が多い。
+.SS "BSD バージョン番号"
+BSD バージョン番号の伝統的な表記方法は \fIx.yBSD\fP である (\fIx.y\fP はバージョン番号; 例: 4.2BSD)。 \fIBSD 4.3\fP
+といった表記は避けること。
.SS 大文字表記
サブセクション ("SS") 見出しでは、最初の単語だけ先頭文字を大文字にし、残りの単語は小文字にすること。但し、英語の用法 (例えば、固有名詞)
やプログラミング言語の要件 (例えば、識別子の名前) などで別の表記をする場合はこの限りではない。
.SS 構造体の定義、シェルのセッションログなどの字下げ、など
構造体の定義やシェルのセッションログなどを本文中に記載する際は、 スペース 4個分の字下げを行う (つまり、ブロックを \fI.in\ +4n\fP と
\&\fI.in\fP で囲む)。
-.SS "Preferred terms"
-The following table lists some preferred terms to use in man pages, mainly
-to ensure consistency across pages.
+.SS 推奨用語
+以下の表にマニュアルページでの使用が推奨される用語を示す。これらは主にマニュアルページ間での一貫性を保つためである。
.TS
l l l
---
zeros zeroes
.TE
.PP
-See also the discussion \fIHyphenation of attributive compounds\fP below.
-.SS "Terms to avoid"
-The following table lists some terms to avoid using in man pages, along with
-some suggested alternatives, mainly to ensure consistency across pages.
+以下の\fI修飾子としての複合語におけるハイフン\fPの議論も参照。
+.SS 使用を避ける用語
+以下の表にマニュアルページでの使用を避けるべき用語を示す。 推奨される表現も合わせて記載している。
+これらは主にマニュアルページ間での一貫性を保つためである。
.TS
l l l
---
l l l.
-Avoid Use instead Notes
+使用を避ける 使用を推奨 備考
32bit 32\-bit T{
-same for 8\-bit, 16\-bit, etc.
+8\-bit, 16\-bit なども同様
T}
current process calling process T{
-A common mistake made by kernel programmers when writing man pages
+カーネルプログラマーがマニュアルページを書く際によくする間違い
T}
manpage T{
man page, manual page
Unixes UNIX systems
.TE
.SS 商標
-Use the correct spelling and case for trademarks. The following is a list
-of the correct spellings of various relevant trademarks that are sometimes
-misspelled:
+商標については正しい綴りと大文字小文字を使うこと。以下は時々綴りの間違いがある商標の正しい綴りのリストである。
DG/UX
HP\-UX
UNIX
UnixWare
-.SS "NULL, NUL, null pointer, and null character"
-A \fInull pointer\fP is a pointer that points to nothing, and is normally
-indicated by the constant \fINULL\fP. On the other hand, \fINUL\fP is the \fInull
-byte\fP, a byte with the value 0, represented in C via the character constant
-\fI\(aq\e0\(aq\fP.
-
-The preferred term for the pointer is "null pointer" or simply "NULL"; avoid
-writing "NULL pointer".
-
-The preferred term for the byte is "null byte". Avoid writing "NUL", since
-it is too easily confused with "NULL". Avoid also the terms "zero byte" and
-"null character". The byte that terminates a C string should be described
-as "the terminating null byte"; strings may be described as
-"null\-terminated", but avoid the use of "NUL\-terminated".
+.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 ハイパーリンク
-For hyperlinks, use the \fI.UR\fP/\fI.UE\fP macro pair (see \fBgroff_man\fP(7)).
-This produces proper hyperlinks that can be used in a web browser, when
-rendering a page with, say:
+ハイパーリンクについては、 \fI.UR\fP/\fI.UE\fP マクロの組を使うこと (\fBgroff_man\fP(7)
+参照)。ページを以下のようにレンダリングする場合に、このマクロはウェブブラウザーで使用できる正しいハイパーリンクを生成してくれる。
BROWSER=firefox man \-H pagename
-.SS "Use of e.g., i.e., etc., a.k.a., and similar"
-In general, the use of abbreviations such as "e.g.", "i.e.", "etc.",
-"a.k.a." should be avoided, in favor of suitable full wordings ("for
-example", "that is", "and so on", "also known as").
-
-The only place where such abbreviations may be acceptable is in \fIshort\fP
-parenthetical asides (e.g., like this one).
-
-Always include periods in such abbreviations, as shown here. In addition,
-"e.g." and "i.e." should always be followed by a comma.
-.SS Em\-dashes
-The way to write an em\-dash\(emthe glyph that appears at either end of this
-subphrase\(emin *roff is with the macro "\e(em". (On an ASCII terminal, an
-em\-dash typically renders as two hyphens, but in other typographical
-contexts it renders as a long dash.) Em\-dashes should be written \fIwithout\fP
-surrounding spaces.
-.SS "Hyphenation of attributive compounds"
-Compound terms should be hyphenated when used attributively (i.e., to
-qualify a following noun). Some examples:
-
- 32\-bit value
- command\-line argument
- floating\-point number
- run\-time check
- user\-space function
- wide\-character string
-.SS "Hyphenation with multi, non, pre, re, sub, and so on"
-The general tendency in modern English is not to hyphenate after prefixes
-such as "multi", "non", "pre", "re", "sub", and so on. Manual pages should
-generally follow this rule when these prefixes are used in natural English
-constructions with simple suffixes. The following list gives some examples
-of the preferred forms:
+.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
subdirectory
subsystem
-Hyphens should be retained when the prefixes are used in nonstandard English
-words, with trademarks, proper nouns, acronyms, or compound terms. Some
-examples:
+接尾語が通常の英単語以外 (商標、固有名詞、頭字語、複合語) と組み合わされる場合は、ハイフンを使うこと。以下に例を挙げる。
non\-ASCII
non\-English
non\-NULL
non\-real\-time
-Finally, note that "re\-create" and "recreate" are two different verbs, and
-the former is probably what you want.
-.SS "Real minus character"
-Where a real minus character is required (e.g., for numbers such as \-1, or
-when writing options that have a leading dash, such as in \fIls\ \-l\fP), use
-the following form in the man page source:
+最後に、"re\-create" と "recreate" は異なる別の動詞である点に注意すること。たいていの場合、使おうと思っているのは前者であろう。
+.SS 本当のマイナス文字
+本当の意味でのマイナス文字が必要な場合は (\-1 といった数字や \fIls\ \-l\fP
+といった先頭にダッシュのオプションを記載する場合など)、マニュアルページの原文では以下の表記を使うこと。
\e\-
-This guideline applies also to code examples.
-.SS "Character constants"
-To produce single quotes that render well in both ASCII and UTF\-8, use the
-following form for character constants in the man page source:
+このガイドラインはサンプルコードの場合にも適用される。
+.SS 文字定数
+ASCII と UTF\-8 の両方で正しくレンダリングされるシングルクォート (一重引用符)
+を生成するには、マニュアルページの原文では以下の表記を使うこと。
\e(aqC\e(aq
-where \fIC\fP is the quoted character. This guideline applies also to
-character constants used in code examples.
+ここで \fIC\fP が括弧で囲まれる文字である。このガイドラインはサンプルコードの場合にも適用される。
.SS サンプルプログラムとシェルのセッション
マニュアルページには、システムコールやライブラリ関数の使い方を示す サンプルプログラムを含めることができる。 その際には、以下の点に留意すべきである。
.IP * 3
サンプルプログラムは C で記載すること。
.IP *
-サンプルプログラムは、 インタフェースについて文章で簡単に説明できる以上のことを示す場合にだけ
-必要かつ有用である。インタフェースを呼び出す以外に何もしないサンプル プログラムは普通はほとんど役に立たない。
+ã\82µã\83³ã\83\97ã\83«ã\83\97ã\83ã\82°ã\83©ã\83 ã\81¯ã\80\81 ã\82¤ã\83³ã\82¿ã\83¼ã\83\95ã\82§ã\83¼ã\82¹ã\81«ã\81¤ã\81\84ã\81¦æ\96\87ç« ã\81§ç°¡å\8d\98ã\81«èª¬æ\98\8eã\81§ã\81\8dã\82\8b以ä¸\8aã\81®ã\81\93ã\81¨ã\82\92示ã\81\99å ´å\90\88ã\81«ã\81 ã\81\91
+å¿\85è¦\81ã\81\8bã\81¤æ\9c\89ç\94¨ã\81§ã\81\82ã\82\8bã\80\82ã\82¤ã\83³ã\82¿ã\83¼ã\83\95ã\82§ã\83¼ã\82¹ã\82\92å\91¼ã\81³å\87ºã\81\99以å¤\96ã\81«ä½\95ã\82\82ã\81\97ã\81ªã\81\84ã\82µã\83³ã\83\97ã\83« ã\83\97ã\83ã\82°ã\83©ã\83 ã\81¯æ\99®é\80\9aã\81¯ã\81»ã\81¨ã\82\93ã\81©å½¹ã\81«ç«\8bã\81\9fã\81ªã\81\84ã\80\82
.IP *
サンプルプログラムはかなり短めにすること (100行未満が望ましく、50行未満が理想的である)。
.IP *
サンプルプログラムは、K&R (Kernighan and Ritchie) スタイルで書き、 字下げはスペース 4文字で行う。 (ソースコードで
TAB 文字を使うのは避けること。)
.IP *
-For consistency, all example programs should terminate using either of:
+一貫性を保つため、すべてのサンプルプログラムは以下のいずれかで終了すること。
exit(EXIT_SUCCESS);
exit(EXIT_FAILURE);
-Avoid using the following forms to terminate a program:
+プログラムを終了するのに以下を使うのは避けること。
exit(0);
exit(1);
return n;
.IP *
-If there is extensive explanatory text before the program source code, mark
-off the source code with a susbsection heading \fIProgram source\fP, as in:
+プログラムソースの前に説明文がある場合は、\fIプログラムソース\fPの見出しをソースコードの前に付けること。
\&.SS プログラムのソース
-Always do this if the explanatory text includes a shell session log.
+説明文がシェルセッションのログを含む場合は必ずこのようにすること。
.PP
プログラムの使い方や他のシステムの特徴を示すためにシェルのセッションログを含める場合、
.IP * 3
.IP *
セッションログをスペース 4 つで字下げすること
.IP *
-ユーザの入力文をボールドにして、システムが生成する出力と区別できるようにすること
+ã\83¦ã\83¼ã\82¶ã\83¼ã\81®å\85¥å\8a\9bæ\96\87ã\82\92ã\83\9cã\83¼ã\83«ã\83\89ã\81«ã\81\97ã\81¦ã\80\81ã\82·ã\82¹ã\83\86ã\83 ã\81\8cç\94\9fæ\88\90ã\81\99ã\82\8bå\87ºå\8a\9bã\81¨å\8cºå\88¥ã\81§ã\81\8dã\82\8bã\82\88ã\81\86ã\81«ã\81\99ã\82\8bã\81\93ã\81¨
.PP
サンプルプログラムがどんな風になっていればよいかの例については、 \fBwait\fP(2) と \fBpipe\fP(2) を参照すること。
.SH 例
\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.65 の一部
+この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.78 の一部
である。プロジェクトの説明とバグ報告に関する情報は
http://www.kernel.org/doc/man\-pages/ に書かれている。
OSDN Git Service
