release/man7/man-pages.7

   1 .\" (C) Copyright 1992-1999 Rickard E. Faith and David A. Wheeler
   2 .\" (faith@cs.unc.edu and dwheeler@ida.org)
   3 .\" and (C) Copyright 2007 Michael Kerrisk <mtk.manpages@gmail.com>
   4 .\"
   5 .\" %%%LICENSE_START(VERBATIM)
   6 .\" Permission is granted to make and distribute verbatim copies of this
   7 .\" manual provided the copyright notice and this permission notice are
   8 .\" preserved on all copies.
   9 .\"
  10 .\" Permission is granted to copy and distribute modified versions of this
  11 .\" manual under the conditions for verbatim copying, provided that the
  12 .\" entire resulting derived work is distributed under the terms of a
  13 .\" permission notice identical to this one.
  14 .\"
  15 .\" Since the Linux kernel and libraries are constantly changing, this
  16 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  17 .\" responsibility for errors or omissions, or for damages resulting from
  18 .\" the use of the information contained herein.  The author(s) may not
  19 .\" have taken the same level of care in the production of this manual,
  20 .\" which is licensed free of charge, as they might when working
  21 .\" professionally.
  22 .\"
  23 .\" Formatted or processed versions of this manual, if unaccompanied by
  24 .\" the source, must acknowledge the copyright and authors of this work.
  25 .\" %%%LICENSE_END
  26 .\"
  27 .\" 2007-05-30 created by mtk, using text from old man.7 plus
  28 .\" rewrites and additional text.
  29 .\"
  30 .\"*******************************************************************
  31 .\"
  32 .\" This file was generated with po4a. Translate the source file.
  33 .\"
  34 .\"*******************************************************************
  35 .\"
  36 .\" Japanese Version Copyright (c) 2007  Akihiro MOTOKI
  37 .\"         all rights reserved.
  38 .\" Translated 2007-06-13, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.54
  39 .\" Updated 2007-07-04, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.59
  40 .\" Updated 2007-09-03, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.64
  41 .\" Updated 2008-08-09, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v3.05
  42 .\" Updated 2013-05-04, Akihiro MOTOKI <amotoki@gmail.com>
  43 .\" Updated 2013-07-24, Akihiro MOTOKI <amotoki@gmail.com>
  44 .\" Updated 2013-08-21, Akihiro MOTOKI <amotoki@gmail.com>, LDP v3.53
  45 .\"
  46 .TH MAN\-PAGES 7 2014\-03\-16 Linux "Linux Programmer's Manual"
  47 .SH 名前
  48 man\-pages \- Linux の man ページを書く際の決まり事
  49 .SH 書式
  50 \fBman\fP [\fIsection\fP] \fItitle\fP
  51 .SH 説明
  52 このページでは、 Linux \fIman\-pages\fP プロジェクトのマニュアルページを書く際に 従うべき決まり事について説明する。 Linux
  53 \fIman\-pages\fP プロジェクトは Linux カーネルおよび GNU C ライブラリが提供するユーザ空間 API
  54 のドキュメント作成を行っている。Linux システムのマニュアルページのセクション 2 のページのほとんどと、セクション 3, 4, 5, 7
  55 の多くのページが、このプロジェクトにより提供されている。このページで説明されている決まり事は、他のプロジェクトの
  56 マニュアルページを書く作者にも役立つことだろう。
  57 .SS マニュアルページのセクション
  58 .PP
  59 マニュアルのセクションは、習慣的に以下のような定義が用いられている:
  60 .TP  10
  61 \fB1 コマンド (プログラム)\fP
  62 シェルの中からユーザが実行できるコマンド。
  63 .TP
  64 \fB2 システムコール\fP
  65 カーネルが処理しなければならない関数。
  66 .TP
  67 \fB3 ライブラリコール\fP
  68 \fIlibc\fP の関数の大部分。
  69 .TP
  70 \fB4 スペシャルファイル (デバイス)\fP
  71 \fI/dev\fP 以下にあるファイル。
  72 .TP
  73 \fB5 ファイルのフォーマットと規約\fP
  74 \fI/etc/passwd\fP などの人が読めるファイルのフォーマット。
  75 .TP
  76 \fB6 ゲーム\fP
  77 .TP
  78 \fB7 概要、約束事、その他\fP
  79 様々な事柄の概要、慣習、プロトコル、文字集合の規格、その他雑多なこと。
  80 .TP
  81 \fB8 システム管理コマンド\fP
  82 .\" .TP
  83 .\" .B 9 Kernel routines
  84 .\" This is an obsolete manual section.
  85 .\" Once it was thought a good idea to document the Linux kernel here,
  86 .\" but in fact very little has been documented, and the documentation
  87 .\" that exists is outdated already.
  88 .\" There are better sources of
  89 .\" information for kernel developers.
  90 \fBmount\fP(8)  のような root のみが実行可能なコマンド。
  91 .SS マクロパッケージ
  92 新しいマニュアルページは \fBman\fP(7)  で説明されている \fBgroff an.tmac\fP パッケージを使って記述すべきである。
  93 この方針は一貫性の確保が主な理由である。既存の Linux のマニュアルページ の圧倒的多数がこれらのマクロを使って記述されている。
  94 .SS ソースファイルの配置に関する決まり事
  95 マニュアルページのソースコードの 1行の長さは 可能な限り 75文字を越えないようにしてほしい。 こうすることで、パッチをメール本文に載せて送る場合に、
  96 メールクライアントによる行折り返しを回避することができる。
  97
  98 新しい文は行頭から開始する。 これにより、パッチの内容を確認しやすくなる。 パッチは文単位であることが多いからである。
  99 .SS タイトル行
 100 man ページの最初の行は \fBTH\fP コマンドにすべきである。
 101 .RS
 102 .sp
 103 \fB\&.TH\fP \fItitle section date source manual\fP
 104 .sp
 105 .RE
 106 個々の説明:
 107 .RS
 108 .TP  10
 109 \fItitle\fP
 110 man ページのタイトル。全部大文字で記載する (例: \fIMAN\-PAGES\fP)。
 111 .TP
 112 \fIsection\fP
 113 man ページが属するセクション番号 (例: \fI7\fP)。
 114 .TP
 115 \fIdate\fP
 116 最新のリビジョンの日付\(emman ページに些細でない変更を加えたときには必ずこれを変更すること。 日付は YYYY\-MM\-DD
 117 の形式で記載すべきである。
 118 .TP
 119 \fIsource\fP
 120 コマンド、関数、システムコールの出自。
 121
 122 数少ないセクション 1 と 8 のページの場合、おそらく単に \fIGNU\fP とだけ書くことが多いだろう。
 123
 124 システムコールの場合、単に \fILinux\fP とだけ書く。 (以前の慣習では、マニュアルページを記載した/内容を確認したカーネルの
 125 バージョン番号を記載していた。しかし、バージョン番号が実際の内容と 一致していることはなく、そのためバージョン番号がないよりも
 126 おそらく悪い形になっていた。 今後は、バージョン番号を含めるのは避けること。)
 127
 128 glibc のライブラリコールや その他の一般的な GNU ライブラリのライブラリコールの場合、 単に \fIGNU C Library\fP, \fIGNU\fP
 129 と書くか、空の文字列を使う。
 130
 131 セクション 4 のページでは \fILinux\fP を使う。
 132
 133 よくわからない場合は、 \fILinux\fP とか \fIGNU\fP と書いておく。
 134 .TP
 135 \fImanual\fP
 136 マニュアルのタイトル (例: \fIman\-pages\fP パッケージのセクション 2 および 3 のページの場合には、 \fILinux
 137 Programmer's Manual\fP を使うこと)。
 138 .RE
 139 .SS マニュアルページのセクション
 140 昔から使われてきたセクション名を以下のリストに示す。 これらを使うと良いだろう。 一般的に、マニュアルページは、少なくとも \fB色つき\fP
 141 のセクションを持つのが望ましい。 新しくマニュアルページを作成する際には、だいたい以下のリストに示した 順序でセクションを配置するようにしてもらいたい。
 142 .in +0.5i
 143 .nf
 144
 145 .\" May 07: Few current man pages have an ERROR HANDLING section,,,
 146 .\" ERROR HANDLING,
 147 .\" May 07: Almost no current man pages have a USAGE section,,,
 148 .\" USAGE,
 149 .\" DIAGNOSTICS,
 150 .\" May 07: Almost no current man pages have a SECURITY section,,,
 151 .\" SECURITY,
 152 .\" AUTHORS sections are discouraged
 153 .\" AUTHORS             [Discouraged]
 154 \fB名前\fP
 155 \fB書式\fP
 156 設定               [通常はセクション 4 のみ]
 157 \fB説明\fP
 158 オプション         [通常はセクション 1, 8 のみ]
 159 終了ステータス     [通常はセクション 1, 8 のみ]
 160 返り値             [通常はセクション 2, 3 のみ]
 161 エラー             [たいていはセクション 2, 3 のみ]
 162 環境変数
 163 ファイル
 164 バージョン         [通常はセクション 2, 3 のみ]
 165 属性               [通常はセクション 2, 3 のみ]
 166 準拠
 167 注意/備考
 168 バグ
 169 例
 170 \fB関連項目\fP
 171
 172 .fi
 173 .in
 174 「伝統的に使われてきた見出しが使える場合には、それを使ってほしい。」 この種の一貫性を保つことで、情報を理解しやすくなるからである。
 175 どうしても必要な場合には、理解しやすくなるように独自の見出しを 作ってもよい (特にセクション 4 や 5 のページではこうした方が
 176 わかりやすくなる)。ただし、そうする前に、伝統的な見出しを使い、 そのセクション内にサブセクション (\fI.SS\fP) を設けることで
 177 対応できないか考えてほしい。
 178
 179 以下のリストでは、上記のセクションのそれぞれの内容について 詳しく説明する。
 180 .TP  14
 181 \fB名前 (NAME)\fP
 182 マニュアルページの名前。 \fB.SH NAME\fP コマンドの後に続ける行の重要な情報については \fBman\fP(7) を参照。この行のすべての単語は
 183 ("\e\-" の直後の単語も含め) 小文字にすべきである。但し、英語や技術用語の慣例として別の記載をする場合はこの限りではない。
 184 .TP
 185 \fB書式 (SYNOPSIS)\fP
 186 コマンドや関数のインターフェースを簡潔に記述する。 コマンドに対しては、コマンドや引き数 (オプション) の文法を書く。
 187 そのまま書くテキストにはボールド体を用い、置き換える引き数には イタリック体を用いる。省略可能なオプションはブラケット ([]) で囲い、 選択肢は縦棒
 188 (|) で区切り、繰り返しには省略符号 (...) を書く。 関数に対しては、必要なデータ宣言や \fB#include\fP 指定を書き、関数宣言を続ける。
 189
 190 .\" FIXME . Say something here about compiler options
 191 ヘッダファイルから関数 (や変数) の定義を得るために 機能検査マクロ (feature test macro) を定義しなければならない場合、 書式
 192 (SYNOPSIS) に必要な機能検査マクロを記載すべきである。 機能検査マクロについては \fBfeature_test_macros\fP(7)
 193 で説明されている。
 194 .TP
 195 \fBCONFIGURATION\fP
 196 デバイスの設定詳細。 通常、このセクションは 4 章のマニュアルページでのみ登場する。
 197 .TP
 198 \fB説明 (DESCRIPTION)\fP
 199 .\" If there is some kind of input grammar or complex set of subcommands,
 200 .\" consider describing them in a separate
 201 .\" .B USAGE
 202 .\" section (and just place an overview in the
 203 .\" .B DESCRIPTION
 204 .\" section).
 205 プログラム・関数・フォーマットの動作・目的を説明する。 ファイルや標準入力をどのように処理し、標準出力や標準エラー出力を
 206 どのように生成するかといったことについて述べる。 内部動作や実装の詳細については省略する (ただしそれが動作の理解にどうしても必要なら別)。
 207 通常の場合について記述する。 プログラムのコマンドライン・オプションの説明には、 \fBオプション\fP のセクションを用いる。
 208
 209 システムコールやライブラリ関数の新しい動作や新しいフラグについて説明する際は、 変更が取り込まれたカーネルや C
 210 ライブラリのバージョンを注記に入れるように気を付けること。 フラグにこの情報の注記を入れる方法としては、推奨される方法は、 以下のように \fB.TP\fP
 211 リストの一部にすることである (この例はシステムコールの新しいフラグの場合)。
 212 .RS 22
 213 .TP
 214  \fBXYZ_FLAG\fP (Linux 3.7 以降)
 215 フラグの説明...
 216 .RE
 217 .IP
 218 バージョン情報を入れておくのは、 古いバージョンのカーネルや C ライブラリを使わざるを得ないユーザにとって、 特に有用である
 219 (例えば、組み込みシステムではよくあることである)。
 220 .TP
 221 \fBオプション (OPTIONS)\fP
 222 .\" .TP
 223 .\" .B USAGE
 224 .\" describes the grammar of any sublanguage this implements.
 225 プログラムが受け付けるコマンドライン・オプションと、 その場合プログラムの振舞いがどう変わるかを説明する。 このセクションはセクション 1 と 8
 226 のマニュアルページにだけ登場すべきである。
 227 .TP
 228 \fB終了ステータス (EXIT STATUS)\fP
 229 プログラムの終了ステータスの値と、それらの値に対応する状況を列挙する。 このセクションはセクション 1 と 8
 230 のマニュアルページにだけ登場すべきである。
 231 .TP
 232 \fB返り値 (RETURN VALUE)\fP
 233 セクション 2 と 3 のページの場合、このセクションに ライブラリルーチンが呼び出し元に返す値のリストを記載する。
 234 それらの値が返された場合の状態に対する説明も書く。
 235 .TP
 236 \fBエラー (ERRORS)\fP
 237 セクション 2 と 3 のマニュアルページでは、 エラーが発生した場合に \fIerrno\fP に設定される可能性がある値のリストを記載する。
 238 リストには、エラーの値とエラーの原因についての情報を書く。 「エラーリストはアルファベット順にすべきである。」
 239 .TP
 240 \fB環境変数 (ENVIRONMENT)\fP
 241 プログラムや関数に影響する環境変数をリストし、それらの効果を書く。
 242 .TP
 243 \fBファイル (FILES)\fP
 244 .\" May 07: Almost no current man pages have a DIAGNOSTICS section;
 245 .\"         "RETURN VALUE" or "EXIT STATUS" is preferred.
 246 .\" .TP
 247 .\" .B DIAGNOSTICS
 248 .\" gives an overview of the most common error messages and how to
 249 .\" cope with them.
 250 .\" You don't need to explain system error messages
 251 .\" or fatal signals that can appear during execution of any program
 252 .\" unless they're special in some way to the program.
 253 .\"
 254 .\" May 07: Almost no current man pages have a SECURITY section.
 255 .\".TP
 256 .\".B SECURITY
 257 .\"discusses security issues and implications.
 258 .\"Warn about configurations or environments that should be avoided,
 259 .\"commands that may have security implications, and so on, especially
 260 .\"if they aren't obvious.
 261 .\"Discussing security in a separate section isn't necessary;
 262 .\"if it's easier to understand, place security information in the
 263 .\"other sections (such as the
 264 .\" .B DESCRIPTION
 265 .\" or
 266 .\" .B USAGE
 267 .\" section).
 268 .\" However, please include security information somewhere!
 269 プログラムや関数が用いるファイルを列記する。 例えば、設定ファイル、起動ファイル、プログラムが直接操作するファイルなどである。
 270 これらのファイルのファイル名はフルパスで記載し、 ディレクトリの部分はユーザーの好みに合わせて インストール処理で変更できるようにする。
 271 多くのプログラムではデフォルトのインストール先は \fI/usr/local\fP である。したがってベースとなるマニュアルページでも
 272 \fI/usr/local\fP が使われていることが多いだろう。
 273 .TP
 274 \fB属性 (ATTRIBUTES)\fP
 275 そのページで説明している関数の種々の属性の概要を、サブセクションに分けて説明する。以下のサブセクションが定義されている。
 276 .sp
 277 .RS
 278 .TP
 279 \fBマルチスレッディング (pthreads(7) 参照)\fP
 280 このサブセクションでは、マルチスレッドアプリケーションに関連する属性について説明する。
 281 .RS
 282 .IP * 3
 283 その関数がスレッドセーフかどうか。
 284 .IP *
 285 その関数が取り消しポイント (cancellation point) かどうか。
 286 .IP *
 287 その関数が非同期で安全にキャンセルできるか (async\-cancel\-safe かどうか)。
 288 .RE
 289 .IP
 290 これらの属性の詳細は \fBpthreads\fP(7) で説明されている。
 291 .RE
 292 .TP
 293 \fBバージョン (VERSIONS)\fP
 294 システムコールやライブラリ関数が登場したり、動作の重要な変更が行われた、 Linux カーネルや glibc のバージョンについての簡潔な概要。
 295 一般に、全ての新しいインターフェイスは、マニュアルページに 「バージョン」の節を設けるべきである。
 296 残念なことに、多くの既存のマニュアルページにこの情報は含まれていない (これらのページが書かれた時点ではそのようなポリシーはなかったからである)。
 297 これを改善するパッチは歓迎されるが、 新しいコードを書くプログラマの観点からすれば、 おそらくこの情報が重要になるのは、 Linux 2.4
 298 以降で追加されたカーネルインターフェイス (カーネル 2.2 からの変更) と glibc バージョン 2.1 以降で追加されたライブラリ関数
 299 (glibc 2.0 からの変更)  についてのみであろう。
 300
 301 \fBsyscalls\fP(2)  マニュアルページにも、いろいろなシステムコールが初めて登場した カーネルバージョンについての情報が書かれている。
 302 .TP
 303 \fB準拠 (CONFORMING TO)\fP
 304 そのマニュアルページで説明している関数やコマンドに関連する 標準規格や慣習について記載する。 様々な標準を示すのに適した用語は
 305 \fBstandards\fP(7) に見出しでリストになっている。 セクション 2 や 3 のページでは、このセクションで システムコールや関数が準拠する
 306 POSIX.1 のバージョンと、 C99 で規定されているかに触れるべきである。 (SUS, SUSv2, XPG などの他の標準規格や、SVr4 や
 307 4.xBSD の実装標準に ついては、説明しているコールがこれらの規格で規定されており POSIX.1 の現行バージョンで規定されていない場合以外は、
 308 あまり深く気にする必要はない。)  (\fBstandards\fP(7)  参照。)
 309
 310 そのコールがどの標準にも基づいていないが、 他のシステムで広く存在する場合は、その旨を記載すること。 そのコールが Linux
 311 固有の場合は、その旨を記載すること。
 312
 313 (そうなっているページが多いが) このセクションの内容が標準のリスト だけの場合、リストの最後にピリオド (\(aq.\(aq) を置くこと。
 314 .TP
 315 \fB注意 (NOTES)\fP
 316 その他の注意点を書く。 セクション 2 と 3 のマニュアルページでは、 \fILinux での注意 (Linux Notes)\fP や \fIglibc
 317 での注意 (Glibc Notes)\fP という名前のサブセクション (\fBSS\fP) を設けると便利なこともある。
 318 .TP
 319 \fBバグ (BUGS)\fP
 320 制限・知られている欠陥や不便な点、その他不思議な動作などを書く。
 321 .TP
 322 \fB例 (EXAMPLE)\fP
 323 この関数・ファイル・コマンドをどのように使うかを示した ひとつまたは複数の例を記述する。 サンプルプログラムを書く際の詳細は
 324 以下の「サンプルプログラム」の節を参照のこと。
 325 .TP
 326 \fB著者 (AUTHORS)\fP
 327 文書またはプログラムの著者を列記する。 \fB著者セクションは極力使用しないこと。\fP 一般的には、著者のリストを各ページに撒き散らさない方がよい
 328 (時間がたつと、作者のリストは膨大になる可能性がある)。 マニュアルページを新規に書いたり、大幅に修正を行った場合には、
 329 ソースファイルにコメントとして著作権表示を追加すること。 あなたがデバイスドライバの作者で、バグを報告するためのアドレスを
 330 載せたい場合は、「バグ」セクションの後ろにこのセクションを配置すること。
 331 .TP
 332 \fB関連項目 (SEE ALSO)\fP
 333 関連するマニュアルページを、コンマ区切りのリストで、 セクション番号順に、セクション内ではアルファベット順で記載する。 可能なら関連する他の文書も書く。
 334 慣習では、このセクションは最後に置く。 リストの末尾にピリオドを置かないこと。
 335 .IP
 336 関連項目のリストに長いマニュアルページ名が多く含まれる場合には、出力を見やすくするために \fI.ad l\fP (右揃えをしない) や \fI.nh\fP
 337 (ハイフンによる折り返しをしない) を活用するとよい。個々のページ名のハイフンによる折り返しは、単語の前に "\e%" を付けることで防ぐことができる。
 338 .SH "STYLE GUIDE"
 339 The following subsections describe the preferred style for the \fIman\-pages\fP
 340 project.  For details not covered below, the Chicago Manual of Style is
 341 usually a good source; try also grepping for preexisting usage in the
 342 project source tree.
 343 .SS "Use of gender\-neutral language"
 344 As far as possible, use gender\-neutral language in the text of man pages.
 345 Use of "they" ("them", "themself", "their") as a gender\-neutral singular
 346 pronoun is acceptable.
 347 .SS フォントの慣習
 348 .PP
 349 関数に対しては、引き数には常にイタリック体を用いる。 「たとえ書式 (SYNOPSIS) セクションであっても、このルールに従う」
 350 関数の他の部分はボールドを指定する:
 351 .PP
 352 \fB int myfunction(int \fP\fIargc\fP\fB, char **\fP\fIargv\fP\fB);\fP
 353 .PP
 354 引き数名といった変数名はイタリック体を指定すべきである。
 355 .PP
 356 ファイル名 (パス名、またはヘッダーファイルへの参照) は常にイタリック体にする (例: \fI<stdio.h>\fP)。 ただし、書式
 357 (SYNOPSIS) セクションは例外で、 インクルードファイルはボールドにする (例: \fB#include <stdio.h>\fP)。
 358 標準のインクルードヘッダファイルを参照する際は、 通常の C 言語と同様に山括弧でヘッダファイルを囲ぬで指定する (例：
 359 \fI<stdio.h>\fP)。
 360 .PP
 361 通常、大文字で表現する特殊マクロはボールドで表す (例えば \fBMAXINT\fP)。 例外として NULL はボールドにしない。
 362 .PP
 363 エラーコードのリストを列挙する時には、コードはボールドで表す (このリストには通常 \fB\&.TP\fP マクロを用いる)。
 364 .PP
 365 完全なコマンドは、長い場合には、例に示すように 字下げした行にコマンドだけを記載し、コマンドの前後には空行を置くべきである。
 366 .in +4n
 367 .nf
 368
 369 man 7 man\-pages
 370
 371 .fi
 372 .in
 373 コマンドが短い場合は、 \fIman 7 man\-pages\fP のようにイタリック体で文中に埋め込んで記載してもよい。
 374 この場合、コマンド内の適切な位置に、改行できないスペース ("\e\ ")  を使うとよいかもしれない。 コマンドオプションも (\fI\-l\fP のように)
 375 イタリック体で記載すべきである。
 376 .PP
 377 式は、専用の字下げした行に記載しない場合、イタリック体を指定すること。 繰り返しになるが、式を通常の文中に埋め込む場合にも、
 378 改行できないスペースを使うとよいだろう。
 379 .PP
 380 そのマニュアルページの説明対象への参照は、ボールドで名前を記載する。 対象が関数 (つまり、セクション 2 や 3 のページ) の場合、
 381 名前の後ろにローマンフォント (通常のフォント) で丸括弧の対を続ける。 例えば、 \fBfcntl\fP(2)  のマニュアルページでは、説明対象への参照は
 382 \fBfcntl\fP()  のように記載する。 マニュアルページのソースファイルには次のように記載するのが望ましい:
 383 .nf
 384
 385     .BR fcntl ()
 386
 387 .fi
 388 ("\efB...\efP()" よりも、この形式を使うこと。 これにより、マニュアルページのソースファイルを解釈するツールを 書くのが簡単になる。)
 389 .PP
 390 別のマニュアルページへの参照は、ボールドで名前を記載し、 それに続けてセクション番号を「必ず」書く。セクション番号は ローマンフォント
 391 (通常のフォント) で書き、スペースは入れない (例: \fBintro\fP(2))。 マニュアルページのソースファイルには次のように記載するのが望ましい:
 392 .nf
 393
 394     .BR intro (2)
 395
 396 .fi
 397 (相互参照にセクション番号を含めておくと、 \fBman2html\fP といったツールがページ間のハイパーリンクを適切に生成できる。)
 398
 399 Control characters should be written in bold face, with no quotes; for
 400 example, \fB^X\fP.
 401 .SS "綴り (spelling)"
 402 リリース 2.59 からだが、 \fIman\-pages\fP はアメリカ英語の綴りの慣習に従っている
 403 (以前はイギリス英語とアメリカ英語が基準もなく混在して使われていた)。 新しいページやパッチは全てこの慣習に従って下さい。
 404
 405 Aside from the well\-known spelling differences, there are a few other
 406 subtleties to watch for:
 407 .IP * 3
 408 American English tends to use the forms "backward", "upward", "toward", and
 409 so on rather than the British forms "backwards", "upwards", "towards", and
 410 so on.
 411 .SS "BSD version numbers"
 412 The classical scheme for writing BSD version numbers is \fIx.yBSD\fP, where
 413 \fIx.y\fP is the version number (e.g., 4.2BSD).  Avoid forms such as \fIBSD
 414 4.3\fP.
 415 .SS 大文字表記
 416 サブセクション ("SS") 見出しでは、最初の単語だけ先頭文字を大文字にし、残りの単語は小文字にすること。但し、英語の用法 (例えば、固有名詞)
 417 やプログラミング言語の要件 (例えば、識別子の名前) などで別の表記をする場合はこの限りではない。
 418
 419 \&.SS Unicode under Linux
 420
 421 .SS 構造体の定義、シェルのセッションログなどの字下げ、など
 422 構造体の定義やシェルのセッションログなどを本文中に記載する際は、 スペース 4個分の字下げを行う (つまり、ブロックを \fI.in\ +4n\fP と
 423 \&\fI.in\fP で囲む)。
 424 .SS "Preferred terms"
 425 The following table lists some preferred terms to use in man pages, mainly
 426 to ensure consistency across pages.
 427 .TS
 428 l l l
 429 ---
 430 l l l.
 431 用語  使用を避ける単語        備考
 432
 433 bit mask        bitmask
 434 built\-in       builtin
 435 Epoch   epoch   T{
 436 For the UNIX Epoch (00:00:00, 1 Jan 1970 UTC)
 437 T}
 438 filename        file name
 439 filesystem      file system
 440 hostname        host name
 441 inode   i\-node
 442 lowercase       lower case, lower\-case
 443 pathname        path name
 444 pseudoterminal  pseudo\-terminal
 445 privileged port T{
 446 reserved port,
 447 system port
 448 T}
 449 real\-time      T{
 450 realtime,
 451 real time
 452 T}
 453 run time        runtime
 454 saved set\-group\-ID    T{
 455 saved group ID,
 456 saved set\-GID
 457 T}
 458 saved set\-user\-ID     T{
 459 saved user ID,
 460 saved set\-UID
 461 T}
 462 set\-group\-ID  set\-GID, setgid
 463 set\-user\-ID   set\-UID, setuid
 464 superuser       T{
 465 super user,
 466 super\-user
 467 T}
 468 superblock      T{
 469 super block,
 470 super\-block
 471 T}
 472 timestamp       time stamp
 473 timezone        time zone
 474 uppercase       upper case, upper\-case
 475 usable  useable
 476 user space      userspace
 477 username        user name
 478 zeros   zeroes
 479 .TE
 480 .PP
 481 See also the discussion \fIHyphenation of attributive compounds\fP below.
 482 .SS "Terms to avoid"
 483 The following table lists some terms to avoid using in man pages, along with
 484 some suggested alternatives, mainly to ensure consistency across pages.
 485 .TS
 486 l l l
 487 ---
 488 l l l.
 489 Avoid   Use instead     Notes
 490
 491 32bit   32\-bit T{
 492 same for 8\-bit, 16\-bit, etc.
 493 T}
 494 current process calling process T{
 495 A common mistake made by kernel programmers when writing man pages
 496 T}
 497 manpage T{
 498 man page, manual page
 499 T}
 500 minus infinity  negative infinity
 501 non\-root       unprivileged user
 502 non\-superuser  unprivileged user
 503 nonprivileged   unprivileged
 504 OS      operating system
 505 plus infinity   positive infinity
 506 pty     pseudoterminal
 507 tty     terminal
 508 Unices  UNIX systems
 509 Unixes  UNIX systems
 510 .TE
 511 .SS 商標
 512 Use the correct spelling and case for trademarks.  The following is a list
 513 of the correct spellings of various relevant trademarks that are sometimes
 514 misspelled:
 515
 516      DG/UX
 517      HP\-UX
 518      UNIX
 519      UnixWare
 520 .SS "NULL, NUL, null pointer, and null character"
 521 A \fInull pointer\fP is a pointer that points to nothing, and is normally
 522 indicated by the constant \fINULL\fP.  On the other hand, \fINUL\fP is the \fInull
 523 byte\fP, a byte with the value 0, represented in C via the character constant
 524 \fI\(aq\e0\(aq\fP.
 525
 526 The preferred term for the pointer is "null pointer" or simply "NULL"; avoid
 527 writing "NULL pointer".
 528
 529 The preferred term for the byte is "null byte".  Avoid writing "NUL", since
 530 it is too easily confused with "NULL".  Avoid also the terms "zero byte" and
 531 "null character".  The byte that terminates a C string should be described
 532 as "the terminating null byte"; strings may be described as
 533 "null\-terminated", but avoid the use of "NUL\-terminated".
 534 .SS ハイパーリンク
 535 For hyperlinks, use the \fI.UR\fP/\fI.UE\fP macro pair (see \fBgroff_man\fP(7)).
 536 This produces proper hyperlinks that can be used in a web browser, when
 537 rendering a page with, say:
 538
 539      BROWSER=firefox man \-H pagename
 540 .SS "Use of e.g., i.e., etc., a.k.a., and similar"
 541 In general, the use of abbreviations such as "e.g.", "i.e.", "etc.",
 542 "a.k.a." should be avoided, in favor of suitable full wordings ("for
 543 example", "that is", "and so on", "also known as").
 544
 545 The only place where such abbreviations may be acceptable is in \fIshort\fP
 546 parenthetical asides (e.g., like this one).
 547
 548 Always include periods in such abbreviations, as shown here.  In addition,
 549 "e.g." and "i.e." should always be followed by a comma.
 550 .SS Em\-dashes
 551 The way to write an em\-dash\(emthe glyph that appears at either end of this
 552 subphrase\(emin *roff is with the macro "\e(em".  (On an ASCII terminal, an
 553 em\-dash typically renders as two hyphens, but in other typographical
 554 contexts it renders as a long dash.)  Em\-dashes should be written \fIwithout\fP
 555 surrounding spaces.
 556 .SS "Hyphenation of attributive compounds"
 557 Compound terms should be hyphenated when used attributively (i.e., to
 558 qualify a following noun). Some examples:
 559
 560     32\-bit value
 561     command\-line argument
 562     floating\-point number
 563     run\-time check
 564     user\-space function
 565     wide\-character string
 566 .SS "Hyphenation with multi, non, pre, re, sub, and so on"
 567 The general tendency in modern English is not to hyphenate after prefixes
 568 such as "multi", "non", "pre", "re", "sub", and so on.  Manual pages should
 569 generally follow this rule when these prefixes are used in natural English
 570 constructions with simple suffixes.  The following list gives some examples
 571 of the preferred forms:
 572
 573     interprocess
 574     multithreaded
 575     multiprocess
 576     nonblocking
 577     nondefault
 578     nonempty
 579     noninteractive
 580     nonnegative
 581     nonportable
 582     nonzero
 583     preallocated
 584     precreate
 585     prerecorded
 586     reestablished
 587     reinitialize
 588     rearm
 589     reread
 590     subcomponent
 591     subdirectory
 592     subsystem
 593
 594 Hyphens should be retained when the prefixes are used in nonstandard English
 595 words, with trademarks, proper nouns, acronyms, or compound terms.  Some
 596 examples:
 597
 598     non\-ASCII
 599     non\-English
 600     non\-NULL
 601     non\-real\-time
 602
 603 Finally, note that "re\-create" and "recreate" are two different verbs, and
 604 the former is probably what you want.
 605 .SS "Real minus character"
 606 Where a real minus character is required (e.g., for numbers such as \-1, or
 607 when writing options that have a leading dash, such as in \fIls\ \-l\fP), use
 608 the following form in the man page source:
 609
 610     \e\-
 611
 612 This guideline applies also to code examples.
 613 .SS "Character constants"
 614 To produce single quotes that render well in both ASCII and UTF\-8, use the
 615 following form for character constants in the man page source:
 616
 617     \e(aqC\e(aq
 618
 619 where \fIC\fP is the quoted character.  This guideline applies also to
 620 character constants used in code examples.
 621 .SS サンプルプログラムとシェルのセッション
 622 マニュアルページには、システムコールやライブラリ関数の使い方を示す サンプルプログラムを含めることができる。 その際には、以下の点に留意すべきである。
 623 .IP * 3
 624 サンプルプログラムは C で記載すること。
 625 .IP *
 626 サンプルプログラムは、 インタフェースについて文章で簡単に説明できる以上のことを示す場合にだけ
 627 必要かつ有用である。インタフェースを呼び出す以外に何もしないサンプル プログラムは普通はほとんど役に立たない。
 628 .IP *
 629 サンプルプログラムはかなり短めにすること (100行未満が望ましく、50行未満が理想的である)。
 630 .IP *
 631 サンプルプログラムでは、システムコールやライブラリ関数を呼び出した後で エラーチェックを行うこと。
 632 .IP *
 633 サンプルプログラムは完結していて、 \fIcc\ \-Wall\fP でコンパイルした際に警告なしでコンパイルできること。
 634 .IP *
 635 可能かつ適切な場合には、サンプルプログラムで 入力により動作を変化させるなどの実験を行うとよい
 636 (理想的には、コマンドライン引き数や、プログラムが読み込む入力データ 経由で、動作を変化させるのがよい)。
 637 .IP *
 638 サンプルプログラムは、K&R (Kernighan and Ritchie) スタイルで書き、 字下げはスペース 4文字で行う。 (ソースコードで
 639 TAB 文字を使うのは避けること。)
 640 .IP *
 641 For consistency, all example programs should terminate using either of:
 642
 643      exit(EXIT_SUCCESS);
 644      exit(EXIT_FAILURE);
 645
 646 Avoid using the following forms to terminate a program:
 647
 648     exit(0);
 649     exit(1);
 650     return n;
 651 .IP *
 652 If there is extensive explanatory text before the program source code, mark
 653 off the source code with a susbsection heading \fIProgram source\fP, as in:
 654
 655 \&.SS プログラムのソース
 656
 657 Always do this if the explanatory text includes a shell session log.
 658 .PP
 659 プログラムの使い方や他のシステムの特徴を示すためにシェルのセッションログを含める場合、
 660 .IP * 3
 661 セッションログをソースコードの前に置くこと
 662 .IP *
 663 セッションログをスペース 4 つで字下げすること
 664 .IP *
 665 ユーザの入力文をボールドにして、システムが生成する出力と区別できるようにすること
 666 .PP
 667 サンプルプログラムがどんな風になっていればよいかの例については、 \fBwait\fP(2)  と \fBpipe\fP(2)  を参照すること。
 668 .SH 例
 669 \fIman\-pages\fP パッケージに含まれるマニュアルページの体裁の標準的な例については、 \fBpipe\fP(2)  と \fBfcntl\fP(2)
 670 を参照すること。
 671 .SH 関連項目
 672 \fBman\fP(1), \fBman2html\fP(1), \fBgroff\fP(7), \fBgroff_man\fP(7), \fBman\fP(7),
 673 \fBmdoc\fP(7)
 674 .SH この文書について
 675 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.64 の一部
 676 である。プロジェクトの説明とバグ報告に関する情報は
 677 http://www.kernel.org/doc/man\-pages/ に書かれている。