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>
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.
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.
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
23 .\" Formatted or processed versions of this manual, if unaccompanied by
24 .\" the source, must acknowledge the copyright and authors of this work.
27 .\" 2007-05-30 created by mtk, using text from old man.7 plus
28 .\" rewrites and additional text.
30 .\"*******************************************************************
32 .\" This file was generated with po4a. Translate the source file.
34 .\"*******************************************************************
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
46 .TH MAN\-PAGES 7 2014\-12\-31 Linux "Linux Programmer's Manual"
48 man\-pages \- Linux の man ページを書く際の決まり事
50 \fBman\fP [\fIsection\fP] \fItitle\fP
52 このページでは、 Linux \fIman\-pages\fP プロジェクトのマニュアルページを書く際に 従うべき決まり事について説明する。 Linux
53 \fIman\-pages\fP プロジェクトは Linux カーネルおよび GNU C ライブラリが提供するユーザ空間 API
54 のドキュメント作成を行っている。Linux システムのマニュアルページのセクション 2 のページのほとんどと、セクション 3, 4, 5, 7
55 の多くのページが、このプロジェクトにより提供されている。このページで説明されている決まり事は、他のプロジェクトの
56 マニュアルページを書く作者にも役立つことだろう。
59 マニュアルのセクションは、習慣的に以下のような定義が用いられている:
70 \fB4 スペシャルファイル (デバイス)\fP
73 \fB5 ファイルのフォーマットと規約\fP
74 \fI/etc/passwd\fP などの人が読めるファイルのフォーマット。
79 様々な事柄の概要、慣習、プロトコル、文字集合の規格、その他雑多なこと。
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 のみが実行可能なコマンド。
92 新しいマニュアルページは \fBman\fP(7) で説明されている \fBgroff an.tmac\fP パッケージを使って記述すべきである。
93 この方針は一貫性の確保が主な理由である。既存の Linux のマニュアルページ の圧倒的多数がこれらのマクロを使って記述されている。
94 .SS ソースファイルの配置に関する決まり事
95 マニュアルページのソースコードの 1行の長さは 可能な限り 75文字を越えないようにしてほしい。 こうすることで、パッチをメール本文に載せて送る場合に、
96 メールクライアントによる行折り返しを回避することができる。
98 新しい文は行頭から開始する。 これにより、パッチの内容を確認しやすくなる。 パッチは文単位であることが多いからである。
100 man ページの最初の行は \fBTH\fP コマンドにすべきである。
103 \fB\&.TH\fP \fItitle section date source manual\fP
110 man ページのタイトル。全部大文字で記載する (例: \fIMAN\-PAGES\fP)。
113 man ページが属するセクション番号 (例: \fI7\fP)。
116 man ページに最後に些細でない変更が行われた日付。 (\fIman\-pages\fP プロジェクトでは、
117 このタイムスタンプの必要な更新はスクリプトで自動的に行われるので、 パッチの中でこの日付を手動で更新する必要はない。) 日付は YYYY\-MM\-DD
123 数少ないセクション 1 と 8 のページの場合、おそらく単に \fIGNU\fP とだけ書くことが多いだろう。
125 システムコールの場合、単に \fILinux\fP とだけ書く。 (以前の慣習では、マニュアルページを記載した/内容を確認したカーネルの
126 バージョン番号を記載していた。しかし、バージョン番号が実際の内容と 一致していることはなく、そのためバージョン番号がないよりも
127 おそらく悪い形になっていた。 今後は、バージョン番号を含めるのは避けること。)
129 glibc のライブラリコールや その他の一般的な GNU ライブラリのライブラリコールの場合、 単に \fIGNU C Library\fP, \fIGNU\fP
132 セクション 4 のページでは \fILinux\fP を使う。
134 よくわからない場合は、 \fILinux\fP とか \fIGNU\fP と書いておく。
137 マニュアルのタイトル (例: \fIman\-pages\fP パッケージのセクション 2 および 3 のページの場合には、 \fILinux
138 Programmer's Manual\fP を使うこと)。
141 昔から使われてきたセクション名を以下のリストに示す。 これらを使うと良いだろう。 一般的に、マニュアルページは、少なくとも \fB色つき\fP
142 のセクションを持つのが望ましい。 新しくマニュアルページを作成する際には、だいたい以下のリストに示した 順序でセクションを配置するようにしてもらいたい。
146 .\" May 07: Few current man pages have an ERROR HANDLING section,,,
148 .\" May 07: Almost no current man pages have a USAGE section,,,
151 .\" May 07: Almost no current man pages have a SECURITY section,,,
153 .\" AUTHORS sections are discouraged
154 .\" AUTHORS [Discouraged]
159 オプション [通常はセクション 1, 8 のみ]
160 終了ステータス [通常はセクション 1, 8 のみ]
161 返り値 [通常はセクション 2, 3 のみ]
162 エラー [たいていはセクション 2, 3 のみ]
165 バージョン [通常はセクション 2, 3 のみ]
166 属性 [通常はセクション 2, 3 のみ]
175 「伝統的に使われてきた見出しが使える場合には、それを使ってほしい。」 この種の一貫性を保つことで、情報を理解しやすくなるからである。
176 どうしても必要な場合には、理解しやすくなるように独自の見出しを 作ってもよい (特にセクション 4 や 5 のページではこうした方が
177 わかりやすくなる)。ただし、そうする前に、伝統的な見出しを使い、 そのセクション内にサブセクション (\fI.SS\fP) を設けることで
180 以下のリストでは、上記のセクションのそれぞれの内容について 詳しく説明する。
185 \&\fB.SH NAME\fP コマンドの後に続ける行の重要な情報については \fBman\fP(7) を参照。この行のすべての単語は ("\e\-"
186 の直後の単語も含め) 小文字にすべきである。但し、英語や技術用語の慣例として別の記載をする場合はこの限りではない。
189 コマンドや関数インターフェースの簡潔な概要
191 コマンドに対しては、コマンドや引き数 (オプション) の文法を書く。 そのまま書くテキストにはボールド体を用い、置き換える引き数には
192 イタリック体を用いる。省略可能なオプションはブラケット ([]) で囲い、 選択肢は縦棒 (|) で区切り、繰り返しには省略符号 (...) を書く。
193 関数に対しては、必要なデータ宣言や \fB#include\fP 指定を書き、関数宣言を続ける。
195 .\" FIXME . Say something here about compiler options
196 ヘッダファイルから関数 (や変数) の定義を得るために 機能検査マクロ (feature test macro) を定義しなければならない場合、 書式
197 (SYNOPSIS) に必要な機能検査マクロを記載すべきである。 機能検査マクロについては \fBfeature_test_macros\fP(7)
203 通常、このセクションは 4 章のマニュアルページでのみ登場する。
205 \fB説明 (DESCRIPTION)\fP
206 プログラム・関数・フォーマットの動作・目的。
208 .\" If there is some kind of input grammar or complex set of subcommands,
209 .\" consider describing them in a separate
211 .\" section (and just place an overview in the
214 ファイルや標準入力をどのように処理し、標準出力や標準エラー出力を どのように生成するかといったことについて述べる。
215 内部動作や実装の詳細については省略する (ただしそれが動作の理解にどうしても必要なら別)。 通常の場合について記述する。
216 プログラムのコマンドライン・オプションの説明には、 \fBオプション\fP のセクションを用いる。
218 システムコールやライブラリ関数の新しい動作や新しいフラグについて説明する際は、 変更が取り込まれたカーネルや C
219 ライブラリのバージョンを注記に入れるように気を付けること。 フラグにこの情報の注記を入れる方法としては、推奨される方法は、 以下のように \fB.TP\fP
220 リストの一部にすることである (この例はシステムコールの新しいフラグの場合)。
223 \fBXYZ_FLAG\fP (Linux 3.7 以降)
227 バージョン情報を入れておくのは、 古いバージョンのカーネルや C ライブラリを使わざるを得ないユーザにとって、 特に有用である
228 (例えば、組み込みシステムではよくあることである)。
230 \fBオプション (OPTIONS)\fP
231 プログラムが受け付けるコマンドライン・オプションとその場合プログラムの振舞いがどう変わるかの説明。
235 .\" describes the grammar of any sublanguage this implements.
236 このセクションはセクション 1 と 8 のマニュアルページにだけ登場すべきである。
238 \fB終了ステータス (EXIT STATUS)\fP
239 プログラムの終了ステータスの値とそれらの値に対応する状況の一覧。
241 このセクションはセクション 1 と 8 のマニュアルページにだけ登場すべきである。
243 \fB返り値 (RETURN VALUE)\fP
244 セクション 2 と 3 のページの場合、このセクションに ライブラリルーチンが呼び出し元に返す値のリストを記載する。
245 それらの値が返された場合の状態に対する説明も書く。
248 セクション 2 と 3 のマニュアルページでは、 エラーが発生した場合に \fIerrno\fP に設定される可能性がある値のリストを記載する。
249 リストには、エラーの値とエラーの原因についての情報を書く。
251 「エラーリストはアルファベット順にすべきである。」
253 \fB環境変数 (ENVIRONMENT)\fP
254 プログラムや関数に影響する環境変数の一覧と、それらの影響の説明。
257 プログラムや関数が用いるファイルの一覧。 設定ファイル、起動ファイル、プログラムが直接操作するファイルなど。
259 .\" May 07: Almost no current man pages have a DIAGNOSTICS section;
260 .\" "RETURN VALUE" or "EXIT STATUS" is preferred.
263 .\" gives an overview of the most common error messages and how to
265 .\" You don't need to explain system error messages
266 .\" or fatal signals that can appear during execution of any program
267 .\" unless they're special in some way to the program.
269 .\" May 07: Almost no current man pages have a SECURITY section.
272 .\"discusses security issues and implications.
273 .\"Warn about configurations or environments that should be avoided,
274 .\"commands that may have security implications, and so on, especially
275 .\"if they aren't obvious.
276 .\"Discussing security in a separate section isn't necessary;
277 .\"if it's easier to understand, place security information in the
278 .\"other sections (such as the
283 .\" However, please include security information somewhere!
284 これらのファイルのファイル名はフルパスで記載し、 ディレクトリの部分はユーザーの好みに合わせて インストール処理で変更できるようにする。
285 多くのプログラムではデフォルトのインストール先は \fI/usr/local\fP である。したがってベースとなるマニュアルページでも
286 \fI/usr/local\fP が使われていることが多いだろう。
288 \fB属性 (ATTRIBUTES)\fP
289 そのページで説明している関数の種々の属性の概要を、サブセクションに分けて説明する。
295 \fBマルチスレッディング (pthreads(7) 参照)\fP
296 このサブセクションでは、マルチスレッドアプリケーションに関連する属性について説明する。
301 その関数が取り消しポイント (cancellation point) かどうか。
303 その関数が非同期で安全にキャンセルできるか (async\-cancel\-safe かどうか)。
306 これらの属性の詳細は \fBpthreads\fP(7) で説明されている。
309 \fBバージョン (VERSIONS)\fP
310 システムコールやライブラリ関数が登場したり、動作の重要な変更が行われた、 Linux カーネルや glibc のバージョンについての簡潔な概要。
312 一般に、全ての新しいインターフェイスは、マニュアルページに 「バージョン」の節を設けるべきである。
313 残念なことに、多くの既存のマニュアルページにこの情報は含まれていない (これらのページが書かれた時点ではそのようなポリシーはなかったからである)。
314 これを改善するパッチは歓迎されるが、 新しいコードを書くプログラマの観点からすれば、 おそらくこの情報が重要になるのは、 Linux 2.4
315 以降で追加されたカーネルインターフェイス (カーネル 2.2 からの変更) と glibc バージョン 2.1 以降で追加されたライブラリ関数
316 (glibc 2.0 からの変更) についてのみであろう。
318 \fBsyscalls\fP(2) マニュアルページにも、いろいろなシステムコールが初めて登場した カーネルバージョンについての情報が書かれている。
320 \fB準拠 (CONFORMING TO)\fP
321 そのマニュアルページで説明している関数やコマンドに関連する標準規格や慣習について説明。
323 様々な標準を示すのに適した用語は \fBstandards\fP(7) に見出しでリストになっている。
325 セクション 2 や 3 のページでは、このセクションで システムコールや関数が準拠する POSIX.1 のバージョンと、 C99
326 で規定されているかに触れるべきである。 (SUS, SUSv2, XPG などの他の標準規格や、SVr4 や 4.xBSD の実装標準に
327 ついては、説明しているコールがこれらの規格で規定されており POSIX.1 の現行バージョンで規定されていない場合以外は、
330 そのコールがどの標準にも基づいていないが、 他のシステムで広く存在する場合は、その旨を記載すること。 そのコールが Linux
333 (そうなっているページが多いが) このセクションの内容が標準のリスト だけの場合、リストの最後にピリオド (\(aq.\(aq) を置くこと。
338 セクション 2 と 3 のマニュアルページでは、 \fILinux での注意 (Linux Notes)\fP や \fIglibc での注意 (Glibc
339 Notes)\fP という名前のサブセクション (\fBSS\fP) を設けると便利なこともある。
341 セクション 2 では、 システムコールに対する C
342 ライブラリのラッパー関数とカーネルが提供する素のシステムコールのインタフェースの間で違いがある場合に、その違いを説明する注記を記載する際には \fIC
343 ライブラリとカーネル ABI の違い\fP という見出しを使うこと。
346 制限、知られている欠陥や不便な点、その他不思議な動作など。
349 この関数、ファイル、コマンドをどのように使うかを示す、1〜2 個の例。
351 サンプルプログラムを書く際の詳細は 以下の「サンプルプログラム」の節を参照のこと。
356 \fB著者セクションは極力使用しないこと。\fP 一般的には、著者のリストを各ページに撒き散らさない方がよい
357 (時間がたつと、作者のリストは膨大になる可能性がある)。 マニュアルページを新規に書いたり、大幅に修正を行った場合には、
358 ソースファイルにコメントとして著作権表示を追加すること。 あなたがデバイスドライバの作者で、バグを報告するためのアドレスを
359 載せたい場合は、「バグ」セクションの後ろにこのセクションを配置すること。
361 \fB関連項目 (SEE ALSO)\fP
362 関連するマニュアルページのコンマ区切りのリスト。 可能なら関連する他の文書も書く。
364 リストは、 セクション番号順に、セクション内ではアルファベット順で記載する。 このリストの末尾にピリオドを置かないこと。
366 関連項目のリストに長いマニュアルページ名が多く含まれる場合には、出力を見やすくするために \fI.ad l\fP (右揃えをしない) や \fI.nh\fP
367 (ハイフンによる折り返しをしない) を活用するとよい。個々のページ名のハイフンによる折り返しは、単語の前に "\e%" を付けることで防ぐことができる。
369 FOSS プロジェクトやそのドキュメントは本質的に分散して自律的に行われるので、
370 「関連項目」セクションに他のプロジェクトが提供するマニュアルページへの参照を含める必要がときとしてあり、多くの場合は含めるのが望ましい場合がある。
372 以下の節では\fIman\-pages\fPプロジェクトで推奨のスタイルについて説明している。 ここで触れられていない点については、"the Chicago
373 Manual of Style" がたいていはよい情報源になるだろう。
374 また、すでに使用されているスタイルについてはプロジェクトのソースツリーを検索してみてほしい。
375 (訳注:この章では英語の原文でのスタイルについて説明しており、日本語マニュアルにはあわない点もあるため、具体例などは英語のままとしている箇所もあります。)
377 可能な限り、マニュアルページの文章では性別の区別のない表現を使用すること。 性別に区別のない単数形の代名詞として "they" ("them",
378 "themself", "their") を使用してもよい。
381 関数に対しては、引き数には常にイタリック体を用いる。 「たとえ書式 (SYNOPSIS) セクションであっても、このルールに従う」
384 \fB int myfunction(int \fP\fIargc\fP\fB, char **\fP\fIargv\fP\fB);\fP
386 引き数名といった変数名はイタリック体を指定すべきである。
388 ファイル名 (パス名、またはヘッダーファイルへの参照) は常にイタリック体にする (例: \fI<stdio.h>\fP)。 ただし、書式
389 (SYNOPSIS) セクションは例外で、 インクルードファイルはボールドにする (例: \fB#include <stdio.h>\fP)。
390 標準のインクルードヘッダファイルを参照する際は、 通常の C 言語と同様に山括弧でヘッダファイルを囲ぬで指定する (例:
393 通常、大文字で表現する特殊マクロはボールドで表す (例えば \fBMAXINT\fP)。 例外として NULL はボールドにしない。
395 エラーコードのリストを列挙する時には、コードはボールドで表す (このリストには通常 \fB\&.TP\fP マクロを用いる)。
397 完全なコマンドは、長い場合には、例に示すように 字下げした行にコマンドだけを記載し、コマンドの前後には空行を置くべきである。
405 コマンドが短い場合は、 \fIman 7 man\-pages\fP のようにイタリック体で文中に埋め込んで記載してもよい。
406 この場合、コマンド内の適切な位置に、改行できないスペース ("\e\ ") を使うとよいかもしれない。 コマンドオプションも (\fI\-l\fP のように)
409 式は、専用の字下げした行に記載しない場合、イタリック体を指定すること。 繰り返しになるが、式を通常の文中に埋め込む場合にも、
412 そのマニュアルページの説明対象への参照は、ボールドで名前を記載する。 対象が関数 (つまり、セクション 2 や 3 のページ) の場合、
413 名前の後ろにローマンフォント (通常のフォント) で丸括弧の対を続ける。 例えば、 \fBfcntl\fP(2) のマニュアルページでは、説明対象への参照は
414 \fBfcntl\fP() のように記載する。 マニュアルページのソースファイルには次のように記載するのが望ましい:
420 ("\efB...\efP()" よりも、この形式を使うこと。 これにより、マニュアルページのソースファイルを解釈するツールを 書くのが簡単になる。)
422 別のマニュアルページへの参照は、ボールドで名前を記載し、 それに続けてセクション番号を「必ず」書く。セクション番号は ローマンフォント
423 (通常のフォント) で書き、スペースは入れない (例: \fBintro\fP(2))。 マニュアルページのソースファイルには次のように記載するのが望ましい:
429 (相互参照にセクション番号を含めておくと、 \fBman2html\fP といったツールがページ間のハイパーリンクを適切に生成できる。)
431 制御文字は太字で引用符なしで表記すること。 例えば \fB^X\fP。
433 リリース 2.59 からだが、 \fIman\-pages\fP はアメリカ英語の綴りの慣習に従っている
434 (以前はイギリス英語とアメリカ英語が基準もなく混在して使われていた)。 新しいページやパッチは全てこの慣習に従って下さい。
436 よく知られた綴りの違い以外に、微妙な違いもいくつか見られる。
438 アメリカ英語では "backward", "upward", "toward" を使う傾向にあるが、イギリス英語では "backwards",
439 "upwards", "towards" などを使う方が多い。
441 BSD バージョン番号の伝統的な表記方法は \fIx.yBSD\fP である (\fIx.y\fP はバージョン番号; 例: 4.2BSD)。 \fIBSD 4.3\fP
444 サブセクション ("SS") 見出しでは、最初の単語だけ先頭文字を大文字にし、残りの単語は小文字にすること。但し、英語の用法 (例えば、固有名詞)
445 やプログラミング言語の要件 (例えば、識別子の名前) などで別の表記をする場合はこの限りではない。
447 \&.SS Unicode under Linux
449 .SS 構造体の定義、シェルのセッションログなどの字下げ、など
450 構造体の定義やシェルのセッションログなどを本文中に記載する際は、 スペース 4個分の字下げを行う (つまり、ブロックを \fI.in\ +4n\fP と
453 以下の表にマニュアルページでの使用が推奨される用語を示す。これらは主にマニュアルページ間での一貫性を保つためである。
463 For the UNIX Epoch (00:00:00, 1 Jan 1970 UTC)
466 filesystem file system
469 lowercase lower case, lower\-case
471 pseudoterminal pseudo\-terminal
481 saved set\-group\-ID T{
485 saved set\-user\-ID T{
489 set\-group\-ID set\-GID, setgid
490 set\-user\-ID set\-UID, setuid
501 uppercase upper case, upper\-case
508 以下の\fI修飾子としての複合語におけるハイフン\fPの議論も参照。
510 以下の表にマニュアルページでの使用を避けるべき用語を示す。 推奨される表現も合わせて記載している。
511 これらは主にマニュアルページ間での一貫性を保つためである。
519 8\-bit, 16\-bit なども同様
521 current process calling process T{
522 カーネルプログラマーがマニュアルページを書く際によくする間違い
525 man page, manual page
527 minus infinity negative infinity
528 non\-root unprivileged user
529 non\-superuser unprivileged user
530 nonprivileged unprivileged
532 plus infinity positive infinity
539 商標については正しい綴りと大文字小文字を使うこと。以下は時々綴りの間違いがある商標の正しい綴りのリストである。
545 .SS "NULL, NUL, ヌルポインター、ヌル文字"
546 \fInull pointer\fP (\fIヌルポインター\fP) は何もないものを指すポインターで、通常は定数 \fINULL\fP で示される。 一方、
547 \fINUL\fP は \fInull byte\fP (\fIヌルバイト\fP、値 0 のバイト) で、 C では文字定数 \fI\(aq\e0\(aq\fP と表現される。
549 ポインターとして推奨される用語は "null pointer" (ヌルポインター) もしくは単に "NULL" である。 "NULL pointer"
552 バイトとして推奨される用語は "null byte" (ヌルバイト) である。 "NUL" と記載するのは避けること。 "NUL" は "NULL"
553 と間違われることが非常に多いからである。 また、 "zero byte" (ゼロバイト) と "null character" (ヌル文字)
554 も避けること。 C の文字列を終端するバイトは "the terminating null byte" (終端ヌルバイト)、
555 文字列の説明として使う場合には "null\-terminated" (ヌル終端された) と記載すべきである。 "NUL\-terminated"
558 ハイパーリンクについては、 \fI.UR\fP/\fI.UE\fP マクロの組を使うこと (\fBgroff_man\fP(7)
559 参照)。ページを以下のようにレンダリングする場合に、このマクロはウェブブラウザーで使用できる正しいハイパーリンクを生成してくれる。
561 BROWSER=firefox man \-H pagename
562 .SS "e.g., i.e., etc., a.k.a. などの使用"
563 一般的には、 "e.g.", "i.e.", "etc.", "a.k.a." などの省略形の使用は避けるべきである。 代わりに完全な形の単語を使うこと
564 ("for example" (例えば), "that is" (つまり), "and so on" (〜など), "also known as"
567 これらの省略形の使用が認められる唯一の場所は、 \fI短い\fP括弧で囲まれた余談 ("(e.g., like this one)") の場合である。
569 ここで記載しているように、これらの省略形では必ずピリオドを入れること。 また、"e.g." と "i.e." では常に後にカンマも付けること。
571 *roff で em によるダッシュ\(emこの部分の両端にある記号\(emを書くには "\e(em" を使う。 (ASCII 端末では em
572 によるダッシュは通常ハイフン 2 つとして表示されるが、別の活版印刷の場合などでは長いダッシュとして表示されることもある。) em
573 によるダッシュの両側にはスペースを\fI置かないこと\fP。
574 .SS 修飾子としての複合語におけるハイフン
575 何かを修飾する際 (すなわち後続の名詞を限定する場合) 複合語にはハイフンを入れること。いくつか例を挙げる。
577 32\-bit value (32 ビット値)
578 command\-line argument (コマンドライン引き数)
579 floating\-point number (浮動小数点数)
580 run\-time check (実行時チェック)
581 user\-space function (ユーザー空間関数)
582 wide\-character string (ワイド文字の文字列)
583 .SS "multi, non, pre, re, sub などとの組み合わせでのハイフン"
584 一般的に最近の英語の傾向では、"multi", "non", "pre", "re", "sub" などの接尾辞の後ろにはハイフンを付けない。
585 これらの接尾辞が単純な接尾語との普通の英語の組み合わせの場合には、 マニュアルページでは基本的にこのルールに従う。
586 以下のリストに推奨される形式での例をいくつか挙げる。
609 接尾語が通常の英単語以外 (商標、固有名詞、頭字語、複合語) と組み合わされる場合は、ハイフンを使うこと。以下に例を挙げる。
616 最後に、"re\-create" と "recreate" は異なる別の動詞である点に注意すること。たいていの場合、使おうと思っているのは前者であろう。
618 本当の意味でのマイナス文字が必要な場合は (\-1 といった数字や \fIls\ \-l\fP
619 といった先頭にダッシュのオプションを記載する場合など)、マニュアルページの原文では以下の表記を使うこと。
623 このガイドラインはサンプルコードの場合にも適用される。
625 ASCII と UTF\-8 の両方で正しくレンダリングされるシングルクォート (一重引用符)
626 を生成するには、マニュアルページの原文では以下の表記を使うこと。
630 ここで \fIC\fP が括弧で囲まれる文字である。このガイドラインはサンプルコードの場合にも適用される。
631 .SS サンプルプログラムとシェルのセッション
632 マニュアルページには、システムコールやライブラリ関数の使い方を示す サンプルプログラムを含めることができる。 その際には、以下の点に留意すべきである。
634 サンプルプログラムは C で記載すること。
636 サンプルプログラムは、 インタフェースについて文章で簡単に説明できる以上のことを示す場合にだけ
637 必要かつ有用である。インタフェースを呼び出す以外に何もしないサンプル プログラムは普通はほとんど役に立たない。
639 サンプルプログラムはかなり短めにすること (100行未満が望ましく、50行未満が理想的である)。
641 サンプルプログラムでは、システムコールやライブラリ関数を呼び出した後で エラーチェックを行うこと。
643 サンプルプログラムは完結していて、 \fIcc\ \-Wall\fP でコンパイルした際に警告なしでコンパイルできること。
645 可能かつ適切な場合には、サンプルプログラムで 入力により動作を変化させるなどの実験を行うとよい
646 (理想的には、コマンドライン引き数や、プログラムが読み込む入力データ 経由で、動作を変化させるのがよい)。
648 サンプルプログラムは、K&R (Kernighan and Ritchie) スタイルで書き、 字下げはスペース 4文字で行う。 (ソースコードで
651 一貫性を保つため、すべてのサンプルプログラムは以下のいずれかで終了すること。
656 プログラムを終了するのに以下を使うのは避けること。
662 プログラムソースの前に説明文がある場合は、\fIプログラムソース\fPの見出しをソースコードの前に付けること。
666 説明文がシェルセッションのログを含む場合は必ずこのようにすること。
668 プログラムの使い方や他のシステムの特徴を示すためにシェルのセッションログを含める場合、
670 セッションログをソースコードの前に置くこと
672 セッションログをスペース 4 つで字下げすること
674 ユーザの入力文をボールドにして、システムが生成する出力と区別できるようにすること
676 サンプルプログラムがどんな風になっていればよいかの例については、 \fBwait\fP(2) と \fBpipe\fP(2) を参照すること。
678 \fIman\-pages\fP パッケージに含まれるマニュアルページの体裁の標準的な例については、 \fBpipe\fP(2) と \fBfcntl\fP(2)
681 \fBman\fP(1), \fBman2html\fP(1), \fBgroff\fP(7), \fBgroff_man\fP(7), \fBman\fP(7),
684 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.77 の一部
685 である。プロジェクトの説明とバグ報告に関する情報は
686 http://www.kernel.org/doc/man\-pages/ に書かれている。