Manpages

title 手 冊 頁 的 標 題

(例 如 ， MAN).

應 當 放 在 這 裏 (例 如 ， 7).
date 最 後 修 改 日 期 -- 記 住 要 在 每 次 修 改 過 此 手 冊 頁 之 後 修 改 它 ，

這 樣 可 以 方 便 地 進 行 版 本 控 制

Distribution, MCC Distribution. 對 於 系 統 調 用 ， 使 用 它 適 用 的 內 核 版 本 來 表 述 ： Linux 0.99.11. 對 於 庫 調 用 ， 使 用 函 數 的 來 源 來 表 述 ： GNU, BSD 4.3, Linux DLL 4.4.1.

注 意 BSD mdoc 格 式 的 手 冊 頁 以 Dd 命 令 開 始 ， 而 不 是 TH 命 令 手 冊 章 節 傳 統 上 如 下 定 義 ：

1 Commands 用 戶 可 從 shell 運 行 的 命 令
2 System calls 必 須 由 內 核 完 成 的 功 能
3 Library calls 大 多 數 libc 函 數 ， 例 如 qsort(3))
4 Special files

/dev) 目 錄 中 的 文 件

5 File formats and conventions

/etc/passwd 等 人 類 可 讀 的 文 件 的 格 式 說 明

7 Macro packages and conventions 文 件 系 統 標 準 描 述 ， 網 絡 協 議 ， ASCII 和 其 他 字 符 集 ， 還 有 你 眼 前 這 份 文 檔 以 及 其 他 東 西
8 System management commands 類 似 mount(8) 等 命 令 ， 大 部 分 只 能 由 root 執 行
9 Kernel routines 這 是 廢 棄 的 章 節 。 原 來 曾 想 把 一 些 關 於 核 心 的 文 件 放 在 這 裏 ， 但 是 實 際 上 只 有 極 少 數 可 以 寫 成 文 件 放 在 這 裏 ， 而 且 它 們 也 很 快 過 時 了 。 核 心 開 發 者 可 以 找 到 其 他 更 好 的 資 源 。

段 SECTIONS

段 以 .SH 開 始 ， 後 跟 標 題 名 。 如 果 標 題 包 含 空 格 並 且 和 .SH 在 同 一 行 ， 則 需 在 標 題 上 加 雙 引 號 。 傳 統 的 或 建 議 的 標 題 包 括 ： NAME, 總 覽 SYNOPSIS, 描 述 DESCRIPTION, 返 回 值 RETURN VALUE, 退 出 狀 態 EXIT STATUS, 錯 誤 處 理 ERROR HANDLING, 錯 誤 ERRORS, 選 項 OPTIONS, 用 法 USAGE, 示 例 EXAMPLES, 文 件 FILES, 環 境 ENVIRONMENT, 診 斷 DIAGNOSTICS, 安 全 SECURITY, 遵 循 CONFORMING TO, 注 意 NOTES, BUGS, 作 者 AUTHOR, 和 參 見 SEE ALSO. 在 適 合 使 用 約 定 標 題 的 地 方 ， 請 使 用 它 ； 這 樣 做 可 以 使 文 章 更 易 讀 、 易 懂 。 不 過 ， 只 要 您 的 標 題 能 夠 增 加 易 懂 性 ， 請 放 心 使 用 。 唯 一 必 須 的 標 題 是 NAME, 他 應 是 手 冊 頁 的 第 一 段 ， 後 面 應 緊 跟 對 該 命 令 的 簡 單 描 述 。 比 如 ：

.SH NAME
chess \- the game of chess 請 一 定 要 按 照 這 個 格 式 來 寫 ， 注 意 在 短 橫 線 (dash ’-’) 前 要 有 個 斜 槓 (slash ’´). 這 種 語 法 結 構 在 makewhatis(8) 程 序 爲 whatis(1) 和 apropos(1) 命 令 建 立 簡 短 命 令 描 述 時 要 用 到 。 其 他 約 定 段 的 內 容 應 爲 ：

[]中 的 是 可 選 項 ， 豎 線 | 用 於 把 幾 個 選 項 間 隔 開 ， 小 括 號 ()中 的 部 分 可 以 自 動 重 複 。 對 函 數 ， 顯 示 需 要 的 數 據 聲 明 或 需 #include 包 含 的 項 目 ， 後 跟 函 數 聲 明 。 描 述
DESCRIPTION 解 釋 命 令 、 函 數 或 格 式 的 用 途 。 說 明 其 如 何 與 文 件 及 標 準 輸 入 交 互 ， 他 們 的 標 準 輸 出 及 標 準 錯 誤 。 必 須 要 指 明 的 細 節 。 描 述 一 般 情 況 。 選 項 和 參 數 信 息 放 在 OPTIONS（ 選 項 ） 段 。 如 果 有 語 法 說 明 和 一 些 複 雜 的 設 定 ， 建 議 把 它 們 放 到 USAGE（ 用 法 ） 段 （ 本 段 中 最 好 只 寫 一 個 概 要 ） 。 返 回 值
RETURN VALUE 列 出 程 序 或 函 數 會 返 回 的 值 ， 指 出 引 發 返 回 值 的 條 件 或 原 因 。 退 出 狀 態
EXIT STATUS 列 出 可 能 的 退 出 狀 態 的 值 ， 指 出 引 起 返 回 的 程 序 或 原 因 。

provides one or more examples describing how this function, file or command is used.

/usr/local， 所 以 你 的 文 件 要 與 此 一 致 。 環 境
ENVIRONMENT 列 出 影 響 你 的 程 序 的 所 有 環 境 變 量 ， 並 說 明 影 響 的 原 因 。 診 斷
DIAGNOSTICS 寫 出 常 會 出 現 的 錯 誤 概 述 ， 並 說 明 解 決 的 辦 法 。 你 無 需 解 釋 系 統 錯 誤 信 息 或 信 號 ， 除 非 它 們 會 影 響 到 您 的 程 序 。

CONFORMING TO 描 述 它 實 現 的 任 何 標 準 或 約 定

man pages)。 通 常 來 講 ， 這 是 一 個 手 冊 頁 的 最 後 一 段 。

字 體 FONTS

雖 然 在 UNIX 世 界 中 有 各 種 對 手 冊 頁 （ man pages)的 不 同 約 定 ， 但 在 linux 系 統 下 存 在 一 個 字 體 的 標 準 ： 對 函 數 ， 其 參 數 通 常 用 下 劃 線 （ 或 斜 體 ） ， 在 總 覽 （ SYNOPSIS)中 也 是 這 樣 ， 其 他 部 分 用 黑 體 。 例 如

int myfunction(int argc, char **argv); 文 件 名 用 下 劃 線 （ 或 斜 體 ） ， 例 如 ， .IR "/usr/include/stdio.h" ), 但 在 總 覽 （ SYNOPSIS)中 ， 包 含 的 文 件 用 黑 體 ， 例 如 #include <stdio.h>). 專 用 宏 ， 一 般 大 寫 表 示 ， 用 黑 體 （ 如 ： MAXINT). 列 舉 錯 誤 代 號 時 ， 代 號 用 黑 體 （ 這 種 列 舉 通 常 使 用 .TP 宏 命 令 ） 。 對 其 他 手 冊 頁 的 引 用 （ 或 本 頁 中 某 主 體 的 引 用 ） 用 黑 體 。 手 冊 章 節 號 用 普 通 體 （ 如 ： man(7)). 設 置 字 體 的 宏 命 令 如 下 ：

GNU 去 除 了 這 個 限 制 。 小 節 之 間 以 空 格 隔 開 。 如 果 某 小 節 含 有 空 格 ， 則 需 要 給 其 加 上 雙 引 號 。 各 小 節 在 顯 示 時 無 間 隔 ， 所 以 .BR 命 令 可 以 指 定 一 個 黑 體 的 詞 ， 後 跟 一 個 普 通 體 的 標 點 。 如 果 命 令 後 無 參 數 ， 則 命 令 作 用 於 下 一 行 。

其 他 宏 命 令 和 字 符 串 OTHER MACROS AND STRINGS

下 面 是 其 他 一 些 相 關 的 宏 和 預 定 義 的 字 符 串 。 除 非 指 明 ， 否 則 所 有 的 宏 在 本 行 文 本 結 束 時 終 止 。 多 數 宏 使 用 “流 行 縮 進 ”（ prevailing indent)方 式 。 “流 行 縮 進 ”的 值 由 緊 跟 着 宏 命 令 的 i 值 指 定 ， 如 果 不 指 定 ， 那 就 會 使 用 當 前 的 “流 行 縮 進 ”值 。 這 樣 ， 連 續 的 縮 進 段 就 可 使 用 相 同 的 縮 進 值 而 不 需 要 重 新 指 定 。 普 通 段 （ 不 縮 進 ） 將 “流 行 縮 進 ”值 重 值 爲 缺 省 值 （ 0.5 英 寸 ） 。 缺 省 時 ， 縮 進 是 有 規 則 的 en(s)： 用 en(s) 或 者 em(s) 作 爲 縮 進 的 單 位 ， 因 爲 它 們 會 自 動 地 調 整 字 體 的 大 小 。 (注 ： 度 量 距 離 有 不 同 的 單 位 ， 當 請 求 需 要 用 到 不 同 的 距 離 時 ， 可 以 使 用 默 認 類 型 來 修 飾 數 字 ， 度 量 單 位 是 英 寸 ， 釐 米 ， pica,en,em,點 ， unit和 垂 直 行 距 。 1pica等 於 1/6英 寸 ， 1em等 於 字 母 m的 寬 度 ， 默 認 寬 度 取 決 於 troff中 使 用 的 字 體 。 En是 em的 一 半 。 ) 其 他 宏 命 令 定 義 如 下 ： 普 通 段 （ 無 縮 進 ） Normal Paragraphs