名 前
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 形 式 で 記 載 す る こ と 。 コ マ ン ド 、 関 数 、 シ ス テ ム コ ー ル の 出 自 。 数 少 な い セ ク シ ョ ン 1 と 8 の ペ ー ジ の 場 合 、 お そ ら く 単 に GNU と だ け 書 く こ と が 多 い だ ろ う 。 シ ス テ ム コ ー ル の 場 合 、 単 に Linux と だ け 書 く 。 (以 前 の 慣 習 で は 、 マ ニ ュ ア ル ペ ー ジ を 記 載 し た /内 容 を 確 認 し た カ ー ネ ル の バ ー ジ ョ ン 番 号 を 記 載 し て い た 。 し か し 、 バ ー ジ ョ ン 番 号 が 実 際 の 内 容 と 一 致 し て い る こ と は な く 、 そ の た め バ ー ジ ョ ン 番 号 が な い よ り も お そ ら く 悪 い 形 に な っ て い た 。 今 後 は 、 バ ー ジ ョ ン 番 号 を 含 め る の は 避 け る こ と 。 ) glibc の ラ イ ブ ラ リ コ ー ル や そ の 他 の 一 般 的 な GNU ラ イ ブ ラ リ の ラ イ ブ ラ リ コ ー ル の 場 合 、 単 に GNU C Library, GNU と 書 く か 、 空 の 文 字 列 を 使 う 。 セ ク シ ョ ン 4 の ペ ー ジ で は Linux を 使 う 。 よ く わ か ら な い 場 合 は 、 Linux と か GNU と 書 い て お く 。
シ ョ ン 2
お よ び 3 の ペ ー
ジ の 場 合 に は
、 Linux Programmer’s Manual を
使 う こ と )。 マ
ニ ュ ア ル ペ ー
ジ の セ ク シ ョ
ン 昔 か ら 使 わ
れ て き た セ ク
シ ョ ン 名 を 以
下 の リ ス ト に
示 す 。 こ れ ら
を 使 う と 良 い
だ ろ う 。 一 般
的 に 、 マ ニ ュ
ア ル ペ ー ジ は
、 少 な く と も
色 つ き の セ ク
シ ョ ン を 持 つ
の が 望 ま し い
。 新 し く マ ニ
ュ ア ル ペ ー ジ
を 作 成 す る 際
に は 、 だ い た
い 以 下 の リ ス
ト に 示 し た 順
序 で セ ク シ ョ
ン を 配 置 す る
よ う に し て も
ら い た い 。 名
前 書 式 設 定
.SH NAME コ マ ン ド の 後 に 続 け る 行 の 重 要 な 情 報 に つ い て は man(7) を 参 照 。 こ の 行 の す べ て の 単 語 は ("\−" の 直 後 の 単 語 も 含 め ) 小 文 字 に す べ き で あ る 。 但 し 、 英 語 や 技 術 用 語 の 慣 例 と し て 別 の 記 載 を す る 場 合 は こ の 限 り で は な い 。 書 式 (SYNOPSIS) コ マ ン ド や 関 数 イ ン タ ー フ ェ ー ス の 簡 潔 な 概 要 コ マ ン ド に 対 し て は 、 コ マ ン ド や 引 き 数 (オ プ シ ョ ン ) の 文 法 を 書 く 。 そ の ま ま 書 く テ キ ス ト に は ボ ー ル ド 体 を 用 い 、 置 き 換 え る 引 き 数 に は イ タ リ ッ ク 体 を 用 い る 。 省 略 可 能 な オ プ シ ョ ン は ブ ラ ケ ッ ト ([]) で 囲 い 、 選 択 肢 は 縦 棒 (|) で 区 切 り 、 繰 り 返 し に は 省 略 符 号 (...) を 書 く 。 関 数 に 対 し て は 、 必 要 な デ ー タ 宣 言 や #include 指 定 を 書 き 、 関 数 宣 言 を 続 け る 。 ヘ ッ ダ ー フ ァ イ ル か ら 関 数 (や 変 数 ) の 定 義 を 得 る た め に 機 能 検 査 マ ク ロ (feature test macro) を 定 義 し な け れ ば な ら な い 場 合 、 書 式 (SYNOPSIS) に 必 要 な 機 能 検 査 マ ク ロ を 記 載 す べ き で あ る 。 機 能 検 査 マ ク ロ に つ い て は feature_test_macros(7) で 説 明 さ れ て い る 。
る 。 説 明 (DESCRIPTION) プ ロ グ ラ ム ・ 関 数 ・ フ ォ ー マ ッ ト の 動 作 ・ 目 的 。 フ ァ イ ル や 標 準 入 力 を ど の よ う に 処 理 し 、 標 準 出 力 や 標 準 エ ラ ー 出 力 を ど の よ う に 生 成 す る か と い っ た こ と に つ い て 述 べ る 。 内 部 動 作 や 実 装 の 詳 細 に つ い て は 省 略 す る (た だ し そ れ が 動 作 の 理 解 に ど う し て も 必 要 な ら 別 )。 通 常 の 場 合 に つ い て 記 述 す る 。 プ ロ グ ラ ム の コ マ ン ド ラ イ ン オ プ シ ョ ン の 説 明 に は 、 オ プ シ ョ ン の セ ク シ ョ ン を 用 い る 。 シ ス テ ム コ ー ル や ラ イ ブ ラ リ 関 数 の 新 し い 動 作 や 新 し い フ ラ グ に つ い て 説 明 す る 際 は 、 変 更 が 取 り 込 ま れ た カ ー ネ ル や C ラ イ ブ ラ リ の バ ー ジ ョ ン を 注 記 に 入 れ る よ う に 気 を 付 け る こ と 。 フ ラ グ に こ の 情 報 の 注 記 を 入 れ る 方 法 と し て は 、 推 奨 さ れ る 方 法 は 、 以 下 の よ う に .TP リ ス ト の 一 部 に す る こ と で あ る (こ の 例 は シ ス テ ム コ ー ル の 新 し い フ ラ グ の 場 合 )。 XYZ_FLAG (Linux 3.7 以 降 ) フ ラ グ の 説 明 ... バ ー ジ ョ ン 情 報 を 入 れ て お く の は 、 古 い バ ー ジ ョ ン の カ ー ネ ル や C ラ イ ブ ラ リ を 使 わ ざ る を 得 な い ユ ー ザ ー に と っ て 、 特 に 有 用 で あ る (例 え ば 、 組 み 込 み シ ス テ ム で は よ く あ る こ と で あ る )。 オ プ シ ョ ン (OPTIONS) プ
ロ グ ラ ム が 受
け 付 け る コ マ
ン ド ラ イ ン オ
プ シ ョ ン と そ
の 場 合 プ ロ グ
ラ ム の 振 舞 い
が ど う 変 わ る
か の 説 明 。 こ
の セ ク シ ョ ン
は セ ク シ ョ ン 1
と 8 の マ ニ ュ ア
ル ペ ー ジ に だ
け 登 場 す べ き
で あ る 。 終 了
ス テ ー タ ス (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 固 有 の 場 合 は 、 そ の 旨 を 記 載 す る こ と 。 (そ う な っ て い る ペ ー ジ が 多 い が ) こ の セ ク シ ョ ン の 内 容 が 標 準 の リ ス ト だ け の 場 合 、 リ ス ト の 最 後 に ピ リ オ ド ('.') を 置 く こ と 。
2 と 3 の マ ニ ュ ア ル ペ ー ジ で は 、 Linux で の 注 意 (Linux Notes) や glibc で の 注 意 (Glibc Notes) と い う 名 前 の サ ブ セ ク シ ョ ン (SS) を 設 け る と 便 利 な こ と も あ る 。 セ ク シ ョ ン 2 で は 、 シ ス テ ム コ ー ル に 対 す る C ラ イ ブ ラ リ の ラ ッ パ ー 関 数 と カ ー ネ ル が 提 供 す る 素 の シ ス テ ム コ ー ル の イ ン タ ー フ ェ ー ス の 間 で 違 い が あ る 場 合 に 、 そ の 違 い を 説 明 す る 注 記 を 記 載 す る 際 に は C ラ イ ブ ラ リ と カ ー ネ ル ABI の 違 い と い う 見 出 し を 使 う こ と 。
1〜 2 個 の
例 。 サ ン プ ル
プ ロ グ ラ ム を
書 く 際 の 詳 細
は 以 下 の 「 サ
ン プ ル プ ロ グ
ラ ム 」 の 節 を
参 照 の こ と 。
著 者 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 は ア メ リ カ 英 語 の 綴 り の 慣 習 に 従 っ て い る (以 前 は イ ギ リ ス 英 語 と ア メ リ カ 英 語 が 基 準 も な く 混 在 し て 使 わ れ て い た )。 新 し い ペ ー ジ や パ ッ チ は 全 て こ の 慣 習 に 従 っ て 下 さ い 。 よ く 知 ら れ た 綴 り の 違 い 以 外 に 、 微 妙 な 違 い も い く つ か 見 ら れ る 。
が 、 イ ギ リ ス 英 語 で は "backwards", "upwards", "towards" な ど を 使 う 方 が 多 い 。 BSD バ
ー ジ ョ ン 番 号
.SS Unicode under Linux 構 造 体 の 定 義 、 シ ェ ル の セ ッ シ ョ ン ロ グ な ど の 字 下 げ 、 な ど 構 造 体 の 定 義 や シ ェ ル の セ ッ シ ョ ン ロ グ な ど を 本 文 中 に 記 載 す る 際 は 、 ス ペ ー ス 4個 分 の 字 下 げ を 行 う (つ ま り 、 ブ ロ ッ ク を .in +4n と .in で 囲 む )。 推 奨 用 語 以 下 の 表 に マ ニ ュ ア ル ペ ー ジ で の 使 用 が 推 奨 さ れ る 用 語 を 示 す 。 こ れ ら は 主 に マ ニ ュ ア ル ペ ー ジ 間 で の 一 貫 性 を 保 つ た め で あ る 。 以 下 の 修 飾 子 と し て の 複 合 語 に お け る ハ イ フ ン の 議 論 も 参 照 。 使 用 を 避 け る 用 語 以 下 の 表 に マ ニ ュ ア ル ペ ー ジ で の 使 用 を 避 け る べ き 用 語 を 示 す 。 推 奨 さ れ る 表 現 も 合 わ せ て 記 載 し て い る 。 こ れ ら は 主 に マ ニ ュ ア ル ペ ー ジ 間 で の 一 貫 性 を 保 つ た め で あ る 。 商 標 商 標 に つ い て は 正 し い 綴 り と 大 文 字 小 文 字 を 使 う こ と 。 以 下 は 時 々 綴 り の 間 違 い が あ る 商 標 の 正 し い 綴 り の リ ス ト で あ る 。 DG/UX NULL, NUL,
ヌ ル ポ イ ン タ
ー 、 ヌ ル 文 字
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 に
よ る ダ ッ シ ュ
32−bit
value (32 ビ ッ ト 値 ) multi, non, pre, re, sub な ど と の 組 み 合 わ せ で の ハ イ フ ン 一 般 的 に 最 近 の 英 語 の 傾 向 で は 、 "multi", "non", "pre", "re", "sub" な ど の 接 尾 辞 の 後 ろ に は ハ イ フ ン を 付 け な い 。 こ れ ら の 接 尾 辞 が 単 純 な 接 尾 語 と の 普 通 の 英 語 の 組 み 合 わ せ の 場 合 に は 、 マ ニ ュ ア ル ペ ー ジ で は 基 本 的 に こ の ル ー ル に 従 う 。 以 下 の リ ス ト に 推 奨 さ れ る 形 式 で の 例 を い く つ か 挙 げ る 。 interprocess
non−ASCII
\−
こ の ガ イ ド ラ
イ ン は サ ン プ
ル コ ー ド の 場
合 に も 適 用 さ
れ る 。 文 字 定
数 \(aqC\(aq こ こ で C が 括 弧 で 囲 ま れ る 文 字 で あ る 。 こ の ガ イ ド ラ イ ン は サ ン プ ル コ ー ド の 場 合 に も 適 用 さ れ る 。 サ ン プ ル プ ロ グ ラ ム と シ ェ ル の セ ッ シ ョ ン マ ニ ュ ア ル ペ ー ジ に は 、 シ ス テ ム コ ー ル や ラ イ ブ ラ リ 関 数 の 使 い 方 を 示 す サ ン プ ル プ ロ グ ラ ム を 含 め る こ と が で き る 。 そ の 際 に は 、 以 下 の 点 に 留 意 す べ き で あ る 。
イ ン タ ー フ ェ ー ス に つ い て 文 章 で 簡 単 に 説 明 で き る 以 上 の こ と を 示 す 場 合 に だ け 必 要 か つ 有 用 で あ る 。 イ ン タ ー フ ェ ー ス を 呼 び 出 す 以 外 に 何 も し な い サ ン プ ル プ ロ グ ラ ム は 普 通 は ほ と ん ど 役 に 立 た な い 。
未 満 が 理 想 的 で あ る )。
cc −Wall で コ ン パ イ ル し た 際 に 警 告 な し で コ ン パ イ ル で き る こ と 。
(理 想 的 に は 、 コ マ ン ド ラ イ ン 引 き 数 や 、 プ ロ グ ラ ム が 読 み 込 む 入 力 デ ー タ 経 由 で 、 動 作 を 変 化 さ せ る の が よ い )。
字 下 げ は ス ペ ー ス 4文 字 で 行 う 。 (ソ ー ス コ ー ド で TAB 文 字 を 使 う の は 避 け る こ と 。 )
exit(EXIT_SUCCESS);
.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/ に 書 か れ て い る 。 |