(split) LDP: Addresses fuzzy strings in 3.53

[linuxjm/LDP_man-pages.git] / draft / man7 / man-pages.7

diff --git a/draft/man7/man-pages.7 b/draft/man7/man-pages.7
index 74eeb4e..ddd13b6 100644 (file)
--- a/draft/man7/man-pages.7
+++ b/draft/man7/man-pages.7
@@ -2,6 +2,7 @@
 .\" (faith@cs.unc.edu and dwheeler@ida.org)
 .\" and (C) Copyright 2007 Michael Kerrisk <mtk.manpages@gmail.com>
 .\"
 .\" (faith@cs.unc.edu and dwheeler@ida.org)
 .\" and (C) Copyright 2007 Michael Kerrisk <mtk.manpages@gmail.com>
 .\"

+.\" %%%LICENSE_START(VERBATIM)

 .\" Permission is granted to make and distribute verbatim copies of this
 .\" manual provided the copyright notice and this permission notice are
 .\" preserved on all copies.
 .\" Permission is granted to make and distribute verbatim copies of this
 .\" manual provided the copyright notice and this permission notice are
 .\" preserved on all copies.


@@ -21,6 +22,7 @@
 .\"
 .\" Formatted or processed versions of this manual, if unaccompanied by
 .\" the source, must acknowledge the copyright and authors of this work.
 .\"
 .\" Formatted or processed versions of this manual, if unaccompanied by
 .\" the source, must acknowledge the copyright and authors of this work.

+.\" %%%LICENSE_END

 .\"
 .\" 2007-05-30 created by mtk, using text from old man.7 plus
 .\" rewrites and additional text.
 .\"
 .\" 2007-05-30 created by mtk, using text from old man.7 plus
 .\" rewrites and additional text.


@@ -30,15 +32,17 @@
 .\" This file was generated with po4a. Translate the source file.
 .\"
 .\"*******************************************************************
 .\" This file was generated with po4a. Translate the source file.
 .\"
 .\"*******************************************************************

-.TH MAN\-PAGES 7 2008\-10\-28 Linux "Linux Programmer's Manual"
+.TH MAN\-PAGES 7 2013\-07\-24 Linux "Linux Programmer's Manual"

 .SH 名前
 man\-pages \- Linux の man ページを書く際の決まり事
 .SH 書式
 \fBman\fP [\fIsection\fP] \fItitle\fP
 .SH 説明
 このページでは、 Linux \fIman\-pages\fP プロジェクトのマニュアルページを書く際に 従うべき決まり事について説明する。 Linux
 .SH 名前
 man\-pages \- Linux の man ページを書く際の決まり事
 .SH 書式
 \fBman\fP [\fIsection\fP] \fItitle\fP
 .SH 説明
 このページでは、 Linux \fIman\-pages\fP プロジェクトのマニュアルページを書く際に 従うべき決まり事について説明する。 Linux

-\fIman\-pages\fP は Linux のマニュアルページの セクション 2, 3, 4, 5, 7 から構成されている。
-このページで説明されている決まり事は、他のプロジェクトの マニュアルページを書く作者にも役立つことだろう。
+\fIman\-pages\fP プロジェクトは Linux カーネルおよび GNU C ライブラリが提供するユーザ空間 API
+のドキュメント作成を行っている。Linux システムのマニュアルページのセクション 2 のページのほとんどと、セクション 3, 4, 5, 7
+の多くのページが、このプロジェクトにより提供されている。このページで説明されている決まり事は、他のプロジェクトの
+マニュアルページを書く作者にも役立つことだろう。

 .SS マニュアルページのセクション
 .PP
 マニュアルのセクションは、習慣的に以下のような定義が用いられている:
 .SS マニュアルページのセクション
 .PP
 マニュアルのセクションは、習慣的に以下のような定義が用いられている:


@@ -60,7 +64,7 @@ man\-pages \- Linux の man ページを書く際の決まり事
 .TP 
 \fB6 ゲーム\fP
 .TP 
 .TP 
 \fB6 ゲーム\fP
 .TP 

-\fB7 約束事その他\fP
+\fB7 概要、約束事、その他\fP

 様々な事柄の概要、慣習、プロトコル、文字集合の規格、その他雑多なこと。
 .TP 
 \fB8 システム管理コマンド\fP
 様々な事柄の概要、慣習、プロトコル、文字集合の規格、その他雑多なこと。
 .TP 
 \fB8 システム管理コマンド\fP


@@ -146,6 +150,7 @@ Programmer's Manual\fP を使うこと)。
 エラー             [たいていはセクション 2, 3 のみ]
 環境変数
 ファイル
 エラー             [たいていはセクション 2, 3 のみ]
 環境変数
 ファイル

+属性               [通常はセクション 2, 3 のみ]

 バージョン         [通常はセクション 2, 3 のみ]
 準拠
 注意/備考
 バージョン         [通常はセクション 2, 3 のみ]
 準拠
 注意/備考


@@ -163,7 +168,8 @@ Programmer's Manual\fP を使うこと)。
 以下のリストでは、上記のセクションのそれぞれの内容について 詳しく説明する。
 .TP  14
 \fB名前 (NAME)\fP
 以下のリストでは、上記のセクションのそれぞれの内容について 詳しく説明する。
 .TP  14
 \fB名前 (NAME)\fP

-そのマニュアルページの名前。 \fB.SH NAME\fP コマンドの行が従うべき大事な点については \fBman\fP(7)  を参照してほしい。
+マニュアルページの名前。 \fB.SH NAME\fP コマンドの後に続ける行の重要な情報については \fBman\fP(7) を参照。この行のすべての単語は
+("\e\-" の直後の単語も含め) 小文字にすべきである。但し、英語や技術用語の慣例として別の記載をする場合はこの限りではない。

 .TP 
 \fB書式 (SYNOPSIS)\fP
 コマンドや関数のインターフェースを簡潔に記述する。 コマンドに対しては、コマンドや引き数 (オプション) の文法を書く。
 .TP 
 \fB書式 (SYNOPSIS)\fP
 コマンドや関数のインターフェースを簡潔に記述する。 コマンドに対しては、コマンドや引き数 (オプション) の文法を書く。


@@ -188,6 +194,21 @@ Programmer's Manual\fP を使うこと)。
 プログラム・関数・フォーマットの動作・目的を説明する。 ファイルや標準入力をどのように処理し、標準出力や標準エラー出力を
 どのように生成するかといったことについて述べる。 内部動作や実装の詳細については省略する (ただしそれが動作の理解にどうしても必要なら別)。
 通常の場合について記述する。 プログラムのコマンドライン・オプションの説明には、 \fBオプション\fP のセクションを用いる。
 プログラム・関数・フォーマットの動作・目的を説明する。 ファイルや標準入力をどのように処理し、標準出力や標準エラー出力を
 どのように生成するかといったことについて述べる。 内部動作や実装の詳細については省略する (ただしそれが動作の理解にどうしても必要なら別)。
 通常の場合について記述する。 プログラムのコマンドライン・オプションの説明には、 \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):
+.RS 22
+.TP 
+ \fBXYZ_FLAG\fP (since 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).

 .TP 
 \fBオプション (OPTIONS)\fP
 .\" .TP
 .TP 
 \fBオプション (OPTIONS)\fP
 .\" .TP


@@ -242,6 +263,25 @@ Programmer's Manual\fP を使うこと)。
 多くのプログラムではデフォルトのインストール先は \fI/usr/local\fP である。したがってベースとなるマニュアルページでも
 \fI/usr/local\fP が使われていることが多いだろう。
 .TP 
 多くのプログラムではデフォルトのインストール先は \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 のバージョンについての簡潔な概要。
 一般に、全ての新しいインターフェイスは、マニュアルページに 「バージョン」の節を設けるべきである。
 \fBバージョン (VERSIONS)\fP
 システムコールやライブラリ関数が登場したり、動作の重要な変更が行われた、 Linux カーネルや glibc のバージョンについての簡潔な概要。
 一般に、全ての新しいインターフェイスは、マニュアルページに 「バージョン」の節を設けるべきである。


@@ -283,6 +323,9 @@ Programmer's Manual\fP を使うこと)。
 \fB関連項目 (SEE ALSO)\fP
 関連するマニュアルページを、コンマ区切りのリストで、 セクション番号順に、セクション内ではアルファベット順で記載する。 可能なら関連する他の文書も書く。
 慣習では、このセクションは最後に置く。 リストの末尾にピリオドを置かないこと。
 \fB関連項目 (SEE ALSO)\fP
 関連するマニュアルページを、コンマ区切りのリストで、 セクション番号順に、セクション内ではアルファベット順で記載する。 可能なら関連する他の文書も書く。
 慣習では、このセクションは最後に置く。 リストの末尾にピリオドを置かないこと。

+.IP
+関連項目のリストに長いマニュアルページ名が多く含まれる場合には、出力を見やすくするために \fI.ad l\fP (右揃えをしない) や \fI.nh\fP
+(ハイフンによる折り返しをしない) を活用するとよい。個々のページ名のハイフンによる折り返しは、単語の前に "\e%" を付けることで防ぐことができる。

 .SS フォントの慣習
 .PP
 関数に対しては、引き数には常にイタリック体を用いる。 「たとえ書式 (SYNOPSIS) セクションであっても、このルールに従う」
 .SS フォントの慣習
 .PP
 関数に対しては、引き数には常にイタリック体を用いる。 「たとえ書式 (SYNOPSIS) セクションであっても、このルールに従う」


@@ -336,6 +379,9 @@ man 7 man\-pages
 (相互参照にセクション番号を含めておくと、 \fBman2html\fP といったツールがページ間のハイパーリンクを適切に生成できる。)
 .SS "綴り (spelling)"
 リリース 2.59 からだが、 \fIman\-pages\fP はアメリカ英語の綴りの慣習に従っている。 新しいページやパッチは全てこの慣習に従って下さい。
 (相互参照にセクション番号を含めておくと、 \fBman2html\fP といったツールがページ間のハイパーリンクを適切に生成できる。)
 .SS "綴り (spelling)"
 リリース 2.59 からだが、 \fIman\-pages\fP はアメリカ英語の綴りの慣習に従っている。 新しいページやパッチは全てこの慣習に従って下さい。

+.SS 大文字表記
+サブセクション ("SS") 見出しでは、最初の単語だけ先頭文字を大文字にし、残りの単語は小文字にすること。但し、英語の用法 (例えば、固有名詞)
+やプログラミング言語の要件 (例えば、識別子の名前) などで別の表記をする場合はこの限りではない。

 .SS サンプルプログラムとシェルのセッション
 マニュアルページには、システムコールやライブラリ関数の使い方を示す サンプルプログラムを含めることができる。 その際には、以下の点に留意すべきである。
 .TP  3
 .SS サンプルプログラムとシェルのセッション
 マニュアルページには、システムコールやライブラリ関数の使い方を示す サンプルプログラムを含めることができる。 その際には、以下の点に留意すべきである。
 .TP  3


@@ -377,6 +423,6 @@ TAB 文字を使うのは避けること。)
 \fBman\fP(1), \fBman2html\fP(1), \fBgroff\fP(7), \fBgroff_man\fP(7), \fBman\fP(7),
 \fBmdoc\fP(7)
 .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.40 の一部
+この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.53 の一部

 である。プロジェクトの説明とバグ報告に関する情報は
 http://www.kernel.org/doc/man\-pages/ に書かれている。
 である。プロジェクトの説明とバグ報告に関する情報は
 http://www.kernel.org/doc/man\-pages/ に書かれている。