Manpages

名 前

man−pages − Linux の man ペ ー ジ を 書 く 際 の 決 ま り 事

書 式

man [section] title

説 明

こ の ペ ー ジ で は 、 Linux man−pages プ ロ ジ ェ ク ト の マ ニ ュ ア ル ペ ー ジ を 書 く 際 に 従 う べ き 決 ま り 事 に つ い て 説 明 す る 。 Linux man−pages プ ロ ジ ェ ク ト は Linux カ ー ネ ル お よ び GNU C ラ イ ブ ラ リ が 提 供 す る ユ ー ザ ー 空 間 API の ド キ ュ メ ン ト 作 成 を 行 っ て い る 。 Linux シ ス テ ム の マ ニ ュ ア ル ペ ー ジ の セ ク シ ョ ン 2 の ペ ー ジ の ほ と ん ど と 、 セ ク シ ョ ン 3, 4, 5, 7 の 多 く の ペ ー ジ が 、 こ の プ ロ ジ ェ ク ト に よ り 提 供 さ れ て い る 。 こ の ペ ー ジ で 説 明 さ れ て い る 決 ま り 事 は 、 他 の プ ロ ジ ェ ク ト の マ ニ ュ ア ル ペ ー ジ を 書 く 作 者 に も 役 立 つ こ と だ ろ う 。 マ ニ ュ ア ル ペ ー ジ の セ ク シ ョ ン マ ニ ュ ア ル の セ ク シ ョ ン は 、 習 慣 的 に 以 下 の よ う な 定 義 が 用 い ら れ て い る :

1 コ マ ン ド (プ ロ グ ラ ム ) シ ェ ル の 中 か ら ユ ー ザ ー が 実 行 で き る コ マ ン ド 。
2 シ ス テ ム コ ー ル
カ ー ネ ル が 処 理 し な け れ ば な ら な い 関 数 。
3 ラ イ ブ ラ リ コ ー ル

libc の 関 数 の 大 部 分 。

4 ス ペ シ ャ ル フ ァ イ ル (デ バ イ ス )

/dev 以 下 に あ る フ ァ イ ル 。

5 フ ァ イ ル の フ ォ ー マ ッ ト と 規 約

/etc/passwd な ど の 人 が 読 め る フ ァ イ ル の フ ォ ー マ ッ ト 。

6 ゲ ー ム

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

mount(8) の よ う な root の み が 実 行 可 能 な コ マ ン ド 。 マ ク ロ パ ッ ケ ー ジ 新 し い マ ニ ュ ア ル ペ ー ジ は man(7) で 説 明 さ れ て い る groff an.tmac パ ッ ケ ー ジ を 使 っ て 記 述 す べ き で あ る 。 こ の 方 針 は 一 貫 性 の 確 保 が 主 な 理 由 で あ る 。 既 存 の Linux の マ ニ ュ ア ル ペ ー ジ の 圧 倒 的 多 数 が こ れ ら の マ ク ロ を 使 っ て 記 述 さ れ て い る 。 ソ ー ス フ ァ イ ル の 配 置 に 関 す る 決 ま り 事 マ ニ ュ ア ル ペ ー ジ の ソ ー ス コ ー ド の 1行 の 長 さ は 可 能 な 限 り 75文 字 を 越 え な い よ う に し て ほ し い 。 こ う す る こ と で 、 パ ッ チ を メ ー ル 本 文 に 載 せ て 送 る 場 合 に 、 メ ー ル ク ラ イ ア ン ト に よ る 行 折 り 返 し を 回 避 す る こ と が で き る 。 新 し い 文 は 行 頭 か ら 開 始 す る 。 こ れ に よ り 、 パ ッ チ の 内 容 を 確 認 し や す く な る 。 パ ッ チ は 文 単 位 で あ る こ と が 多 い か ら で あ る 。 タ イ ト ル 行

man ペ ー ジ の 最 初 の 行 は TH コ マ ン ド に す べ き で あ る 。

.TH title section date source manual 個 々 の 説 明 :

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 を 使 う こ と )。 マ ニ ュ ア ル ペ ー ジ の セ ク シ ョ ン 昔 か ら 使 わ れ て き た セ ク シ ョ ン 名 を 以 下 の リ ス ト に 示 す 。 こ れ ら を 使 う と 良 い だ ろ う 。 一 般 的 に 、 マ ニ ュ ア ル ペ ー ジ は 、 少 な く と も 色 つ き の セ ク シ ョ ン を 持 つ の が 望 ま し い 。 新 し く マ ニ ュ ア ル ペ ー ジ を 作 成 す る 際 に は 、 だ い た い 以 下 の リ ス ト に 示 し た 順 序 で セ ク シ ョ ン を 配 置 す る よ う に し て も ら い た い 。 名 前 書 式 設 定
[通 常 は セ ク シ ョ ン 4 の み ] 説 明 オ プ シ ョ ン
[通 常 は セ ク シ ョ ン 1, 8 の み ] 終 了 ス テ ー タ ス
[通 常 は セ ク シ ョ ン 1, 8 の み ] 返 り 値
[通 常 は セ ク シ ョ ン 2, 3 の み ] エ ラ ー
[た い て い は セ ク シ ョ ン 2, 3 の み ] 環 境 変 数 フ ァ イ ル バ ー ジ ョ ン
[通 常 は セ ク シ ョ ン 2, 3 の み ] 属 性
[通 常 は セ ク シ ョ ン 2, 3 の み ] 準 拠 注 意
/備 考 バ グ 例 関 連 項 目 「 伝 統 的 に 使 わ れ て き た 見 出 し が 使 え る 場 合 に は 、 そ れ を 使 っ て ほ し い 。 」 こ の 種 の 一 貫 性 を 保 つ こ と で 、 情 報 を 理 解 し や す く な る か ら で あ る 。 ど う し て も 必 要 な 場 合 に は 、 理 解 し や す く な る よ う に 独 自 の 見 出 し を 作 っ て も よ い (特 に セ ク シ ョ ン 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 に 設 定 さ れ る 可 能 性 が あ る 値 の リ ス ト を 記 載 す る 。 リ ス ト に は 、 エ ラ ー の 値 と エ ラ ー の 原 因 に つ い て の 情 報 を 書 く 。 「 エ ラ ー リ ス ト は ア ル フ ァ ベ ッ ト 順 に す べ き で あ る 。 」 環 境 変 数
(ENVIRONMENT)
プ ロ グ ラ ム や 関 数 に 影 響 す る 環 境 変 数 の 一 覧 と 、 そ れ ら の 影 響 の 説 明 。 フ ァ イ ル
(FILES)
プ ロ グ ラ ム や 関 数 が 用 い る フ ァ イ ル の 一 覧 。 設 定 フ ァ イ ル 、 起 動 フ ァ イ ル 、 プ ロ グ ラ ム が 直 接 操 作 す る フ ァ イ ル な ど 。 こ れ ら の フ ァ イ ル の フ ァ イ ル 名 は フ ル パ ス で 記 載 し 、 デ ィ レ ク ト リ の 部 分 は ユ ー ザ ー の 好 み に 合 わ せ て イ ン ス ト ー ル 処 理 で 変 更 で き る よ う に す る 。 多 く の プ ロ グ ラ ム で は デ フ ォ ル ト の イ ン ス ト ー ル 先 は /usr/local で あ る 。 し た が っ て ベ ー ス と な る マ ニ ュ ア ル ペ ー ジ で も /usr/local が 使 わ れ て い る こ と が 多 い だ ろ う 。 属 性
(ATTRIBUTES)
そ の ペ ー ジ で 説 明 し て い る 関 数 の 種 々 の 属 性 の 概 要 を 、 サ ブ セ ク シ ョ ン に 分 け て 説 明 す る 。 以 下 の サ ブ セ ク シ ョ ン が 定 義 さ れ て い る 。 マ ル チ ス レ ッ デ ィ ン グ

(pthreads(7) 参 照 ) こ の サ ブ セ ク シ ョ ン で は 、 マ ル チ ス レ ッ ド ア プ リ ケ ー シ ョ ン に 関 連 す る 属 性 に つ い て 説 明 す る 。

* そ の 関 数 が ス レ ッ ド セ ー フ か ど う か 。

* そ の 関 数 が 取 り 消 し ポ イ ン ト

(cancellation point) か ど う か 。

* そ の 関 数 が 非 同 期 で 安 全 に キ ャ ン セ ル で き る か

(async−cancel−safe か ど う か )。 こ れ ら の 属 性 の 詳 細 は pthreads(7) で 説 明 さ れ て い る 。 バ ー ジ ョ ン

(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) を 設 け る と 便 利 な こ と も あ る 。 セ ク シ ョ ン 2 で は 、 シ ス テ ム コ ー ル に 対 す る C ラ イ ブ ラ リ の ラ ッ パ ー 関 数 と カ ー ネ ル が 提 供 す る 素 の シ ス テ ム コ ー ル の イ ン タ ー フ ェ ー ス の 間 で 違 い が あ る 場 合 に 、 そ の 違 い を 説 明 す る 注 記 を 記 載 す る 際 に は C ラ イ ブ ラ リ と カ ー ネ ル ABI の 違 い と い う 見 出 し を 使 う こ と 。

バ グ (BUGS) 制 限 、 知 ら れ て い る 欠 陥 や 不 便 な 点 、 そ の 他 不 思 議 な 動 作 な ど 。

例 (EXAMPLE) こ の 関 数 、 フ ァ イ ル 、 コ マ ン ド を ど の よ う に 使 う か を 示 す 、

1〜 2 個 の 例 。 サ ン プ ル プ ロ グ ラ ム を 書 く 際 の 詳 細 は 以 下 の 「 サ ン プ ル プ ロ グ ラ ム 」 の 節 を 参 照 の こ と 。 著 者
(AUTHORS)
文 書 や プ ロ グ ラ ム の 著 者 の 一 覧 。 著 者 セ ク シ ョ ン は 極 力 使 用 し な い こ と 。 一 般 的 に は 、 著 者 の リ ス ト を 各 ペ ー ジ に 撒 き 散 ら さ な い 方 が よ い (時 間 が た つ と 、 作 者 の リ ス ト は 膨 大 に な る 可 能 性 が あ る )。 マ ニ ュ ア ル ペ ー ジ を 新 規 に 書 い た り 、 大 幅 に 修 正 を 行 っ た 場 合 に は 、 ソ ー ス フ ァ イ ル に コ メ ン ト と し て 著 作 権 表 示 を 追 加 す る こ と 。 あ な た が デ バ イ ス ド ラ イ バ の 作 者 で 、 バ グ を 報 告 す る た め の ア ド レ ス を 載 せ た い 場 合 は 、 「 バ グ 」 セ ク シ ョ ン の 後 ろ に こ の セ ク シ ョ ン を 配 置 す る こ と 。 関 連 項 目
(SEE ALSO)
関 連 す る マ ニ ュ ア ル ペ ー ジ の コ ン マ 区 切 り の リ ス ト 。 可 能 な ら 関 連 す る 他 の 文 書 も 書 く 。 リ ス ト は 、 セ ク シ ョ ン 番 号 順 に 、 セ ク シ ョ ン 内 で は ア ル フ ァ ベ ッ ト 順 で 記 載 す る 。 こ の リ ス ト の 末 尾 に ピ リ オ ド を 置 か な い こ と 。 関 連 項 目 の リ ス ト に 長 い マ ニ ュ ア ル ペ ー ジ 名 が 多 く 含 ま れ る 場 合 に は 、 出 力 を 見 や す く す る た め に .ad l (右 揃 え を し な い ) や .nh (ハ イ フ ン に よ る 折 り 返 し を し な い ) を 活 用 す る と よ い 。 個 々 の ペ ー ジ 名 の ハ イ フ ン に よ る 折 り 返 し は 、 単 語 の 前 に "\%" を 付 け る こ と で 防 ぐ こ と が で き る 。

FOSS プ ロ ジ ェ ク ト や そ の ド キ ュ メ ン ト は 本 質 的 に 分 散 し て 自 律 的 に 行 わ れ る の で 、 「 関 連 項 目 」 セ ク シ ョ ン に 他 の プ ロ ジ ェ ク ト が 提 供 す る マ ニ ュ ア ル ペ ー ジ へ の 参 照 を 含 め る 必 要 が と き と し て あ り 、 多 く の 場 合 は 含 め る の が 望 ま し い 場 合 が あ る 。

ス タ イ ル ガ イ ド

以 下 の 節 で は man−pagesプ ロ ジ ェ ク ト で 推 奨 の ス タ イ ル に つ い て 説 明 し て い る 。 こ こ で 触 れ ら れ て い な い 点 に つ い て は 、 "the Chicago Manual of Style" が た い て い は よ い 情 報 源 に な る だ ろ う 。 ま た 、 す で に 使 用 さ れ て い る ス タ イ ル に つ い て は プ ロ ジ ェ ク ト の ソ ー ス ツ リ ー を 検 索 し て み て ほ し い 。 (訳 注 : こ の 章 で は 英 語 の 原 文 で の ス タ イ ル に つ い て 説 明 し て お り 、 日 本 語 マ ニ ュ ア ル に は あ わ な い 点 も あ る た め 、 具 体 例 な ど は 英 語 の ま ま と し て い る 箇 所 も あ り ま す 。 ) 性 別 の 区 別 の な い 表 現 の 使 用 可 能 な 限 り 、 マ ニ ュ ア ル ペ ー ジ の 文 章 で は 性 別 の 区 別 の な い 表 現 を 使 用 す る こ と 。 性 別 に 区 別 の な い 単 数 形 の 代 名 詞 と し て "they" ("them", "themself", "their") を 使 用 し て も よ い 。 フ ォ ン ト の 慣 習 関 数 に 対 し て は 、 引 き 数 に は 常 に イ タ リ ッ ク 体 を 用 い る 。 「 た と え 書 式 (SYNOPSIS) セ ク シ ョ ン で あ っ て も 、 こ の ル ー ル に 従 う 」 関 数 の 他 の 部 分 は ボ ー ル ド を 指 定 す る :

int myfunction(int argc, char **argv); 引 き 数 名 と い っ た 変 数 名 は イ タ リ ッ ク 体 を 指 定 す べ き で あ る 。 フ ァ イ ル 名 (パ ス 名 、 ま た は ヘ ッ ダ ー フ ァ イ ル へ の 参 照 ) は 常 に イ タ リ ッ ク 体 に す る (例 : <stdio.h>)。 た だ し 、 書 式 (SYNOPSIS) セ ク シ ョ ン は 例 外 で 、 イ ン ク ル ー ド フ ァ イ ル は ボ ー ル ド に す る (例 : #include <stdio.h>)。 標 準 の イ ン ク ル ー ド ヘ ッ ダ ー フ ァ イ ル を 参 照 す る 際 は 、 通 常 の C 言 語 と 同 様 に 山 括 弧 で ヘ ッ ダ ー フ ァ イ ル を 囲 ぬ で 指 定 す る (例 : <stdio.h>)。 通 常 、 大 文 字 で 表 現 す る 特 殊 マ ク ロ は ボ ー ル ド で 表 す (例 え ば MAXINT)。 例 外 と し て NULL は ボ ー ル ド に し な い 。 エ ラ ー コ ー ド の リ ス ト を 列 挙 す る 時 に は 、 コ ー ド は ボ ー ル ド で 表 す (こ の リ ス ト に は 通 常 .TP マ ク ロ を 用 い る )。 完 全 な コ マ ン ド は 、 長 い 場 合 に は 、 例 に 示 す よ う に 字 下 げ し た 行 に コ マ ン ド だ け を 記 載 し 、 コ マ ン ド の 前 後 に は 空 行 を 置 く べ き で あ る 。

man 7 man−pages コ マ ン ド が 短 い 場 合 は 、 man 7 man−pages の よ う に イ タ リ ッ ク 体 で 文 中 に 埋 め 込 ん で 記 載 し て も よ い 。 こ の 場 合 、 コ マ ン ド 内 の 適 切 な 位 置 に 、 改 行 で き な い ス ペ ー ス ("\ ") を 使 う と よ い か も し れ な い 。 コ マ ン ド オ プ シ ョ ン も (−l の よ う に ) イ タ リ ッ ク 体 で 記 載 す べ き で あ る 。 式 は 、 専 用 の 字 下 げ し た 行 に 記 載 し な い 場 合 、 イ タ リ ッ ク 体 を 指 定 す る こ と 。 繰 り 返 し に な る が 、 式 を 通 常 の 文 中 に 埋 め 込 む 場 合 に も 、 改 行 で き な い ス ペ ー ス を 使 う と よ い だ ろ う 。 そ の マ ニ ュ ア ル ペ ー ジ の 説 明 対 象 へ の 参 照 は 、 ボ ー ル ド で 名 前 を 記 載 す る 。 対 象 が 関 数 (つ ま り 、 セ ク シ ョ ン 2 や 3 の ペ ー ジ ) の 場 合 、 名 前 の 後 ろ に ロ ー マ ン フ ォ ン ト (通 常 の フ ォ ン ト ) で 丸 括 弧 の 対 を 続 け る 。 例 え ば 、 fcntl(2) の マ ニ ュ ア ル ペ ー ジ で は 、 説 明 対 象 へ の 参 照 は fcntl() の よ う に 記 載 す る 。 マ ニ ュ ア ル ペ ー ジ の ソ ー ス フ ァ イ ル に は 次 の よ う に 記 載 す る の が 望 ま し い :

.BR fcntl ()

("\fB...\fP()" よ り も 、 こ の 形 式 を 使 う こ と 。 こ れ に よ り 、 マ ニ ュ ア ル ペ ー ジ の ソ ー ス フ ァ イ ル を 解 釈 す る ツ ー ル を 書 く の が 簡 単 に な る 。 ) 別 の マ ニ ュ ア ル ペ ー ジ へ の 参 照 は 、 ボ ー ル ド で 名 前 を 記 載 し 、 そ れ に 続 け て セ ク シ ョ ン 番 号 を 「 必 ず 」 書 く 。 セ ク シ ョ ン 番 号 は ロ ー マ ン フ ォ ン ト (通 常 の フ ォ ン ト ) で 書 き 、 ス ペ ー ス は 入 れ な い (例 : intro(2))。 マ ニ ュ ア ル ペ ー ジ の ソ ー ス フ ァ イ ル に は 次 の よ う に 記 載 す る の が 望 ま し い :

.BR intro (2)

(相 互 参 照 に セ ク シ ョ ン 番 号 を 含 め て お く と 、 man2html と い っ た ツ ー ル が ペ ー ジ 間 の ハ イ パ ー リ ン ク を 適 切 に 生 成 で き る 。 ) 制 御 文 字 は 太 字 で 引 用 符 な し で 表 記 す る こ と 。 例 え ば ^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 構 造 体 の 定 義 、 シ ェ ル の セ ッ シ ョ ン ロ グ な ど の 字 下 げ 、 な ど 構 造 体 の 定 義 や シ ェ ル の セ ッ シ ョ ン ロ グ な ど を 本 文 中 に 記 載 す る 際 は 、 ス ペ ー ス 4個 分 の 字 下 げ を 行 う (つ ま り 、 ブ ロ ッ ク を .in +4n.in で 囲 む )。 推 奨 用 語 以 下 の 表 に マ ニ ュ ア ル ペ ー ジ で の 使 用 が 推 奨 さ れ る 用 語 を 示 す 。 こ れ ら は 主 に マ ニ ュ ア ル ペ ー ジ 間 で の 一 貫 性 を 保 つ た め で あ る 。

以 下 の 修 飾 子 と し て の 複 合 語 に お け る ハ イ フ ン の 議 論 も 参 照 。 使 用 を 避 け る 用 語 以 下 の 表 に マ ニ ュ ア ル ペ ー ジ で の 使 用 を 避 け る べ き 用 語 を 示 す 。 推 奨 さ れ る 表 現 も 合 わ せ て 記 載 し て い る 。 こ れ ら は 主 に マ ニ ュ ア ル ペ ー ジ 間 で の 一 貫 性 を 保 つ た め で あ る 。

商 標 商 標 に つ い て は 正 し い 綴 り と 大 文 字 小 文 字 を 使 う こ と 。 以 下 は 時 々 綴 り の 間 違 い が あ る 商 標 の 正 し い 綴 り の リ ス ト で あ る 。

DG/UX
HP−UX
UNIX
UnixWare

NULL, NUL, ヌ ル ポ イ ン タ ー 、 ヌ ル 文 字
null pointer
(ヌ ル ポ イ ン タ ー ) は 何 も な い も の を 指 す ポ イ ン タ ー で 、 通 常 は 定 数 NULL で 示 さ れ る 。 一 方 、 NULnull 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. な ど の 使 用 一 般 的 に は 、 "e.g.", "i.e.", "etc.", "a.k.a." な ど の 省 略 形 の 使 用 は 避 け る べ き で あ る 。 代 わ り に 完 全 な 形 の 単 語 を 使 う こ と ("for example" (例 え ば ), "that is" (つ ま り ), "and so on" (〜 な ど ), "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" は 異 な る 別 の 動 詞 で あ る 点 に 注 意 す る こ と 。 た い て い の 場 合 、 使 お う と 思 っ て い る の は 前 者 で あ ろ う 。 本 当 の マ イ ナ ス 文 字 本 当 の 意 味 で の マ イ ナ ス 文 字 が 必 要 な 場 合 は (−1 と い っ た 数 字 や ls −l と い っ た 先 頭 に ダ ッ シ ュ の オ プ シ ョ ン を 記 載 す る 場 合 な ど )、 マ ニ ュ ア ル ペ ー ジ の 原 文 で は 以 下 の 表 記 を 使 う こ と 。

\− こ の ガ イ ド ラ イ ン は サ ン プ ル コ ー ド の 場 合 に も 適 用 さ れ る 。 文 字 定 数
ASCII と UTF−8 の 両 方 で 正 し く レ ン ダ リ ン グ さ れ る シ ン グ ル ク ォ ー ト (一 重 引 用 符 ) を 生 成 す る に は 、 マ ニ ュ ア ル ペ ー ジ の 原 文 で は 以 下 の 表 記 を 使 う こ と 。

\(aqC\(aq こ こ で C が 括 弧 で 囲 ま れ る 文 字 で あ る 。 こ の ガ イ ド ラ イ ン は サ ン プ ル コ ー ド の 場 合 に も 適 用 さ れ る 。 サ ン プ ル プ ロ グ ラ ム と シ ェ ル の セ ッ シ ョ ン マ ニ ュ ア ル ペ ー ジ に は 、 シ ス テ ム コ ー ル や ラ イ ブ ラ リ 関 数 の 使 い 方 を 示 す サ ン プ ル プ ロ グ ラ ム を 含 め る こ と が で き る 。 そ の 際 に は 、 以 下 の 点 に 留 意 す べ き で あ る 。

* サ ン プ ル プ ロ グ ラ ム は

C で 記 載 す る こ と 。

* サ ン プ ル プ ロ グ ラ ム は 、

イ ン タ ー フ ェ ー ス に つ い て 文 章 で 簡 単 に 説 明 で き る 以 上 の こ と を 示 す 場 合 に だ け 必 要 か つ 有 用 で あ る 。 イ ン タ ー フ ェ ー ス を 呼 び 出 す 以 外 に 何 も し な い サ ン プ ル プ ロ グ ラ ム は 普 通 は ほ と ん ど 役 に 立 た な い 。

* サ ン プ ル プ ロ グ ラ ム は か な り 短 め に す る こ と

(100行 未 満 が 望 ま し く 、 50行

未 満 が 理 想 的 で あ る )。

* サ ン プ ル プ ロ グ ラ ム で は 、 シ ス テ ム コ ー ル や ラ イ ブ ラ リ 関 数 を 呼 び 出 し た 後 で エ ラ ー チ ェ ッ ク を 行 う こ と 。

* サ ン プ ル プ ロ グ ラ ム は 完 結 し て い て 、

cc −Wall で コ ン パ イ ル し た 際 に 警 告 な し で コ ン パ イ ル で き る こ と 。

* 可 能 か つ 適 切 な 場 合 に は 、 サ ン プ ル プ ロ グ ラ ム で 入 力 に よ り 動 作 を 変 化 さ せ る な ど の 実 験 を 行 う と よ い

(理 想 的 に は 、 コ マ ン ド ラ イ ン 引 き 数 や 、 プ ロ グ ラ ム が 読 み 込 む 入 力 デ ー タ 経 由 で 、 動 作 を 変 化 さ せ る の が よ い )。

* サ ン プ ル プ ロ グ ラ ム は 、

K&R (Kernighan and Ritchie) ス タ イ ル で 書 き 、

字 下 げ は ス ペ ー ス 4文 字 で 行 う 。 (ソ ー ス コ ー ド で TAB 文 字 を 使 う の は 避 け る こ と 。 )

* 一 貫 性 を 保 つ た め 、 す べ て の サ ン プ ル プ ロ グ ラ ム は 以 下 の い ず れ か で 終 了 す る こ と 。

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), groff(7), groff_man(7), man(7), mdoc(7)

こ の 文 書 に つ い て

こ の man ペ ー ジ は Linux man−pages プ ロ ジ ェ ク ト の リ リ ー ス 3.79 の 一 部 で あ る 。 プ ロ ジ ェ ク ト の 説 明 と バ グ 報 告 に 関 す る 情 報 は http://www.kernel.org/doc/man−pages/ に 書 か れ て い る 。

COMMENTS