Provided by: manpages-ja_0.5.0.0.20221215+dfsg-1_all 
名前
man-pages - Linux の man ページを書く際の決まり事
書式
man [section] title
説明
This page describes the conventions that should be employed when writing man pages for the
Linux man-pages 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, many of
the pages that appear in Sections 3, 4, and 7, and a few of the pages that appear in
Sections 1, 5, and 8 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.
マニュアルページのセクション
マニュアルのセクションは、習慣的に以下のような定義が用いられている:
1 ユーザーコマンド (プログラム)
Commands that can be executed by the user from within a shell.
2 システムコール
Functions which wrap operations performed by the kernel.
3 ライブラリコール
All library functions excluding the system call wrappers (Most of the libc
functions).
4 スペシャルファイル (デバイス)
Files found in /dev which allow to access to devices through the kernel.
5 ファイルのフォーマットと設定ファイル
Describes various human-readable file formats and configuration files.
6 ゲーム
Games and funny little programs available on the system.
7 概要、約束事、その他
Overviews or descriptions of various topics, conventions and protocols, character
set standards, the standard filesystem layout, and miscellaneous other things.
8 システム管理コマンド
mount(8) のような root のみが実行可能なコマンド。
マクロパッケージ
新しいマニュアルページは man(7) で説明されている groff an.tmac パッケージを使って記述すべ
きである。 この方針は一貫性の確保が主な理由である。既存の Linux のマニュアルページ の圧倒
的多数がこれらのマクロを使って記述されている。
ソースファイルの配置に関する決まり事
マニュアルページのソースコードの 1行の長さは 可能な限り 75文字を越えないようにしてほしい。
こうすることで、パッチをメール本文に載せて送る場合に、 メールクライアントによる行折り返し
を回避することができる。
タイトル行
man ページの最初の行は TH コマンドにすべきである。
.TH title section date source manual
The arguments of the command are as follows:
title man ページのタイトル。全部大文字で記載する (例: MAN-PAGES)。
section
man ページが属するセクション番号 (例: 7)。
date man ページに最後に些細でない変更が行われた日付。 (man-pages プロジェクトでは、 この
タイムスタンプの必要な更新はスクリプトで自動的に行われるので、 パッチの中でこの日付
を手動で更新する必要はない。) 日付は YYYY-MM-DD 形式で記載すること。
source コマンド、関数、システムコールの出自。
数少ないセクション 1 と 8 のページの場合、おそらく単に GNU とだけ書くことが多いだろ
う。
システムコールの場合、単に Linux とだけ書く。 (以前の慣習では、マニュアルページを記
載した/内容を確認したカーネルの バージョン番号を記載していた。しかし、バージョン番
号が実際の内容と 一致していることはなく、そのためバージョン番号がないよりも おそら
く悪い形になっていた。 今後は、バージョン番号を含めるのは避けること。)
glibc のライブラリコールや その他の一般的な GNU ライブラリのライブラリコールの場
合、 単に GNU C Library, GNU と書くか、空の文字列を使う。
セクション 4 のページでは Linux を使う。
よくわからない場合は、 Linux とか GNU と書いておく。
manual マニュアルのタイトル (例: man-pages パッケージのセクション 2 および 3 のページの場
合には、 Linux Programmer's Manual を使うこと)。
マニュアルページのセクション
昔から使われてきたセクション名を以下のリストに示す。 これらを使うと良いだろう。 一般的
に、マニュアルページは、少なくとも 色つき のセクションを持つのが望ましい。 新しくマニュア
ルページを作成する際には、だいたい以下のリストに示した 順序でセクションを配置するようにし
てもらいたい。
名前 (NAME)
書式 (SYNOPSIS)
CONFIGURATION [Normally only in Section 4]
説明 (DESCRIPTION)
OPTIONS [Normally only in Sections 1, 8]
EXIT STATUS [Normally only in Sections 1, 8]
返り値 [Normally only in Sections 2, 3]
ERRORS [Typically only in Sections 2, 3]
ENVIRONMENT
ファイル
VERSIONS [Normally only in Sections 2, 3]
ATTRIBUTES [Normally only in Sections 2, 3]
準拠
注意
バグ
例
AUTHORS [Discouraged]
REPORTING BUGS [Not used in man-pages]
COPYRIGHT [Not used in man-pages]
関連項目 (SEE ALSO)
「伝統的に使われてきた見出しが使える場合には、それを使ってほしい。」 この種の一貫性を保つ
ことで、情報を理解しやすくなるからである。 どうしても必要な場合には、理解しやすくなるよう
に独自の見出しを 作ってもよい (特にセクション 4 や 5 のページではこうした方が わかりやすく
なる)。ただし、そうする前に、伝統的な見出しを使い、 そのセクション内にサブセクション (.SS)
を設けることで 対応できないか考えてほしい。
以下のリストでは、上記のセクションのそれぞれの内容について 詳しく説明する。
名前 (NAME)
このマニュアルページの名前
.SH NAME コマンドの後に続ける行の重要な情報については man(7) を参照。この行のすべて
の単語は ("\-" の直後の単語も含め) 小文字にすべきである。但し、英語や技術用語の慣例
として別の記載をする場合はこの限りではない。
書式 (SYNOPSIS)
コマンドや関数インターフェースの簡潔な概要
コマンドに対しては、コマンドや引数 (オプション) の文法を書く。 そのまま書くテキスト
にはボールド体を用い、置き換える引数には イタリック体を用いる。省略可能なオプション
はブラケット ([]) で囲い、 選択肢は縦棒 (|) で区切り、繰り返しには省略符号 (...) を
書く。 関数に対しては、必要なデータ宣言や #include 指定を書き、関数宣言を続ける。
ヘッダーファイルから関数 (や変数) の定義を得るために 機能検査マクロ (feature test
macro) を定義しなければならない場合、 書式 (SYNOPSIS) に必要な機能検査マクロを記載
すべきである。 機能検査マクロについては feature_test_macros(7) で説明されている。
CONFIGURATION
デバイスの設定詳細。
通常、このセクションは 4 章のマニュアルページでのみ登場する。
説明 (DESCRIPTION)
プログラム・関数・フォーマットの動作・目的。
ファイルや標準入力をどのように処理し、標準出力や標準エラー出力を どのように生成する
かといったことについて述べる。 内部動作や実装の詳細については省略する (ただしそれが
動作の理解にどうしても必要なら別)。 通常の場合について記述する。 プログラムのコマン
ドラインオプションの説明には、 オプション のセクションを用いる。
システムコールやライブラリ関数の新しい動作や新しいフラグについて説明する際は、 変更
が取り込まれたカーネルや C ライブラリのバージョンを注記に入れるように気を付けるこ
と。 フラグにこの情報の注記を入れる方法としては、推奨される方法は、 以下のように
.TP リストの一部にすることである (この例はシステムコールの新しいフラグの場合)。
XYZ_FLAG (Linux 3.7 以降)
フラグの説明...
バージョン情報を入れておくのは、 古いバージョンのカーネルや C ライブラリを使わざる
を得ないユーザーにとって、 特に有用である (例えば、組み込みシステムではよくあること
である)。
オプション (OPTIONS)
プログラムが受け付けるコマンドラインオプションとその場合プログラムの振舞いがどう変
わるかの説明。
このセクションはセクション 1 と 8 のマニュアルページにだけ登場すべきである。
終了ステータス (EXIT STATUS)
プログラムの終了ステータスの値とそれらの値に対応する状況の一覧。
このセクションはセクション 1 と 8 のマニュアルページにだけ登場すべきである。
返り値 (RETURN VALUE)
セクション 2 と 3 のページの場合、このセクションに ライブラリルーチンが呼び出し元に
返す値のリストを記載する。 それらの値が返された場合の状態に対する説明も書く。
エラー (ERRORS)
セクション 2 と 3 のマニュアルページでは、 エラーが発生した場合に errno に設定され
る可能性がある値のリストを記載する。 リストには、エラーの値とエラーの原因についての
情報を書く。
Where several different conditions produce the same error, the preferred approach
is to create separate list entries (with duplicate error names) for each of the
conditions. This makes the separate conditions clear, may make the list easier to
read, and allows metainformation (e.g., kernel version number where the condition
first became applicable) to be more easily marked for each condition.
「エラーリストはアルファベット順にすべきである。」
環境変数 (ENVIRONMENT)
プログラムや関数に影響する環境変数の一覧と、それらの影響の説明。
ファイル (FILES)
プログラムや関数が用いるファイルの一覧。 設定ファイル、起動ファイル、プログラムが直
接操作するファイルなど。
これらのファイルのファイル名はフルパスで記載し、 ディレクトリの部分はユーザーの好み
に合わせて インストール処理で変更できるようにする。 多くのプログラムではデフォルト
のインストール先は /usr/local である。したがってベースとなるマニュアルページでも
/usr/local が使われていることが多いだろう。
属性 (ATTRIBUTES)
A summary of various attributes of the function(s) documented on this page. See
attributes(7) for further details.
バージョン (VERSIONS)
システムコールやライブラリ関数が登場したり、動作の重要な変更が行われた、 Linux カー
ネルや glibc のバージョンについての簡潔な概要。
一般に、全ての新しいインターフェイスは、マニュアルページに 「バージョン」の節を設け
るべきである。 残念なことに、多くの既存のマニュアルページにこの情報は含まれていない
(これらのページが書かれた時点ではそのようなポリシーはなかったからである)。 これを改
善するパッチは歓迎されるが、 新しいコードを書くプログラマの観点からすれば、 おそら
くこの情報が重要になるのは、 Linux 2.4 以降で追加されたカーネルインターフェイス
(カーネル 2.2 からの変更) と glibc バージョン 2.1 以降で追加されたライブラリ関数
(glibc 2.0 からの変更) についてのみであろう。
syscalls(2) マニュアルページにも、いろいろなシステムコールが初めて登場した カーネ
ルバージョンについての情報が書かれている。
準拠 (CONFORMING TO)
そのマニュアルページで説明している関数やコマンドに関連する標準規格や慣習について説
明。
様々な標準を示すのに適した用語は standards(7) に見出しでリストになっている。
セクション 2 や 3 のページでは、このセクションで システムコールや関数が準拠する
POSIX.1 のバージョンと、 C99 で規定されているかに触れるべきである。 (SUS, SUSv2,
XPG などの他の標準規格や、SVr4 や 4.xBSD の実装標準に ついては、説明しているコール
がこれらの規格で規定されており POSIX.1 の現行バージョンで規定されていない場合以外
は、 あまり深く気にする必要はない。)
そのコールがどの標準にも基づいていないが、 他のシステムで広く存在する場合は、その旨
を記載すること。 そのコールが Linux 固有の場合は、その旨を記載すること。
(そうなっているページが多いが) このセクションの内容が標準のリスト だけの場合、リス
トの最後にピリオド ('.') を置くこと。
注意 (NOTES)
その他の注記。
セクション 2 と 3 のマニュアルページでは、 Linux での注意 (Linux Notes) や glibc で
の注意 (Glibc Notes) という名前のサブセクション (SS) を設けると便利なこともある。
In Section 2, use the heading C library/kernel differences to mark off notes that
describe the differences (if any) between the C library wrapper function for a
system call and the raw system call interface provided by the kernel.
バグ (BUGS)
制限、知られている欠陥や不便な点、その他不思議な動作など。
EXAMPLES
この関数、ファイル、コマンドをどのように使うかを示す、1〜2 個の例。
For details on writing example programs, see Example programs below.
著者 (AUTHORS)
文書やプログラムの著者の一覧。
著者セクションは極力使用しないこと。 一般的には、著者のリストを各ページに撒き散らさ
ない方がよい (時間がたつと、作者のリストは膨大になる可能性がある)。 マニュアルペー
ジを新規に書いたり、大幅に修正を行った場合には、 ソースファイルにコメントとして著作
権表示を追加すること。 あなたがデバイスドライバの作者で、バグを報告するためのアドレ
スを 載せたい場合は、「バグ」セクションの後ろにこのセクションを配置すること。
REPORTING BUGS
The man-pages project doesn't use a REPORTING BUGS section in manual pages.
Information on reporting bugs is instead supplied in the script-generated COLOPHON
section. However, various projects do use a REPORTING BUGS section. it is
recommended to place it near the foot of the page.
COPYRIGHT
The man-pages project doesn't use a COPYRIGHT section in manual pages. Copyright
information is instead maintained in the page source. In pages where this section
is present, it is recommended to place it near the foot of the page, just above SEE
ALSO.
関連項目 (SEE ALSO)
関連するマニュアルページのコンマ区切りのリスト。 可能なら関連する他の文書も書く。
The list should be ordered by section number and then alphabetically by name. Do
not terminate this list with a period.
関連項目のリストに長いマニュアルページ名が多く含まれる場合には、出力を見やすくする
ために .ad l (右揃えをしない) や .nh (ハイフンによる折り返しをしない) を活用すると
よい。個々のページ名のハイフンによる折り返しは、単語の前に "\%" を付けることで防ぐ
ことができる。
FOSS プロジェクトやそのドキュメントは本質的に分散して自律的に行われるので、 「関連
項目」セクションに他のプロジェクトが提供するマニュアルページへの参照を含める必要が
ときとしてあり、多くの場合は含めるのが望ましい場合がある。
スタイルガイド
以下の節ではman-pagesプロジェクトで推奨のスタイルについて説明している。 ここで触れられてい
ない点については、"the Chicago Manual of Style" がたいていはよい情報源になるだろう。 ま
た、すでに使用されているスタイルについてはプロジェクトのソースツリーを検索してみてほしい。
(訳注：この章では英語の原文でのスタイルについて説明しており、日本語マニュアルにはあわない
点もあるため、具体例などは英語のままとしている箇所もあります。)
性別の区別のない表現の使用
可能な限り、マニュアルページの文章では性別の区別のない表現を使用すること。 性別に区別のな
い単数形の代名詞として "they" ("them", "themself", "their") を使用してもよい。
Formatting conventions for manual pages describing commands
For manual pages that describe a command (typically in Sections 1 and 8), the arguments
are always specified using italics, even in the SYNOPSIS section.
The name of the command, and its options, should always be formatted in bold.
Formatting conventions for manual pages describing functions
For manual pages that describe functions (typically in Sections 2 and 3), the arguments
are always specified using italics, even in the SYNOPSIS section, where the rest of the
function is specified in bold:
int myfunction(int argc, char **argv);
引数名といった変数名はイタリック体を指定すべきである。
Any reference to the subject of the current manual page should be written with the name in
bold followed by a pair of parentheses in Roman (normal) font. For example, in the
fcntl(2) man page, references to the subject of the page would be written as: fcntl().
The preferred way to write this in the source file is:
.BR fcntl ()
("\fB...\fP()" よりも、この形式を使うこと。 これにより、マニュアルページのソースファイルを
解釈するツールを 書くのが簡単になる。)
Use semantic newlines
In the source of a manual page, new sentences should be started on new lines, and long
sentences should split into lines at clause breaks (commas, semicolons, colons, and so
on). This convention, sometimes known as "semantic newlines", makes it easier to see the
effect of patches, which often operate at the level of individual sentences or sentence
clauses.
Formatting conventions (general)
Paragraphs should be separated by suitable markers (usually either .PP or .IP). Do not
separate paragraphs using blank lines, as this results in poor rendering in some output
formats (such as PostScript and PDF).
ファイル名 (パス名、またはヘッダーファイルへの参照) は常にイタリック体にする (例:
<stdio.h>)。 ただし、書式 (SYNOPSIS) セクションは例外で、 インクルードファイルはボールドに
する (例: #include <stdio.h>)。 標準のインクルードヘッダーファイルを参照する際は、 通常の
C 言語と同様に山括弧でヘッダーファイルを囲ぬで指定する (例： <stdio.h>)。
通常、大文字で表現する特殊マクロはボールドで表す (例えば MAXINT)。 例外として NULL はボー
ルドにしない。
エラーコードのリストを列挙する時には、コードはボールドで表す (このリストには通常 .TP マク
ロを用いる)。
完全なコマンドは、長い場合には、例に示すように 字下げした行にコマンドだけを記載し、コマン
ドの前後には空行を置くべきである。
man 7 man-pages
コマンドが短い場合は、 man 7 man-pages のようにイタリック体で文中に埋め込んで記載してもよ
い。 この場合、コマンド内の適切な位置に、改行できないスペース ("\ ") を使うとよいかもしれ
ない。 コマンドオプションも (-l のように) イタリック体で記載すべきである。
式は、専用の字下げした行に記載しない場合、イタリック体を指定すること。 繰り返しになる
が、式を通常の文中に埋め込む場合にも、 改行できないスペースを使うとよいだろう。
When showing example shell sessions, user input should be formatted in bold, for example
$ date
Thu Jul 7 13:01:27 CEST 2016
別のマニュアルページへの参照は、ボールドで名前を記載し、 それに続けてセクション番号を「必
ず」書く。セクション番号は ローマンフォント (通常のフォント) で書き、スペースは入れない
(例: intro(2))。 マニュアルページのソースファイルには次のように記載するのが望ましい:
.BR intro (2)
(相互参照にセクション番号を含めておくと、 man2html といったツールがページ間のハイパーリン
クを適切に生成できる。)
Control characters should be written in bold face, with no quotes; for example, ^X.
綴り (spelling)
リリース 2.59 からだが、 man-pages はアメリカ英語の綴りの慣習に従っている (以前はイギリス
英語とアメリカ英語が基準もなく混在して使われていた)。 新しいページやパッチは全てこの慣習に
従って下さい。
よく知られた綴りの違い以外に、微妙な違いもいくつか見られる。
* アメリカ英語では "backward", "upward", "toward" を使う傾向にあるが、イギリス英語では
"backwards", "upwards", "towards" などを使う方が多い。
BSD バージョン番号
BSD バージョン番号の伝統的な表記方法は x.yBSD である (x.y はバージョン番号; 例: 4.2BSD)。
BSD 4.3 といった表記は避けること。
大文字表記
サブセクション ("SS") 見出しでは、最初の単語だけ先頭文字を大文字にし、残りの単語は小文字に
すること。但し、英語の用法 (例えば、固有名詞) やプログラミング言語の要件 (例えば、識別子の
名前) などで別の表記をする場合はこの限りではない。
.SS Unicode under Linux
構造体の定義、シェルのセッションログなどの字下げ、など
When structure definitions, shell session logs, and so on are included in running text,
indent them by 4 spaces (i.e., a block enclosed by .in +4n and .in), format them using the
.EX and EE macros, and surround them with suitable paragraph markers (either .PP or .IP).
For example:
.PP
.in +4n
.EX
int
main(int argc, char *argv[])
{
return 0;
}
.EE
.in
.PP
推奨用語
以下の表にマニュアルページでの使用が推奨される用語を示す。これらは主にマニュアルページ間で
の一貫性を保つためである。
用語 使用を避ける単語 備考
─────────────────────────────────────────────────────────────────────────
bit mask bitmask
built-in builtin
Epoch epoch For the UNIX Epoch
(00:00:00, 1 Jan 1970
UTC)
filename file name
filesystem file system
hostname host name
inode i-node
lowercase lower case, lower-case
nonzero non-zero
pathname path name
pseudoterminal pseudo-terminal
privileged port reserved port, system
port
real-time realtime, real time
run time runtime
saved set-group-ID saved group ID, saved
set-GID
saved set-user-ID saved user ID, saved
set-UID
set-group-ID set-GID, setgid
set-user-ID set-UID, setuid
superuser super user, super-user
superblock super block, super-block
timestamp time stamp
timezone time zone
uppercase upper case, upper-case
usable useable
user space userspace
username user name
x86-64 x86_64 Except if referring to
result of "uname -m" or
similar
zeros zeroes
以下の修飾子としての複合語におけるハイフンの議論も参照。
使用を避ける用語
以下の表にマニュアルページでの使用を避けるべき用語を示す。 推奨される表現も合わせて記載し
ている。 これらは主にマニュアルページ間での一貫性を保つためである。
使用を避ける 使用を推奨 備考
───────────────────────────────────────────────────────────────────
32bit 32-bit 8-bit, 16-bit なども同様
current process calling process カーネルプログラマーがマ
ニュアルページを書く際に
よくする間違い
manpage man page, manual page
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
商標
商標については正しい綴りと大文字小文字を使うこと。以下は時々綴りの間違いがある商標の正しい
綴りのリストである。
DG/UX
HP-UX
UNIX
UnixWare
NULL, NUL, ヌルポインター、ヌル文字
null pointer (ヌルポインター) は何もないものを指すポインターで、通常は定数 NULL で示され
る。 一方、 NUL は null byte (ヌルバイト、値 0 のバイト) で、 C では文字定数 '\0' と表現さ
れる。
ポインターとして推奨される用語は "null pointer" (ヌルポインター) もしくは単に "NULL" であ
る。 "NULL pointer" と記載するのは避けること。
バイトとして推奨される用語は "null byte" (ヌルバイト) である。 "NUL" と記載するのは避ける
こと。 "NUL" は "NULL" と間違われることが非常に多いからである。 また、 "zero byte" (ゼロバ
イト) と "null character" (ヌル文字) も避けること。 C の文字列を終端するバイトは "the
terminating null byte" (終端ヌルバイト)、 文字列の説明として使う場合には "null-terminated"
(ヌル終端された) と記載すべきである。 "NUL-terminated" の使用は避けること。
ハイパーリンク
ハイパーリンクについては、 .UR/.UE マクロの組を使うこと (groff_man(7) 参照)。ページを以下
のようにレンダリングする場合に、このマクロはウェブブラウザーで使用できる正しいハイパーリン
クを生成してくれる。
BROWSER=firefox man -H pagename
e.g., i.e., etc., a.k.a. などの使用
In general, the use of abbreviations such as "e.g.", "i.e.", "etc.", "cf.", and "a.k.a."
should be avoided, in favor of suitable full wordings ("for example", "that is", "and so
on", "compare to", "also known as").
これらの省略形の使用が認められる唯一の場所は、 短い括弧で囲まれた余談 ("(e.g., like this
one)") の場合である。
ここで記載しているように、これらの省略形では必ずピリオドを入れること。 また、"e.g." と
"i.e." では常に後にカンマも付けること。
em によるダッシュ
*roff で em によるダッシュ—この部分の両端にある記号—を書くには "\(em" を使う。 (ASCII 端末
では em によるダッシュは通常ハイフン 2 つとして表示されるが、別の活版印刷の場合などでは長
いダッシュとして表示されることもある。) em によるダッシュの両側にはスペースを置かないこ
と。
修飾子としての複合語におけるハイフン
何かを修飾する際 (すなわち後続の名詞を限定する場合) 複合語にはハイフンを入れること。いくつ
か例を挙げる。
32-bit value (32 ビット値)
command-line argument (コマンドライン引数)
floating-point number (浮動小数点数)
run-time check (実行時チェック)
user-space function (ユーザー空間関数)
wide-character string (ワイド文字の文字列)
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" は異なる別の動詞である点に注意すること。たいていの場
合、使おうと思っているのは前者であろう。
Generating optimal glyphs
Where a real minus character is required (e.g., for numbers such as -1, for man page cross
references such as utf-8(7), or when writing options that have a leading dash, such as in
ls -l), use the following form in the man page source:
\-
このガイドラインはサンプルコードの場合にも適用される。
To produce unslanted single quotes that render well in ASCII, UTF-8, and PDF, use "\(aq"
("apostrophe quote"); for example
\(aqC\(aq
ここで C が括弧で囲まれる文字である。このガイドラインはサンプルコードの場合にも適用され
る。
Where a proper caret (^) that renders well in both a terminal and PDF is required, use
"\(ha". This is especially necessary in code samples, to get a nicely rendered caret when
rendering to PDF.
Using a naked "~" character results in a poor rendering in PDF. Instead use "\(ti". This
is especially necessary in code samples, to get a nicely rendered tilde when rendering to
PDF.
サンプルプログラムとシェルのセッション
マニュアルページには、システムコールやライブラリ関数の使い方を示す サンプルプログラムを含
めることができる。 その際には、以下の点に留意すべきである。
* サンプルプログラムは C で記載すること。
* サンプルプログラムは、 インターフェースについて文章で簡単に説明できる以上のことを示す場
合にだけ 必要かつ有用である。インターフェースを呼び出す以外に何もしないサンプル プログ
ラムは普通はほとんど役に立たない。
* Example programs should ideally be short (e.g., a good example can often be provided in
less than 100 lines of code), though in some cases longer programs may be necessary to
properly illustrate the use of an API.
* Expressive code and useful comments are appreciated.
* サンプルプログラムでは、システムコールやライブラリ関数を呼び出した後で エラーチェックを
行うこと。
* サンプルプログラムは完結していて、 cc -Wall でコンパイルした際に警告なしでコンパイルで
きること。
* 可能かつ適切な場合には、サンプルプログラムで 入力により動作を変化させるなどの実験を行う
とよい (理想的には、コマンドライン引数や、プログラムが読み込む入力データ 経由で、動作を
変化させるのがよい)。
* Example programs should be laid out according to Kernighan and Ritchie style, with
4-space indents. (Avoid the use of TAB characters in source code!) The following
command can be used to format your source code to something close to the preferred
style:
indent -npro -kr -i4 -ts4 -sob -l72 -ss -nut -psl prog.c
* 一貫性を保つため、すべてのサンプルプログラムは以下のいずれかで終了すること。
exit(EXIT_SUCCESS);
exit(EXIT_FAILURE);
プログラムを終了するのに以下を使うのは避けること。
exit(0);
exit(1);
return n;
* プログラムソースの前に説明文がある場合は、プログラムソースの見出しをソースコードの前に
付けること。
.SS プログラムのソース
説明文がシェルセッションのログを含む場合は必ずこのようにすること。
プログラムの使い方や他のシステムの特徴を示すためにシェルのセッションログを含める場合、
* セッションログをソースコードの前に置くこと
* セッションログをスペース 4 つで字下げすること
* ユーザーの入力文をボールドにして、システムが生成する出力と区別できるようにすること
サンプルプログラムがどんな風になっていればよいかの例については、 wait(2) と pipe(2) を参
照すること。
例
man-pages パッケージに含まれるマニュアルページの体裁の標準的な例については、 pipe(2) と
fcntl(2) を参照すること。
関連項目
man(1), man2html(1), attributes(7), groff(7), groff_man(7), man(7), mdoc(7)
この文書について
この man ページは Linux man-pages プロジェクトのリリース 5.10 の一部である。プロジェクトの
説明とバグ報告に関する情報は https://www.kernel.org/doc/man-pages/ に書かれている。