Manpages

NAME (名 字 )

mdoc.samples — 用 -mdoc 編 寫 BSD 手 冊 的 示 範 教 程

SYNOPSIS (總 覽 )

man mdoc.samples

DESCRIPTION (描 述 ) 這 個 示 範 教 程 用 於 編 寫 BSD 手 冊 頁 (manual page), 它 使 用 了 -mdoc 宏 定 義 包 , 這 是 個 基 於 內 容 和 基 於 宏 域 (domain-base) 的 格 式 化 包 , 交 由 troff(1) 處 理 . 它 的 前 身 -man(7) 包 , 定 義 了 頁 面 佈 局 (page layout), 但 是 把 諸 如 字 體 控 制 和 其 他 排 版 細 節 留 給 了 每 一 個 作 者 . 在 -mdoc 包 裏 , 頁 面 佈 局 宏 構 成 了 頁 結 構 宏 域 (page structure domain) 它 由 標 題 , 小 節 首 部 , 顯 示 (displays) 和 列 表 宏 組 成 . 這 些 基 本 項 目 影 響 正 文 在 格 式 化 頁 上 的 物 理 位 置 . 作 爲 頁 結 構 宏 域 的 補 充 , 這 裏 還 定 義 了 另 外 兩 個 宏 域 , 手 冊 宏 域 和 基 本 正 文 宏 域 . 基 本 正 文 宏 域 定 義 了 一 些 宏 , 執 行 例 如 引 文 或 文 字 強 調 之 類 的 任 務 . 手 冊 宏 域 定 義 的 宏 是 非 正 式 日 常 用 語 的 子 集 , 用 於 描 述 命 令 , 例 程 和 相 關 的 BSD 文 件 . 手 冊 宏 域 裏 的 宏 用 來 處 理 命 令 名 , 命 令 行 參 數 和 選 項 , 函 數 名 稱 , 函 數 參 數 , 路 徑 , 變 量 , 以 及 到 其 他 手 冊 頁 的 參 照 等 . 這 些 域 項 留 有 爲 作 者 和 手 冊 頁 的 未 來 用 戶 設 置 的 值 . 希 望 從 手 冊 集 中 獲 得 的 一 致 性 能 夠 爲 將 來 的 文 檔 工 具 提 供 更 簡 單 的 轉 換 . 從 整 個 的 UNIX 手 冊 頁 上 來 看 , 每 個 手 冊 項 可 以 簡 單 的 理 解 爲 一 個 man page, 不 用 注 意 它 的 實 際 長 度 , 也 沒 有 性 別 歧 視 意 圖 . (譯 註 : 可 能 是 雙 關 語 , man page...男 人 頁 ) 開 始 GETTING STARTED 因 爲 人 們 通 常 是 爲 了 能 夠 馬 上 使 用 這 些 材 料 的 時 候 才 閱 讀 教 程 ， 所 以 我 們 假 設 此 文 檔 的 用 戶 是 缺 乏 耐 心 的 ． 下 面 簡 述 一 下 這 份 文 檔 剩 餘 部 分 的 組 織 :

1.

TROFF 特 性 使 用 宏 . 參 數 中 傳 遞 空 白 符 . 尾 部 的 空 白 符 . 轉 義 特 殊 字 符 .

2. 手 冊 頁 的 結 構 分 析 手 冊 頁 的 模 板 .

3. 標 題 宏 .

4. 手 冊 宏 域 和 基 本 正 文 宏 域 的 介 紹 . 名 稱 背 後 .... 基 本 語 法 .

5. 手 冊 宏 域 地 址 . 作 者 名 字 . 參 數 . 配 置 聲 明 (僅 用 於 手 冊 第 四 部 分 ). 命 令 修 飾 . 已 定 義 的 變 量 .
Errno’s (僅 用 於 手 冊 第 二 部 分 ). 環 境 變 量 . 函 數 參 數 . 函 數 聲 明 . 標 誌 (Flags). 函 數 (庫 例 程 ). 函 數 類 型 . 交 互 命 令 . 名 稱 . 選 項 . 路 徑 . 變 量 . 參 照 .

6. 基 本 正 文 宏 域
AT&T 宏 .
BSD 宏 .
FreeBSD 宏 .
UNIX 宏 . 嵌 入 /引 用 宏 (Enclosure/Quoting) 尖 括 弧 引 用 /嵌 入 . 方 括 弧 引 用 /嵌 入 . 雙 引 號 引 用 /嵌 入 宏 . 圓 括 弧 引 用 /嵌 入 . 單 引 號 引 用 /嵌 入 . 前 綴 宏 .
No-Op 或 正 文 宏 . 消 除 空 白 宏 . 手 冊 節 對 照 . 參 考 和 引 用 . 返 回 值 (僅 用 於 手 冊 頁 第 二 和 第 三 部 分 )
Trade Names (縮 略 和 類 型 名 稱 ). 參 數 擴 展 .

7. 頁 結 構 宏 域 小 節 首 部 . 段 落 和 空 行 . 保 持 (Keeps). 顯 示 . 字 體 模 式 (加 重 , 原 文 和 Symbolic). 列 表 和 欄 .

8. 預 定 義 串

9. 診 斷

10. 用 GROFF, TROFF 和 NROFF 格 式 化

11. 臭 蟲 BUGS

TROFF 特 性 使 用 -mdoc 宏 包 的 目 的 是 簡 化 寫 手 冊 頁 的 過 程 . 理 論 上 講 , 要 使 用 -mdoc 不 一 定 要 學 習 troff(1) 的 隱 藏 細 節 ; 然 而 , 有 些 限 制 無 法 迴 避 , 最 好 把 它 們 擺 平 . 而 且 你 應 該 知 道 , 這 個 宏 包 的 速 度 比 較 慢 . 宏 的 用 法 Macro Usage 在 troff(1) 裏 , 宏 調 用 的 形 式 是 在 行 首 以 ’.’ (句 點 符 ) 起 始 , 緊 隨 其 後 是 作 爲 宏 名 的 兩 個 字 符 . 參 數 跟 在 宏 名 之 後 , 用 空 格 符 隔 開 . 這 個 位 於 行 首 的 句 點 符 使 troff(1) 把 緊 隨 其 後 的 兩 個 字 符 視 作 宏 名 . 在 某 些 情 況 下 要 把 ’.’ (句 點 符 ) 放 在 行 首 , 但 不 希 望 被 理 解 成 宏 請 求 , 方 法 是 在 ’.’ (句 點 ) 前 使 用 ’\&’ 轉 義 序 列 . ’\&’ 被 解 釋 成 一 段 長 度 爲 零 的 空 白 , 所 以 不 會 在 輸 出 端 顯 示 出 來 . 一 般 說 來 , troff(1) 宏 最 多 接 受 九 個 參 數 , 忽 略 掉 其 餘 的 . 大 多 數 在 -mdoc 裏 的 宏 支 持 九 個 參 數 , 某 些 場 合 可 以 續 加 參 數 , 或 擴 展 到 下 一 行 . (見 擴 展 Extensions). 有 些 宏 能 夠 處 理 引 號 引 起 來 的 參 數 (見 下 面 的 在 參 數 中 傳 遞 空 格 符 ). 大 多 數 -mdoc 的 基 本 正 文 宏 域 和 手 冊 宏 域 的 宏 擁 有 一 種 特 性 , 表 現 在 把 參 數 列 表 當 成 可 調 用 的 宏 分 析 (解 釋 ). 這 意 味 着 如 果 參 數 列 表 裏 的 參 數 是 普 通 正 文 宏 域 或 手 冊 宏 域 裏 的 宏 , 並 且 是 可 調 用 宏 , 那 麼 處 理 的 時 候 會 執 行 或 調 用 . 這 種 情 況 下 的 參 數 , 即 宏 名 , 不 需 要 用 ’.’ (句 點 符 ) 引 導 . 這 種 風 格 使 很 多 宏 嵌 套 在 一 起 ; 例 如 這 個 選 項 宏 ’.Op’, 可 能 調 用 標 誌 和 參 數 宏 , ’Fl’ 和 ’Ar’, 用 來 說 明 一 個 帶 參 數 的 選 項 :

[-s bytes] 來 自 .Op Fl s Ar bytes 爲 了 防 止 把 兩 個 字 符 的 字 符 串 解 釋 成 宏 名 , 在 這 個 字 符 串 前 面 加 上 ’\&’ 轉 義 序 列 :

[Fl s Ar bytes] 來 自 .Op \&Fl s \&Ar bytes 這 裏 的 字 符 串 ’Fl’ 和 ’Ar’ 沒 有 被 解 釋 成 宏 . 在 這 篇 文 檔 和 相 應 的 快 速 參 考 手 冊 mdoc(7) 中 , 參 數 列 表 按 可 調 用 參 數 分 析 的 宏 稱 爲 已 分 析 , 可 以 從 參 數 列 表 調 用 的 宏 稱 爲 可 調 用 . 這 裏 用 的 術 語 ’分 析 ’ 可 能 是 個 技 術 失 誤 , 幾 乎 所 有 的 -mdoc 宏 都 被 分 析 , 既 用 它 指 可 調 用 宏 , 又 指 有 調 用 其 他 宏 的 能 力 , 顯 得 很 笨 拙 . 在 參 數 中 傳 遞 空 格 符 Passing Space Characters in an Argument 某 些 時 候 我 們 希 望 能 夠 把 含 有 一 個 或 多 個 空 格 符 的 字 符 串 作 爲 單 個 參 數 傳 遞 . 如 果 要 突 破 九 個 參 數 的 限 制 , 或 者 傳 遞 給 宏 的 參 數 需 要 一 些 特 定 佈 置 , 這 個 能 力 是 必 須 的 . 例 如 , 函 數 宏 ’.Fn’ 的 第 一 個 參 數 是 函 數 名 稱 , 剩 下 的 參 數 作 爲 函 數 的 參 數 . ANSI C 規 定 函 數 的 參 數 在 圓 括 弧 內 聲 明 , 每 個 參 數 至 少 由 兩 個 標 示 符 組 成 . 例 如 , int foo. 有 兩 個 方 法 傳 遞 嵌 有 空 格 符 的 參 數 . 補 充 一 點 : 不 幸 的 是 , 在 AT&T troff 中 , 那 個 最 容 易 的 方 法 , 就 是 作 爲 單 個 參 數 傳 遞 兩 個 引 號 之 間 的 字 符 串 和 空 格 符 , 非 常 消 耗 時 間 和 內 存 空 間 . 雖 然 它 對 groff 並 不 費 事 , 但 是 爲 了 可 移 植 性 , 這 種 做 法 只 限 於 下 列 有 迫 切 需 要 的 宏 :

Cd 配 置 聲 明 (手 冊 第 四 部 分 概 要 SYNOPSIS)
Bl 列 表 開 始 (指 定 寬 度 的 )
Em 加 重 文 字
Fn 函 數 (手 冊 第 二 , 四 部 分 )
It 列 表 項
Li 原 文
Sy

Symbolic text

%B 書 題
%J 期 刊 名
%O 參 考 選 注
%R 報 告 題 目 (在 參 考 文 件 中 )
%T 在 書 籍 或 期 刊 中 的 題 目 一 種 傳 遞 含 空 格 符 字 符 串 的 方 法 是 用 ’\ ’ 硬 編 碼 或 不 可 填 充 空 格 符 , 也 就 是 在 空 格 符 前 加 上 轉 義 符 ’\’. 這 個 方 法 適 用 於 任 何 宏 , 但 有 個 副 效 應 , 它 干 擾 了 對 長 行 的 調 整 . Troff 把 這 種 硬 編 碼 的 空 格 符 看 作 可 顯 示 字 符 , 因 此 無 法 在 需 要 的 時 候 把 字 符 串 分 段 或 換 行 . 這 種 方 法 適 用 於 字 符 串 不 會 到 達 行 邊 界 時 , 例 如 :

fetch(char *str) 來 自 ’.Fn fetch char\ *str’

fetch(char *str) 也 可 以 來 自 ’.Fn fetch "char *str"’ 如 果 忽 略 ’\’ 或 引 號 , ’.Fn’ 宏 會 認 爲 有 三 個 參 數 , 結 果 成 爲 :

fetch(char, *str) 如 果 想 知 道 參 數 列 表 到 達 行 邊 界 時 出 現 什 麼 , 參 看 BUGS 小 節 . 尾 部 的 空 白 符 Trailing Blank Space Characters

Troff 可 能 被 行 尾 的 空 白 符 搞 亂 , 它 的 防 範 規 則 是 消 除 所 有 位 於 行 末 的 空 白 符 . 如 果 堅 持 在 行 末 加 上 空 白 符 , 可 以 用 硬 空 格 符 和 ’\&’ 轉 義 字 符 . 例 如 , ’string\ \&’. 轉 義 特 殊 字 符 Escaping Special Characters 特 殊 字 符 , 如 換 行 符 ’\n’, 是 通 過 用 ’\e’ 替 換 ’\’ (e.g.例 如 ’\en’) 保 留 住 反 斜 槓 . 手 冊 頁 結 構 分 析 THE ANATOMY OF A MAN PAGE 手 冊 頁 可 以 很 容 易 的 通 過 模 板 構 建 , 模 板 放 在 /usr/share/misc/mdoc.template. 另 外 在 /usr/share/examples/mdoc 目 錄 下 有 一 些 手 冊 頁 的 例 子 . 手 冊 頁 的 模 板 A manual page template

.\" 所 有 的 手 冊 頁 都 要 求 有 下 面 的 內 容
.Dd 月 日 , 年 Month day, year
.Os 操 作 系 統 [版 本 /發 行 號 ]
.Dt 文 檔 標 題 [手 冊 節 號 ][卷 ]
.Sh 名 稱 NAME
.Nm 名 稱 name
.Nd 對 名 稱 的 簡 單 描 述 one line description of name
.Sh 總 覽 SYNOPSIS
.Sh 描 述 DESCRIPTION
.\" 後 面 的 內 容 取 消 註 釋 後 可 以 用 在 你 需 要 的 任 何 地 方 .
.\" 緊 接 着 的 這 條 命 令 用 於 手 冊 第 二 和 第 三 部 分 , 函 數 的 返 回 值 .
.\" .Sh 返 回 值 RETURN VALUES
.\" 下 面 的 命 令 用 於 手 冊 第 1, 6, 7, 8部 分 .
.\" .Sh 環 境 ENVIRONMENT
.\" .Sh 文 件 FILES
.\" .Sh 示 例 EXAMPLES
.\" 下 面 的 命 令 用 於 手 冊 第 1, 6, 7, 8部 分
.\" (在 shell下 的 命 令 返 回 值 和 標 準 錯 誤 類 型 的 診 斷 )
.\" .Sh 診 斷 DIAGNOSTICS
.\" 下 面 的 命 令 用 於 手 冊 第 二 和 第 三 部 分 中 的 錯 誤 和 信 號 處 理 .
.\" .Sh 錯 誤 ERRORS
.\" .Sh 另 見 SEE ALSO
.\" .Sh 遵 循 CONFORMING TO
.\" .Sh 歷 史 HISTORY
.\" .Sh 作 者 AUTHORS
.\" .Sh BUGS 模 板 中 的 第 一 個 部 分 是 (.Dd, .Os, .Dt) 宏 ; 文 檔 日 期 , 手 冊 或 其 內 容 針 對 的 操 作 系 統 , 手 冊 頁 的 標 題 ((大 寫 )) 和 該 手 冊 頁 所 屬 的 節 (部 分 號 ). 這 些 宏 確 認 和 標 識 了 這 個 手 冊 頁 . 在 後 面 的 標 題 宏 TITLE MACROS 將 繼 續 討 論 . 這 個 模 板 中 的 其 餘 部 分 是 小 節 首 部 (section header) (.Sh); 其 中 名 稱 NAME, 總 覽 SYNOPSIS 和 描 述 DESCRIPTION 是 必 不 可 少 的 . 這 些 首 部 在 頁 結 構 宏 域 中 討 論 ( 介 紹 完 手 冊 域 之 後 ) . 有 一 些 內 容 宏 被 用 來 示 範 頁 面 佈 局 宏 ; 建 議 接 觸 頁 面 佈 局 宏 前 先 看 看 內 容 宏 . 標 題 宏 TITLE MACROS 標 題 宏 是 頁 結 構 宏 域 的 第 一 部 分 , 但 在 過 去 , 人 們 如 果 編 寫 手 冊 頁 , 它 是 手 冊 的 第 一 部 分 , 也 是 獨 立 部 分 . 這 裏 設 計 了 三 個 宏 分 別 描 述 文 檔 標 題 或 手 冊 標 題 , 操 作 系 統 , 和 製 作 日 期 . 它 們 放 在 文 檔 的 最 前 面 , 一 次 只 調 用 一 個 , 用 來 構 建 文 檔 的 頁 頭 和 頁 腳 .

.Dt 文 檔 標 題 手 冊 區 # [卷 ] 文 檔 標 題 是 手 冊 頁 的 主 題 , 由 於 troff 的 限 制 , 必 須 大 寫 . 手 冊 節 號 (部 分 號 ) 介 於 1, ..., 8, 如 果 指 明 瞭 手 冊 節 號 , 可 以 忽 略 卷 標 . 卷 標 用 下 列 標 識 的 一 個 或 任 意 個 :

URM 代 表 手 冊 區 1, 6, and 7; SMM 代 表 手 冊 區 8; PRM 代 表 手 冊 區 2, 3, 4, and 5.

.Os 操 作 系 統 發 行 號 # 操 作 系 統 的 名 字 可 能 是 縮 寫 , 像 BSD 或 FreeBSD 或 ATT. 發 行 號 應 該 是 系 統 專 用 的 標 準 發 行 術 語 , 像 4.3, 4.3+Tahoe, V.3, V.4. 識 別 不 出 的 參 數 就 照 原 樣 顯 示 在 頁 腳 . 例 如 , 典 型 的 頁 腳 可 能 是 :

.Os BSD 4.3 或
.Os FreeBSD 2.2 或 者 象 訂 製 的 產 品

.Os CS Department 作 爲 伯 克 利 的 缺 省 設 置 , 不 帶 參 數 的 ’.Os’ 定 義 爲 BSD (指 定 在 文 件 /usr/share/tmac/mdoc/doc-common 中 ). 你 應 該 把 缺 省 值 設 成 本 機 . 注 意 , 如 果 不 設 置 ’.Os’ 宏 , 頁 面 的 左 下 角 會 很 難 看 .

.Dd 月 日 , 年 (month day, year) 日 期 應 當 寫 的 正 規 點 :

January 25, 1989 手 冊 宏 域 和 基 本 正 文 宏 域 的 介 紹 名 稱 背 後 What’s in a name... 手 冊 宏 域 的 宏 名 來 自 非 正 式 的 日 常 用 語 , 用 來 描 述 命 令 , 子 程 序 及 其 相 關 文 件 . 在 寫 手 冊 頁 時 , 文 字 用 語 有 些 輕 微 的 變 化 , 分 別 描 述 三 個 不 同 應 用 面 . 首 先 是 -mdoc 宏 請 求 的 用 法 . 其 次 , 用 -mdoc 宏 描 述 UNIX 命 令 . 最 後 , 對 用 戶 具 體 的 描 述 這 條 命 令 ; 也 就 是 在 手 冊 頁 正 文 裏 討 論 這 條 命 令 . 第 一 種 情 況 下 , troff(1) 宏 本 身 就 是 一 種 命 令 ; troff 命 令 的 基 本 語 法 是 :

.Va argument1 argument2 ... argument9 這 裏 的 ’.Va’ 是 宏 命 令 或 宏 請 求 , 緊 隨 其 後 的 是 待 處 理 的 參 數 . 第 二 種 情 況 下 , 使 用 內 容 宏 描 述 一 條 UNIX 命 令 要 複 雜 些 ; 一 個 典 型 的 總 覽 SYNOPSIS 命 令 行 顯 示 如 下 :

filter [-flag] infile outfile 這 裏 的 filter 是 命 令 名 稱 , 方 括 弧 內 的 -flag 是 一 個 標 誌 參 數 , 作 爲 可 選 參 數 放 在 代 表 選 項 的 方 括 弧 內 . 在 -mdoc 術 語 中 , infile 和 outfile 稱 爲 參 數 . 產 生 上 述 效 果 的 宏 是 這 樣 的 :

.Nm filter
.Op Fl flag
.Ar infile outfile 第 三 種 情 況 討 論 命 令 及 其 語 法 , 包 括 它 們 的 例 子 , 可 能 還 有 更 多 細 節 . 上 面 的 例 子 裏 , 可 以 把 infile 和 outfile 理 解 爲 操 作 參 數 operands 或 文 件 參 數 file arguments. 有 些 命 令 行 參 數 羅 列 的 十 分 長 :

make

[-eiknqrstv] [-D variable] [-d flags] [-f makefile] [-I directory] [-j max_jobs] [variable=value] [target ...] 這 裏 你 可 能 討 論 make 命 令 和 它 的 參 數 makefile, 作 爲 一 個 標 誌 的 參 數 , -f, 或 者 討 論 一 個 可 選 的 文 件 操 作 對 象 target. 在 具 體 的 上 下 文 中 , 這 種 細 節 能 夠 防 止 混 淆 . 然 而 -mdoc 宏 包 中 沒 有 爲 標 誌 的 參 數 準 備 宏 . 作 爲 替 代 是 ’Ar’ 參 數 宏 , 用 於 描 述 操 作 對 象 或 文 件 參 數 如 target 以 及 標 誌 的 參 數 如 variable. 上 面 的 make 命 令 行 是 這 樣 產 生 的 :

.Nm make
.Op Fl eiknqrstv
.Op Fl D Ar variable
.Op Fl d Ar flags
.Op Fl f Ar makefile
.Op Fl I Ar directory
.Op Fl j Ar max_jobs
.Op Ar variable=value
.Bk -words
.Op Ar target ...
.Ek 在Keeps 小 節 中 將 會 解 釋 ’.Bk’ 和 ’.Ek’ 宏 . 基 本 語 法 General Syntax 手 冊 宏 域 和 基 本 正 文 宏 域 的 宏 有 着 相 似 的 語 法 , 僅 有 微 小 差 別 : ’.Ar’, ’.Fl’, ’.Nm’, 和 ’.Pa’ 僅 當 無 參 數 調 用 時 纔 有 區 別 ; ’.Fn’ 和 ’.Xr’ 的 參 數 列 表 要 求 一 定 的 順 序 ; ’.Op’ 和 ’.Fn’ 宏 有 嵌 套 限 制 . 所 有 的 內 容 宏 能 夠 識 別 和 正 確 處 理 標 點 符 號 , 每 個 標 點 符 號 要 在 前 面 用 空 格 隔 開 . 如 果 給 出 這 樣 的 宏 請 求 :

.Li sptr, ptr), 結 果 是 :

sptr, ptr), 標 點 符 號 沒 有 被 識 別 出 來 , 全 都 按 原 文 字 體 輸 出 . 如 果 標 點 符 號 前 面 用 空 格 符 隔 開 :

.Li sptr , ptr ) , 結 果 是 :

sptr, ptr), 標 點 符 號 被 識 別 出 來 了 , 缺 省 的 字 體 也 有 別 於 原 文 文 字 的 字 體 . 用 ’\&’. 轉 義 符 可 以 去 掉 標 點 字 符 的 特 殊 意 義 . Troff 作 爲 宏 語 言 有 一 定 的 限 制 , 當 表 達 的 字 串 中 含 有 數 學 , 邏 輯 或 引 用 符 號 時 將 難 於 處 理 :

{+,-,/,*,%,<,>,<=,>=,=,==,&,’,’,"} 問 題 是troff 會 認 爲 它 應 該 執 行 或 運 算 這 些 符 號 代 表 的 操 作 . 要 防 止 這 一 點 可 以 用 ’\&’ 轉 義 這 些 字 符 . 典 型 語 法 在 下 面 顯 示 的 第 一 個 內 容 宏 中 可 以 見 到 , ’.Ad’. 手 冊 域 MANUAL DOMAIN 地 址 宏 Address Macro 地 址 宏 用 這 種 格 式 標 明 地 址 : addr1[,addr2[,addr3]].

Usage: .Ad address ...

.Ad addr1

addr1

.Ad addr1 .

addr1.

.Ad addr1 , file2

addr1, file2

.Ad f1 , f2 , f3 :

f1, f2, f3:

.Ad addr ) ) ,

addr)), 不 帶 參 數 調 用 ’.Ad’ 是 個 錯 誤 . ’.Ad’ 可 以 被 (其 他 宏 ) 調 用 和 分 析 . 作 者 名 稱 Author Name

The ’.An’ 宏 用 以 說 明 這 個 文 檔 的 描 述 對 象 的 作 者 , 或 者 這 篇 手 冊 頁 的 作 者 . 名 字 信 息 後 面 的 其 他 參 數 被 認 爲 是 標 點 符 號 .

Usage: .An author_name ...

.An Joe Author

Joe Author

.An Joe Author ,

Joe Author,

.An Joe Author Aq nobody [AT] FreeBSD.ORG

Joe Author <nobody [AT] FreeBSD.ORG>

.An Joe Author ) ) ,

Joe Author)),

’.An’ 宏 可 以 被 (其 他 宏 ) 分 析 和 調 用 , 不 帶 參 數 調 用 ’.An’ 是 個 錯 誤 . 參 數 宏 Argument Macro 當 引 用 命 令 行 參 數 時 可 以 使 用 ’.Ar’ 參 數 宏 .

Usage: .Ar argument ...

.Ar

file ...

.Ar file1

file1

.Ar file1 .

file1.

.Ar file1 file2

file1 file2

.Ar f1 f2 f3 :

f1 f2 f3:

.Ar file ) ) ,

file)), 如 果 不 帶 參 數 調 用 ’.Ar’ 宏 , 缺 省 爲 ’file ...’. ’.Ar’ 宏 可 以 被 (其 他 宏 ) 分 析 和 調 用 . 配 置 定 義 (手 冊 第 四 部 分 ) Configuration Declaration

’.Cd’ 宏 用 於 描 述 config(8) 對 設 備 接 口 的 定 義 (手 冊 第 四 部 分 ). 這 個 宏 接 受 引 號 內 的 參 數 (只 能 是 雙 引 號 ).

device le0 at scode? 來 自 : ’.Cd device le0 at scode?’. 命 令 修 飾 Command Modifier 命 令 修 飾 宏 和 ’.Fl’ (標 誌 ) 命 令 相 似 , 除 了 ’.Cm’ 宏 不 在 任 何 參 數 前 加 短 橫 線 (dash). 傳 統 的 標 誌 以 短 橫 線 開 頭 , 但 一 些 命 令 或 命 令 的 子 集 不 用 這 個 . 命 令 修 飾 宏 也 可 以 和 交 互 命 令 結 合 使 用 , 如 編 輯 命 令 . 另 見 Flags. 已 定 義 的 變 量 Defined Variables 在 頭 文 件 中 已 經 定 義 了 的 變 量 用 ’.Dv’ 宏 說 明 .

Usage: .Dv defined_variable ...

.Dv MAXHOSTNAMELEN

MAXHOSTNAMELEN

.Dv TIOCGPGRP )

TIOCGPGRP) 不 帶 參 數 調 用 ’.Dv’ 是 個 錯 誤 . ’.Dv’ 宏 可 以 被 (其 他 宏 ) 分 析 和 調 用 .

Errno’s (僅 供 手 冊 第 二 部 分 ) 這 個 ’.Er’ errno 宏 指 明 手 冊 第 二 部 分 , 庫 函 數 的 錯 誤 返 回 值 .(譯 註 : 應 該 是 系 統 調 用 ) 下 面 的 第 二 個 例 子 顯 示 了 ’.Er’ 配 合 ’.Bq’ 基 本 正 文 宏 的 使 用 , 就 象 用 在 手 冊 第 二 部 分 一 樣 .

Usage: .Er ERRNOTYPE ...

.Er ENOENT

ENOENT

.Er ENOENT ) ;

ENOENT);

.Bq Er ENOTDIR

[ENOTDIR] 不 帶 參 數 調 用 ’.Er’ 宏 是 個 錯 誤 . ’.Er’ 宏 可 以 被 (其 他 宏 ) 分 析 和 調 用 . 環 境 變 量 Environment Variables

’.Ev’ 宏 說 明 一 個 環 境 變 量 .

Usage: .Ev argument ...

.Ev DISPLAY

DISPLAY

.Ev PATH .

PATH.

.Ev PRINTER ) ) ,

PRINTER)), 不 帶 參 數 調 用 ’.Ev’ 宏 是 個 錯 誤 . ’.Ev’ 宏 可 以 被 (其 他 宏 ) 分 析 和 調 用 . 函 數 參 數 Function Argument

’.Fa’ 宏 用 來 說 明 在 手 冊 的 總 覽 SYNOPSIS 小 節 之 外 的 函 數 參 數 , 或 者 在 總 覽 SYNOPSIS 小 節 內 , 其 參 數 列 表 對 ’.Fn’ 宏 而 言 過 長 , 並 且 必 須 使 用 ’.Fo’ 和 ’.Fc’ 宏 時 . ’.Fa’ 也 有 可 能 用 來 說 明 結 構 成 員 .

Usage: .Fa function_argument ...

.Fa d_namlen ) ) ,

d_namlen)),

.Fa iov_len

iov_len 不 帶 參 數 調 用 ’.Fa’ 宏 是 個 錯 誤 . ’.Fa’ 宏 可 以 被 (其 他 ) 宏 分 析 和 調 用 . 函 數 聲 明 Function Declaration

’.Fd’ 宏 用 於 第 二 或 第 三 部 分 手 冊 頁 的 總 覽 SYNOPSIS 小 節 . ’.Fd’ 宏 既 不 調 用 其 他 宏 , 也 不 能 被 其 他 宏 調 用 .

Usage: .Fd include_file (or defined variable) 在 總 覽 SYNOPSIS 小 節 , 如 果 已 經 說 明 了 某 個 函 數 , 並 且 沒 有 出 現 省 略 號 , 則 ’.Fd’ 宏 請 求 能 夠 產 生 一 個 斷 行 . 在 函 數 和 函 數 聲 明 之 間 , 垂 直 方 向 上 產 生 一 定 的 空 白 . 標 誌 Flags

’.Fl’ 宏 處 理 命 令 行 標 誌 . 它 在 標 誌 前 加 一 個 短 橫 線 ’-’, 對 於 交 互 命 令 標 誌 , 它 不 需 要 短 橫 線 , 可 以 用 ’.Cm’ (命 令 修 飾 command modifier) 宏 替 換 , 它 沒 有 短 橫 線 .

Usage: .Fl argument ...

.Fl

-

.Fl cfv

-cfv

.Fl cfv .

-cfv.

.Fl s v t

-s -v -t

.Fl - ,

--,

.Fl xyz ) ,

-xyz), 如 果 ’.Fl’ 宏 不 帶 任 何 參 數 , 將 只 產 生 一 個 短 橫 線 , 代 表 stdin/stdout. 注 意 如 果 把 一 個 短 橫 線 做 爲 ’.Fl’ 的 參 數 , 結 果 會 得 到 兩 個 短 橫 線 . ’.Fl’ 宏 可 以 被 (其 他 宏 ) 分 析 和 調 用 . 函 數 (庫 函 數 ) Functions (library routines) 宏 .Fn 是 ANSI C 函 數 風 格 的 模 型 .

Usage: .Fn [type] function [[type] parameters ...

.Fn getchar

getchar()

.Fn strlen ) ,

strlen()),

.Fn "int align" "const * char *sptrs",

int align(const * char *sptrs), 不 帶 參 數 調 用 ’.Fn’ 是 一 個 錯 誤 . ’.Fn’ 宏 可 以 被 (其 他 宏 ) 分 析 和 調 用 , 注 意 任 何 對 其 他 宏 的 調 用 應 該 在 ’.Fn’ 宏 調 用 的 結 尾 處 給 出 標 記 (反 括 弧 ). 對 於 八 個 參 數 以 上 的 函 數 (儘 管 少 見 ), 可 以 用 宏 ’.Fo’ (function open) 和 ’.Fc’ (function close) 配 合 ’.Fa’ (function argument) 宏 的 使 用 , 突 破 參 數 過 多 的 限 制 , 例 如 :

.Fo "int res_mkquery"
.Fa "int op"
.Fa "char *dname"
.Fa "int class"
.Fa "int type"
.Fa "char *data"
.Fa "int datalen"
.Fa "struct rrec *newrr"
.Fa "char *buf"
.Fa "int buflen"
.Fc 產 生 :

int res_mkquery(int op, char *dname, int class, int type, char *data, int datalen, struct rrec *newrr, char *buf, int buflen) 宏 ’.Fo’ 和 ’.Fc’ 可 以 被 (其 他 宏 ) 分 析 和 調 用 . 在 總 覽 SYNOPSIS 小 節 , 函 數 總 是 位 於 行 的 開 始 處 . 如 果 在 總 覽 SYNOPSIS 小 節 有 一 個 以 上 的 函 數 聲 明 , 而 且 函 數 類 型 沒 有 說 明 , 則 會 產 生 一 個 斷 行 . 在 函 數 和 函 數 的 垂 直 方 向 上 產 生 一 定 的 空 白 . 此 時 ’.Fn’ 宏 不 按 troff 的 行 長 檢 查 單 詞 邊 界 , 有 可 能 難 看 的 從 單 詞 中 間 斷 開 . 以 後 會 解 決 這 個 問 題 . 函 數 類 型 Function Type 這 個 宏 設 計 用 在 總 覽 SYNOPSIS 小 節 . 它 可 以 毫 無 困 難 的 用 在 手 冊 頁 的 其 他 地 方 , 但 它 的 主 要 目 的 是 爲 第 二 和 第 三 部 分 手 冊 頁 的 總 覽 SYNOPSIS 小 節 , 以 核 心 標 準 形 式 (kernel normal form) 描 述 函 數 類 型 (它 導 致 斷 行 , 在 下 一 行 顯 示 函 數 名 稱 ).

Usage: .Ft type ...

.Ft struct stat

struct stat

’.Ft’ 宏 不 能 被 其 他 宏 調 用 . 交 互 命 令 Interactive Commands 宏 ’.Ic’ 用 於 說 明 交 互 或 內 部 命 令 .

Usage: .Ic argument ...

.Ic :wq : wq
.Ic do while {...}

do while {...}

.Ic setenv , unsetenv

setenv, unsetenv 不 帶 參 數 調 用 ’.Ic’ 是 個 錯 誤 . ’.Ic’ 宏 可 以 被 (其 他 宏 ) 分 析 和 調 用 . 名 稱 宏 Name Macro

’.Nm’ 宏 用 於 說 明 文 檔 題 目 或 主 題 . 它 的 特 點 是 能 夠 記 住 調 用 時 帶 的 第 一 個 參 數 , 這 個 參 數 就 是 該 頁 的 主 題 . 當 不 帶 參 數 調 用 它 時 , ’.Nm’ 宏 把 以 前 記 住 的 參 數 顯 示 出 來 , 可 以 爲 作 者 省 點 勁 . 注 意 : 手 冊 第 二 部 分 或 第 三 部 分 的 函 數 名 稱 , 在 名 稱 NAME 小 節 用 ’.Nm’ 說 明 , 在 總 覽 SYNOPSIS 和 其 餘 小 節 用 ’.Fn’ 說 明 . 對 於 交 互 命 令 , 例 如 在 csh(1) 中 的 ’while’ 命 令 , 應 該 使 用 ’.Ic’ 宏 . ’.Ic’ 宏 和 ’.Nm’, 宏 非 常 接 近 , 只 是 它 不 能 夠 記 憶 調 用 時 的 參 數 .

Usage: .Nm argument ...

.Nm mdoc.sample

mdoc.sample

.Nm \-mdoc

-mdoc.

.Nm foo ) ) ,

foo)),

.Nm

mdoc.samples

’.Nm’ 宏 可 以 被 (其 他 宏 ) 分 析 和 調 用 . 選 項 Options
’.Op’ 宏 把 命 令 行 上 剩 餘 的 所 有 參 數 用 方 括 弧 括 在 一 起 , 把 最 後 的 標 點 符 號 放 到 方 括 弧 外 面 . 宏 ’.Oc’ 和 ’.Oo’ 用 於 處 理 跨 行 .

Usage: .Op options ...

.Op

[]

.Op Fl k

[-k]

.Op Fl k ) .

[-k]).

.Op Fl k Ar kookfile

[-k kookfile]

.Op Fl k Ar kookfile ,

[-k kookfile],

.Op Ar objfil Op Ar corfil

[objfil [corfil]]

.Op Fl c Ar objfil Op Ar corfil ,

[-c objfil [corfil]],

.Op word1 word2

[word1 word2] 應 用 ’.Oc’ 和 ’.Oo’ 宏 :

.Oo
.Op Fl k Ar kilobytes
.Op Fl i Ar interval
.Op Fl c Ar count
.Oc 產 生 :[

[-k kilobytes] [-i interval] [-c count] ] 宏 ’.Op’, ’.Oc’ 和 ’.Oo’ 可 以 被 (其 他 宏 ) 分 析 和 調 用 . 路 徑 名 Pathnames

’.Pa’ 宏 用 於 格 式 化 路 徑 或 文 件 名 .

Usage: .Pa pathname

.Pa /usr/share

/usr/share

.Pa /tmp/fooXXXXX ) .

/tmp/fooXXXXX).

’.Pa’ 宏 可 以 被 (其 他 宏 ) 分 析 和 調 用 . 變 量 Variables 基 本 的 變 量 參 考 :

Usage: .Va variable ...

.Va count

count

.Va settimer,

settimer,

.Va int *prt ) :

int *prt):

.Va char s ] ) ) ,

char s])), 不 帶 參 數 調 用 ’.Va’ 宏 是 個 錯 誤 . ’.Va’ 宏 可 以 被 (其 他 宏 ) 分 析 和 調 用 . 手 冊 頁 參 照 Manual Page Cross References

’.Xr’ 宏 把 第 一 個 參 數 當 做 手 冊 頁 名 稱 , 第 二 個 參 數 , 如 果 存 在 , 當 做 標 點 符 號 或 手 冊 頁 的 部 分 號 (節 號 ). 剩 下 所 有 的 參 數 視 做 標 點 符 號 .

Usage: .Xr man_page [1,...,8]

.Xr mdoc

mdoc

.Xr mdoc ,

mdoc,

.Xr mdoc 7

mdoc(7)

.Xr mdoc 7 ) ) ,

mdoc(7))),

’.Xr’ 宏 可 以 被 (其 他 宏 ) 分 析 和 調 用 . 不 帶 參 數 調 用 ’.Xr’ 宏 是 個 錯 誤 . 基 本 正 文 宏 域 GENERAL TEXT DOMAIN
AT&T 宏

Usage: .At [v6 | v7 | 32v | V.1 | V.4] ...

.At

AT&T UNIX

.At v6 .

Version 6 AT&T UNIX.

’.At’ 宏 不 能 被 (其 他 宏 ) 分 析 , 也 不 能 被 (其 他 宏 ) 調 用 . 該 宏 最 多 接 受 兩 個 參 數 .

BSD 宏

Usage: .Bx [Version/release] ...

.Bx

BSD

.Bx 4.3 .

4.3BSD.

’.Bx’ 宏 可 以 被 (其 他 宏 ) 分 析 和 調 用 .

FreeBSD 宏

Usage: .Fx Version.release ...

.Fx 2.2 .

FreeBSD 2.2.

’.Fx’ 宏 不 能 被 (其 他 宏 ) 分 析 , 也 不 能 被 (其 他 宏 ) 調 用 . 該 宏 最 多 接 受 兩 個 參 數 .

UNIX 宏

Usage: .Ux ...

.Ux

UNIX

’.Ux’ 宏 可 以 被 (其 他 宏 ) 分 析 和 調 用 . 嵌 入 和 引 用 宏 Enclosure and Quoting Macros 嵌 入 的 概 念 和 引 用 類 似 . 把 一 句 或 多 句 引 用 對 象 嵌 到 一 對 字 符 中 , 象 引 號 或 括 弧 . 本 篇 文 檔 中 將 混 用 術 語 ’嵌 入 ’ 和 ’引 用 .’ 大 多 數 單 行 的 引 用 宏 名 用 一 個 小 寫 字 母 ’q’ 結 尾 , 表 明 這 是 一 個 引 用 (quoting), 但 也 有 不 規 則 變 化 . 每 個 引 用 宏 都 有 一 對 開 始 (open) 和 結 束 (close) 宏 , 各 自 以 ’o’ 和 ’c’ 結 尾 . 在 某 些 限 制 時 這 些 宏 可 以 跨 行 使 用 , 單 行 的 引 用 宏 可 以 嵌 套 在 裏 面 .

Quote Close Open Function Result

(其 他 宏 ) 分 析 和 調 用 . 所 有 的 引 用 宏 能 夠 正 確 處 理 標 點 符 號 , 只 要 一 次 一 個 字 符 , 中 間 用 空 格 隔 開 . 引 用 宏 檢 查 開 始 和 結 束 符 號 , 以 決 定 把 它 放 在 引 用 串 的 前 面 還 是 後 面 . 這 樣 就 有 了 一 定 的 嵌 套 能 力 .

.Ec, .Eo 這 些 宏 的 第 一 個 參 數 是 各 自 的 開 始 和 結 束 串 .

.Ql 原 文 引 用 宏 的 表 現 在 troff 中 和 nroff 不 一 樣 . 如 果 用 nroff 格 式 化 , 引 用 的 原 文 始 終 被 引 用 . 如 果 用 troff 格 式 化 , 只 有 寬 度 小 於 三 個 定 寬 字 符 的 項 才 被 引 用 . This is to make short strings more visible where the font change to literal (constant width) is less noticeable. 當 字 體 變 成 原 文 (定 寬 ) 時 , 短 串 顯 得 更 容 易 被 看 到 .

.Pf 前 綴 宏 不 能 被 (其 他 宏 ) 調 用 , 但 是 可 以 被 分 析 .

.Pf ( Fa name2 變 成 (name2. 這 個 ’.Ns’ (無 空 格 ) 宏 執 行 類 似 的 後 綴 功 能 . 引 用 舉 例 :
.Aq

⟨ ⟩

.Aq Ar ctype.h ) ,

⟨ ctype.h⟩ ),

.Bq

[]

.Bq Em Greek , French .

[Greek, French].

.Dq

’’’’

.Dq string abc .

’’string abc’’.

.Dq ´^[A-Z]´

’’´^[A-Z]´’’

.Ql man mdoc

’man mdoc’

.Qq

""

.Qq string ) ,

"string"),

.Qq string Ns ),

"string),"

.Sq

’’

.Sq string

’string’ 作 爲 嵌 套 引 用 宏 的 典 型 範 例 , 參 見 ’.Op’ 選 項 宏 . 它 們 都 來 自 上 面 列 出 的 基 本 引 用 宏 . ’.Xo’ 和 ’.Xc’ 擴 展 的 參 數 列 表 宏 同 樣 來 自 相 同 的 基 本 例 程 , 並 且 , 在 最 壞 的 情 況 下 , 是 -mdoc 宏 用 法 的 很 好 範 例 .

No-Op 或 正 文 宏 or Normal Text Macro 宏 ’.No’ 用 在 某 個 宏 命 令 行 上 , 意 如 其 名 , 將 不 被 格 式 化 , 語 法 遵 循 一 般 的 內 容 宏 . 無 空 格 宏 Space Macro
’.Ns’ 在 宏 請 求 之 間 消 除 不 需 要 的 空 格 . 它 用 在 舊 式 風 格 的 參 數 列 表 中 , 標 誌 和 參 數 間 沒 有 空 格 :

.Op Fl I Ns Ar directory 產 生 [-Idirectory] 注 意 : ’.Ns’ 宏 在 消 除 空 格 後 總 會 調 用 ’.No’ 宏 , 除 非 還 有 其 他 宏 名 跟 在 後 面 . ’.Ns’ 宏 可 以 被 (其 他 宏 ) 分 析 和 調 用 . 手 冊 頁 對 照 參 考 Section Cross References

’.Sx’ 宏 指 定 了 到 同 一 個 文 檔 內 的 小 節 首 部 的 對 照 參 考 . 該 宏 可 以 被 (其 他 宏 ) 分 析 和 調 用 .

.Sx FILES

FILES 參 考 和 引 言 References and Citations

The following macros make a modest attempt to handle references. At best, the macros make it convenient to manually drop in a subset of refer style references. 下 面 的 宏 試 圖 適 度 的 處 理 參 考 資 料 . 最 好 情 況 時 , 這 些 宏 便 於 手 工 插 入 一 段 相 關 風 格 的 參 考 資 料 .

.Rs 參 考 開 始 . 它 導 致 一 次 斷 行 , 並 且 開 始 收 集 參 考 資 料 , 直 到 遇 到 參 考 結 束 宏 .
.Re 參 考 結 束 . 則 打 印 出 參 考 信 息 .
.%A 參 考 資 料 的 作 者 名 字 , 一 次 一 個 .
.%B 書 名 .
.%C 城 市 /地 點 .
.%D 日 期 .
.%J 期 刊 名 .
.%N 發 行 號 .
.%O 可 選 信 息 .
.%P 頁 碼 .
.%R 報 告 名 .
.%T 文 章 題 目 .
.%V 卷 . 用 ’%’ 符 號 開 始 的 宏 不 能 被 (其 他 宏 ) 調 用 , 只 能 被 trade name macro 分 析 , 結 果 返 回 給 調 用 者 (此 時 結 果 不 太 好 預 測 ). 其 目 的 是 允 許 trade name 能 夠 很 好 的 打 印 在 troff/ditroff 的 輸 出 端 . 返 回 值 Return Values

’.Rv’ 宏 產 生 一 些 用 在 返 回 值 RETURN VALUES 小 節 的 文 字 .

Usage: .Rv [-std function]

’.Rv -std atexit’ 將 輸 出 下 列 文 字 :

.Rv -std atexit 這 個 -std 選 項 僅 用 於 手 冊 頁 的 第 二 和 第 三 部 分 .

Trade Names (或 縮 略 和 類 型 名 )
trade name 宏 一 般 說 來 是 一 個 很 小 的 大 寫 字 母 宏 , 用 於 所 有 大 於 兩 個 字 符 的 大 寫 單 詞 .

Usage: .Tn symbol ...

.Tn DEC

DEC

.Tn ASCII

ASCII

’.Tn’ 宏 可 以 被 (其 他 宏 ) 分 析 和 調 用 . 擴 展 參 數 Extended Arguments
’.Xo’ 和 ’.Xc’ 宏 可 以 在 宏 的 邊 界 擴 展 參 數 列 表 . 如 果 某 個 宏 要 求 所 有 的 參 數 在 一 行 上 出 現 , 則 參 數 列 表 不 能 在 這 兒 被 擴 展 . 例 如 ’.Op’. 這 裏 有 ’.Xo’ 宏 的 一 個 示 例 , 用 空 格 模 式 宏 把 空 格 去 掉 :

.Sm off
.It Xo Sy I Ar operation
.No \en Ar count No \en
.Xc
.Sm on 產 生

Ioperation\ncount\n 還 有 一 個 :

.Sm off
.It Cm S No / Ar old_pattern Xo
.No / Ar new_pattern
.No / Op Cm g
.Xc
.Sm on 產 生

S/old_pattern
/new_pattern/[g] 另 一 個 示 例 用 ’.Xo’ 和 引 用 宏 : 測 試 一 個 變 量 的 值 .

.It Xo
.Ic .ifndef
.Oo \&! Oc Ns Ar variable
.Op Ar operator variable ...
.Xc 產 生

.ifndef [
!]variable [operator variable ...] 上 面 所 有 的 例 子 都 在 ’.It’ (list-item) 宏 的 參 數 列 表 中 使 用 了 ’.Xo’ 宏 . 擴 展 宏 不 經 常 使 用 , 一 般 用 來 擴 展 list-item 宏 的 參 數 列 表 . 這 也 不 幸 的 是 擴 展 宏 最 苛 刻 的 地 方 . 前 兩 個 例 子 裏 空 格 被 去 掉 ; 第 三 個 例 子 中 , 希 望 能 輸 出 部 分 空 格 , 而 不 是 全 部 . 在 這 種 情 況 下 用 這 些 宏 , 要 確 保 ’.Xo’ 和 ’.Xc’ 宏 擺 放 到 第 三 個 例 子 中 示 範 的 位 置 . 如 果 ’.Xo’ 宏 沒 有 單 獨 出 現 在 ’.It’ 的 參 數 表 中 , 則 無 法 預 測 空 格 情 況 . 這 種 情 況 下 , ’.Ns’ (no space macro) 一 定 不 能 作 爲 一 行 的 第 一 個 宏 或 最 後 一 個 宏 . 當 前 BSD 發 佈 的 超 過 900個 手 冊 頁 (事 實 上 大 約 1500個 ) 中 , 只 有 十 五 個 用 到 了 ’.Xo’ 宏 . 頁 結 構 宏 宏 域 PAGE STRUCTURE DOMAIN 小 節 首 部 Section Headers 每 個 手 冊 頁 裏 都 用 到 了 下 面 列 出 的 三 個 ’.Sh’ 小 節 首 部 宏 . 作 者 寫 手 冊 頁 時 可 以 酌 情 考 慮 其 他 建 議 使 用 的 小 節 首 部 . ’.Sh’ 宏 最 多 帶 九 個 參 數 . 它 可 以 被 (其 他 宏 ) 分 析 , 但 不 能 被 調 用 .

.Sh 名 稱 NAME

’.Sh 名 稱 NAME’ 宏 是 必 不 可 少 的 . 否 則 無 法 設 置 頁 頭 , 頁 腳 和 缺 省 的 頁 佈 局 , 樣 子 會 很 難 看 . 名 稱 NAME 小 節 至 少 由 三 項 組 成 . 第 一 個 是 ’.Nm’ 名 稱 宏 , 命 名 手 冊 頁 的 主 題 . 第 二 個 是 名 稱 描 述 宏 ’.Nd’, 它 把 主 題 名 稱 和 第 三 項 , 描 述 , 分 離 開 來 . 描 述 應 該 儘 可 能 的 精 簡 易 懂 , 少 佔 空 間 .

.Sh 總 覽 SYNOPSIS

SYNOPSIS 總 覽 小 節 描 述 該 手 冊 頁 對 象 的 典 型 用 途 . 請 求 的 宏 是 下 面 的 任 意 一 個 , ’.Nm’, ’.Cd’, ’.Fn’, (也 可 能 是 ’.Fo’, ’.Fc’, ’.Fd’, ’.Ft’ 宏 ). 函 數 名 稱 宏 ’.Fn’ 用 在 手 冊 頁 的 第 二 第 三 部 分 , 命 令 和 基 本 名 稱 宏 ’.Nm’ 用 在 手 冊 頁 的 1, 5, 6, 7, 8 部 分 . 手 冊 第 四 部 分 需 要 ’.Nm’, ’.Fd’ 或 ’.Cd’ 配 製 設 備 用 途 宏 . 其 他 一 些 宏 可 能 用 來 產 生 概 要 行 , 象 下 面 的 :

cat [-benstuv] [-] file ... 下 面 用 到 的 宏

.Nm cat
.Op Fl benstuv
.Op Fl
.Ar 注 意 : 宏 ’.Op’, ’.Fl’, 和 ’.Ar’ 能 夠 識 別 管 道 符 ’|’, 因 此 命 令 行 如 :

.Op Fl a | Fl b 的 表 現 會 出 軌 . Troff 一 般 把 | 當 做 特 殊 符 號 . 參 見 預 定 義 串 PREDEFINED STRINGS, 在 其 他 情 況 下 | 的 使 用 .

.Sh 描 述 DESCRIPTION 大 多 數 情 況 下 描 述 DESCRIPTION 小 節 的 第 一 段 話 是 關 於 這 個 命 令 , 函 數 或 文 件 的 摘 要 , 後 跟 字 典 式 的 選 項 以 及 相 應 的 解 釋 . 創 建 這 樣 的 列 表 , 應 該 使 用 ’.Bl’ 列 表 開 始 , ’.It’ 列 表 項 和 ’.El’ 列 表 結 束 宏 (參 見 下 面 的 列 表 和 欄 目 Lists and Columns ). 下 面 的 ’.Sh’ 小 節 首 部 是 手 冊 頁 編 排 的 常 見 內 容 , 爲 了 保 證 連 續 性 , 應 適 當 使 用 . 它 們 按 照 應 該 出 現 的 順 序 排 列 .

.Sh 環 境 ENVIRONMENT 環 境 ENVIRONMENT 小 節 用 來 揭 示 相 關 的 環 境 變 量 和 線 索 , 它 們 的 行 爲 , 表 現 , 用 法 .

.Sh 示 例 EXAMPLES 有 很 多 辦 法 創 建 示 例 , 詳 見 下 面 的 示 例 EXAMPLES 小 節 .

.Sh 文 件 FILES 由 手 冊 頁 的 主 題 對 象 創 建 或 使 用 的 文 件 , 應 該 通 過 ’.Pa’ 宏 在 文 件 FILES 小 節 陳 列 出 來 .

.Sh 另 見 SEE ALSO 如 果 提 及 其 他 手 冊 頁 或 參 照 相 應 的 手 冊 , 應 把 它 們 放 在 另 見 SEE ALSO 小 節 . 參 照 主 題 由 ’.Xr’ 宏 指 定 . 在 另 見 SEE ALSO 小 節 的 參 照 主 題 應 該 按 手 冊 節 號 排 序 , 按 字 母 順 序 陳 列 , 並 用 逗 號 隔 開 , 例 如 :

ls(1), ps(1), group(5), passwd(5). 這 時 候 不 太 適 合 用 refer(1) 風 格 的 參 考 引 用 .

.Sh 遵 循 CONFORMING TO 如 果 那 些 命 令 , 庫 函 數 或 文 件 遵 循 一 定 的 標 準 實 現 , 如 IEEE Std 1003.2 (’’POSIX.2’’) 或 ANSI X3.159-1989 (’’ANSI C89’’), 那 就 不 需 要 這 一 小 節 . 如 果 命 令 不 符 合 任 何 標 準 , 應 該 把 它 的 歷 史 放 在 歷 史 HISTORY 小 節 .

.Sh 歷 史 HISTORY 任 何 不 屬 於 已 知 標 準 的 命 令 應 該 在 這 一 節 給 出 它 的 大 致 歷 史 .

.Sh 作 者 AUTHORS 如 果 有 必 要 , 把 致 謝 名 單 也 列 這 兒 .

.Sh 診 斷 DIAGNOSTICS 應 該 把 診 斷 命 令 放 在 這 一 節 .

.Sh 錯 誤 ERRORS 特 定 的 錯 誤 處 理 , 尤 其 是 庫 函 數 (手 冊 頁 第 二 第 三 部 分 ), 放 這 兒 . ’.Er’ 宏 用 來 指 定 一 個 errno.

.Sh BUGS 明 顯 的 問 題 放 這 兒 ... 可 以 增 加 一 些 用 戶 制 定 的 ’.Sh’ 小 節 , 例 如 , 這 樣 設 小 節 :

.Sh PAGE STRUCTURE DOMAIN 段 落 和 空 行Paragraphs and Line Spacing.

.Pp

’.Pp’ 把 段 落 命 令 放 在 所 需 的 位 置 , 可 以 產 生 一 個 空 行 . 在 ’.Sh’ 或 ’.Ss’ 宏 後 面 不 需 要 這 個 宏 , ’.Bl’ 宏 的 前 面 也 不 需 要 . ( ’.Bl’ 聲 明 瞭 垂 直 方 向 的 距 離 , 除 非 給 出 -compact 標 誌 ). 保 持 Keeps 目 前 只 實 現 了 對 單 詞 的 保 持 能 力 . 這 個 宏 有 ’.Bk’ (開 始 保 持 begin-keep) 和 ’.Ek’ (結 束 保 持 end-keep ) . ’.Bk’ 宏 的 唯 一 參 數 是 -words, 用 於 防 止 在 選 項 語 句 的 中 間 斷 行 . 在 make 命 令 行 參 數 的 例 子 裏 (參 見 名 稱 背 後 What’s in a name), keep 宏 防 止 nroff 把 標 誌 和 參 數 分 成 兩 行 . (事 實 上 可 以 用 選 項 宏 防 止 此 類 事 情 , 但 當 我 們 決 定 在 troff 中 作 爲 基 本 選 項 , 強 制 右 邊 界 對 齊 時 , 它 在 稀 疏 行 裏 展 開 的 很 糟 糕 . 使 用 保 持 宏 時 需 要 多 做 點 事 , 增 加 一 個 -line 選 項 ) . 示 例 和 顯 示 有 五 種 類 型 的 顯 示 , 一 個 快 速 的 單 行 縮 進 顯 示 ’.D1’, 快 速 的 單 行 原 文 顯 示 ’.Dl’, 原 文 塊 , 填 充 塊 , 和 由 ’.Bd’ (begin-display) 顯 示 開 始 和 ’.Ed’ (end-display) 顯 示 結 束 宏 對 組 成 的 不 規 則 塊 .

.D1

(D-one) 顯 示 一 行 縮 進 文 字 . 該 宏 可 以 被 (其 他 宏 ) 分 析 , 但 不 能 被 調 用 .

-ldghfstru 上 面 是 這 樣 產 生 的 : .Dl -ldghfstru.

.Dl

(D-ell) 顯 示 一 行 縮 進 的 原 文 literal. ’.Dl’ 示 例 宏 已 經 遍 佈 這 篇 文 檔 . 它 允 許 縮 進 (顯 示 ) 一 行 文 字 . 其 缺 省 字 體 設 爲 定 寬 (原 文 ), 它 可 以 被 其 他 宏 分 析 和 識 別 . 然 而 不 能 被 其 他 宏 調 用 .

% ls -ldg /usr/local/bin 上 面 是 這 樣 產 生 的 .Dl % ls -ldg /usr/local/bin.

.Bd 顯 示 開 始 . ’.Bd’ 的 顯 示 必 須 由 ’.Ed’ 宏 結 束 . 顯 示 可 以 嵌 套 在 顯 示 和 列 表 中 . ’.Bd’ 有 這 樣 的 語 法 :

.Bd display-type [-offset offset_value] [-compact] 顯 示 類 型 必 須 是 下 面 四 個 之 一 , 可 以 指 定 一 個 縮 進 量 . ’.Bd’.

-ragged 以 打 字 形 式 顯 示 一 塊 正 文 , 其 右 (和 左 )邊 界 是 不 平 整 邊 界 .
-filled 顯 示 填 充 (格 式 化 ) 塊 . 塊 中 文 字 被 格 式 化 (邊 界 已 經 填 充 過 , 不 再 是 左 邊 不 對 齊 ).
-literal 顯 示 原 文 塊 , 適 用 於 源 程 序 , 或 那 種 簡 單 的 , 用 table 和 空 格 調 整 的 文 字 .
-file file_name 閱 讀 並 顯 示 跟 在 -file 標 誌 後 面 的 文 件 . 原 文 模 式 被 打 開 , table 設 爲 8個 字 符 寬 , 然 而 文 件 中 出 現 的 任 何 troff/-mdoc 命 令 都 將 被 處 理 .
-offset string 如 果 -offset 指 定 爲 下 面 字 符 串 之 一 , 這 些 字 符 串 解 釋 爲 對 以 後 的 正 文 塊 的 縮 進 層 次 .

left 正 文 塊 按 當 前 左 邊 界 對 齊 , 這 是 ’.Bd’ 的 缺 省 模 式 .
center 應 該 是 把 正 文 塊 布 在 中 間 . 不 幸 的 是 , 目 前 只 能 在 大 致 的 中 間 位 置 靠 左 對 齊 .
indent 按 缺 省 縮 進 值 或 table 值 縮 進 . 這 個 缺 省 縮 進 值 同 時 用 於 ’.D1’ 顯 示 , 因 此 你 應 該 使 這 兩 種 顯 示 一 致 . 縮 進 值 一 般 設 爲 6n, 大 約 2/3 英 寸 (六 個 字 符 寬 度 ).
indent-two 縮 進 缺 省 值 的 兩 倍 .
right 在 距 離 右 邊 界 大 約 兩 英 寸 處 把 正 文 塊 靠 左 對 齊 . 這 個 宏 要 試 驗 效 果 , 有 可 能 troff 怎 麼 都 弄 不 對 .

.Ed

End-display. 顯 示 結 束 . 字 體 模 式 Font Modes 現 有 五 個 宏 用 於 改 變 手 冊 頁 的 文 字 外 觀 :

.Em 文 字 可 以 用 ’.Em’ 宏 加 重 或 強 調 . 常 用 的 強 調 字 體 是 斜 體 (italic).

Usage: .Em argument ...

.Em does not

does not

.Em exceed 1024 .

exceed 1024.

.Em vide infra ) ) ,

vide infra)),

’.Em’ 宏 可 以 被 (其 他 宏 ) 分 析 和 調 用 . 不 帶 參 數 調 用 ’.Em’ 宏 是 一 個 錯 誤 .

.Li

’.Li’ 原 文 宏 用 來 顯 示 字 符 , 變 量 , 常 數 , 任 何 希 望 照 輸 入 文 字 原 樣 顯 示 的 內 容 .

Usage: .Li argument ...

.Li \en

\n

.Li M1 M2 M3 ;

M1 M2 M3;

.Li cntrl-D ) ,

cntrl-D),

.Li 1024 ...

1024 ...

’.Li’ 宏 可 以 被 (其 他 宏 ) 分 析 和 調 用 .

.Sy 一 般 說 來 symbolic 強 調 宏 無 論 在 象 徵 主 義 角 度 , 還 是 傳 統 的 英 語 裏 , 都 是 用 黑 體 (bold) 顯 示 .

Usage: .Sy symbol ...

.Sy Important Notice

Important Notice

’.Sy’ 宏 可 以 被 (其 他 宏 ) 分 析 和 調 用 . ’.Sy’ 的 參 數 可 以 用 引 號 括 起 .

.Bf 字 體 模 式 開 始 . ’.Bf’ 字 體 模 式 必 須 用 ’.Ef’ 宏 結 束 . 字 體 模 式 宏 可 以 嵌 套 . ’.Bf’ 宏 用 下 面 的 語 法 :

.Bf font-mode 字 體 模 式 必 須 是 下 列 三 種 之 一 : ’.Bf’.

Em | -emphasis 就 象 是 把 ’.Em’ 宏 用 在 整 個 正 文 塊 一 樣 .
Li | -literal 就 象 是 把 ’.Li’ 宏 用 在 整 個 正 文 塊 一 樣 .
Sy | -symbolic 就 象 是 把 ’.Sy’ 宏 用 在 整 個 正 文 塊 一 樣 .

.Ef 字 體 模 式 結 束 . 標 記 欄 和 列 表 Tagged Lists and Columns 有 多 種 用 ’.Bl’ 列 表 開 始 宏 初 始 化 的 列 表 . 表 項 用 ’.It’ 項 目 宏 指 定 , 每 一 個 列 表 必 須 用 ’.El’ 宏 結 束 . 列 表 可 以 嵌 套 在 列 表 和 顯 示 中 . 欄 可 以 用 在 列 表 中 , 但 是 列 表 不 能 列 在 欄 裏 . 另 外 還 可 以 指 定 列 表 屬 性 , 像 標 記 寬 度 , 列 表 偏 移 , 以 及 緊 湊 模 式 (允 許 或 不 允 許 表 項 間 的 空 行 ) 在 本 文 中 大 多 使 用 了 標 記 風 格 (tag style) 的 列 表 (-tag). 作 爲 步 距 變 化 , 表 示 列 表 類 型 的 列 表 類 型 是 個 突 出 來 (overhanging) 的 列 表 (-ohang). 這 種 列 表 類 型 在 TeX 用 戶 中 很 流 行 , 但 看 過 很 多 頁 的 標 記 列 表 後 可 能 會 覺 得 有 點 滑 稽 . ’.Bl’ 宏 可 以 接 受 下 面 的 列 表 類 型 :

-bullet
-item
-enum 這 三 個 是 最 簡 單 的 列 表 類 型 . 一 旦 使 用 了 ’.Bl’ 宏 , 只 能 用 ’.It’ 宏 組 織 表 項 . 例 如 , 可 以 這 樣 寫 一 個 簡 單 的 數 字 列 表 "

.Bl -enum -compact
.It
Item one goes here.
.It
And item two here.
.It
Lastly item three goes here.
.El 結 果 是 :

1.

Item one goes here.

2.

And item two here.

3.

Lastly item three goes here. 簡 單 的 佈 告 欄 :

.Bl -bullet -compact
.It
Bullet one goes here.
.It
Bullet two here.
.El 產 生 :

•

Bullet one goes here.

•

Bullet two here.

-tag
-diag
-hang
-ohang
-inset 這 些 列 表 類 型 收 集 ’.It’ 宏 指 定 的 參 數 , 並 且 創 建 一 個 標 籤 , 它 可 能 會 插 入 inset 後 面 的 文 字 中 , 懸 掛 (hanged) 顯 示 在 後 面 的 文 字 前 , 突 前 (overhanged) 顯 示 在 更 高 位 置 , 並 且 不 能 縮 進 或 標 記 tagged. 這 個 列 表 由 ’-ohang’ 列 表 類 型 構 建 . ’.It’ 宏 只 能 被 插 入 (inset), 懸 掛 (hang), 和 標 記 列 表 類 型 宏 分 析 , 且 不 能 被 調 用 . 這 是 一 個 插 入 標 籤 的 例 子 :

Tag

The tagged list (also called a tagged paragraph) is the most common type of list used in the Berkeley manuals.

Diag

Diag lists create section four diagnostic lists and are similar to inset lists except callable macros are ignored.

Hang

Hanged labels are a matter of taste.

Ohang

Overhanging labels are nice when space is constrained.

Inset

Inset labels are useful for controlling blocks of paragraphs and are valuable for converting -mdoc manuals to other formats. 下 面 是 產 生 這 個 例 子 的 源 文 本 :

.Bl -inset -offset indent
.It Em Tag
The tagged list (also called a tagged paragraph) is the
most common type of list used in the Berkeley manuals.
.It Em Diag
Diag lists create section four diagnostic lists
and are similar to inset lists except callable
macros are ignored.
.It Em Hang
Hanged labels are a matter of taste.
.It Em Ohang
Overhanging labels are nice when space is constrained.
.It Em Inset
Inset labels are useful for controlling blocks of
paragraphs and are valuable for converting
.Nm -mdoc
manuals to other formats.
.El 這 是 含 有 兩 個 表 項 的 懸 掛 列 表 :

Hanged

labels appear similar to tagged lists when the label is smaller than the label width.

Longer hanged list labels

blend in to the paragraph unlike tagged paragraph labels. 它 們 的 源 文 本 爲 :

.Bl -hang -offset indent
.It Em Hanged
labels appear similar to tagged lists when the
label is smaller than the label width.
.It Em Longer hanged list labels
blend in to the paragraph unlike
tagged paragraph labels.
.El 帶 有 可 選 寬 度 項 的 標 記 列 表 可 以 控 制 標 記 的 寬 度 .

SL

sleep time of the process (seconds blocked)

PAGEIN

number of disk I/O’s resulting from references by the process to pages not loaded in core.

UID

numerical user-id of process owner

PPID

numerical id of parent of process process priority (non-positive when in non-interruptible wait) 源 文 本 是 :

.Bl -tag -width "PAGEIN" -compact -offset indent
.It SL
sleep time of the process (seconds blocked)
.It PAGEIN
number of disk
.Tn I/O Ns ’s
resulting from references
by the process to pages not loaded in core.
.It UID
numerical user-id of process owner
.It PPID
numerical id of parent of process process priority
(non-positive when in non-interruptible wait)
.El 可 接 受 的 寬 度 說 明 :

-width Fl 把 寬 度 設 置 爲 標 誌 (flag) 的 缺 省 寬 度 . 所 有 可 調 用 的 宏 都 有 一 個 缺 省 寬 度 值 . 目 前 ’.Fl’ 的 值 設 爲 十 個 字 符 寬 度 , 大 約 5/6 英 寸 .

-width 24n 設 置 寬 度 爲 24 個 字 符 寬 度 , 大 約 兩 英 寸 . 要 使 比 例 調 整 正 常 , 字 母 ’n’ 必 不 可 少

-width ENAMETOOLONG 設 置 寬 度 爲 所 給 串 的 長 度 .

-width "int mkfifo" 同 樣 , 設 置 寬 度 爲 所 給 串 的 長 度 . 如 果 沒 有 爲 標 記 列 表 類 型 指 定 寬 度 , 第 一 次 調 用 ’.It’ 的 時 候 , 格 式 化 軟 件 試 圖 決 定 適 當 的 寬 度 . 如 果 ’.It’ 的 第 一 個 參 數 是 可 調 用 宏 , 就 使 用 這 個 宏 的 缺 省 寬 度 , 就 像 把 宏 名 當 做 寬 度 . 可 是 如 果 列 表 中 的 其 他 表 項 得 到 另 一 個 可 調 用 宏 , 則 認 爲 它 是 新 的 , 嵌 套 的 列 表 . 預 定 義 串 PREDEFINED STRINGS 下 面 的 串 是 預 定 義 的 , 可 以 用 在 troff 的 串 翻 譯 序 列 ’\*(xx’ 中 , 這 裏 的 xx 就 是 定 義 的 串 名 ; 以 及 串 翻 譯 序 列 ’\*x’, 這 裏 的 x 是 串 名 . 翻 譯 序 列 可 以 用 在 文 本 的 任 何 地 方 .

’q’ 的 串 應 該 寫 成 ’\*q’, 因 爲 它 只 有 一 個 字 符 . 診 斷 DIAGNOSTICS

-mdoc 的 除 錯 系 統 比 較 有 限 , 但 是 可 以 幫 助 你 檢 測 出 微 妙 的 錯 誤 , 例 如 參 數 名 和 內 部 寄 存 器 或 宏 名 衝 突 . (是 什 麼 ?) 寄 存 器 是 troff 的 算 術 存 儲 類 , 用 一 到 二 個 字 符 命 名 . -mdoc 對 troff 和 ditroff 而 言 , 所 有 -mdoc 的 內 部 寄 存 器 由 兩 個 字 符 組 成 , 格 式 是 <大 寫 字 母 > <小 寫 字 母 > 如 ’Ar’, <小 寫 字 母 > <大 寫 字 母 > 如 ’aR’ 或 <字 母 > <數 字 > 如 ’C1’. 作 爲 亂 上 加 亂 , troff 有 它 自 己 的 內 部 寄 存 器 , 由 兩 個 小 寫 字 母 組 成 , 或 者 是 一 個 點 加 上 一 個 字 母 , 或 者 是 轉 義 字 符 (meta-character) 和 字 符 . 已 經 介 紹 過 的 示 例 中 展 示 過 怎 樣 用 轉 義 序 列 ’\&’ 防 止 解 釋 宏 . 這 辦 法 同 樣 適 用 於 內 部 寄 存 器 名 . 如 果 未 經 轉 義 的 寄 存 器 名 出 現 在 宏 請 求 的 參 數 列 表 中 , 其 後 果 不 可 預 測 . 一 般 說 來 , 如 果 大 段 的 文 字 沒 有 出 現 在 該 出 現 的 地 方 , 或 者 短 句 , 如 標 籤 , 消 失 了 , 多 半 是 這 個 地 方 誤 解 了 參 數 列 表 中 的 參 數 類 型 . 既 然 你 的 母 親 都 沒 打 算 讓 你 記 住 那 些 亂 七 八 糟 的 東 西 , 那 就 用 一 種 辦 法 來 找 出 參 數 是 否 有 效 : ’.Db’ (debug) 宏 可 以 顯 示 出 對 大 多 數 宏 的 參 數 列 表 的 解 釋 . 諸 如 ’.Pp’ 之 類 的 宏 不 包 含 調 試 信 息 , 但 是 所 有 可 調 用 宏 包 含 , 我 們 強 烈 建 議 一 旦 有 疑 點 , 打 開 ’.Db’ 宏 .

Usage: .Db [on | off] 在 這 個 示 例 中 , 我 們 把 介 於 debug 宏 之 間 的 文 本 故 意 弄 出 點 錯 誤 (標 誌 參 數 ’aC’ 應 該 寫 成 ’\&aC’ ):

.Db on
.Op Fl aC Ar file )
.Db off 結 果 輸 出 爲 :

DEBUGGING ON
DEBUG(argv) MACRO: ’.Op’ Line #: 2

DEBUGGING OFF 調 試 信 息 的 第 一 行 是 調 用 的 宏 名 , 這 裏 是 ’.Op’ 和 它 所 在 的 行 號 . 如 果 涉 及 了 一 個 或 多 個 文 件 (特 別 是 其 他 文 件 包 含 進 來 ), 行 號 有 可 能 失 靈 . 但 如 果 只 有 一 個 文 件 , 它 應 該 是 準 的 . 第 二 行 給 出 了 參 數 計 數 , 參 數 (’Fl’) 和 它 的 長 度 . 如 果 參 數 的 長 度 是 兩 個 字 符 , 將 會 測 試 看 它 能 否 執 行 (不 幸 的 是 ,含 有 非 零 值 的 寄 存 器 看 上 去 都 能 執 行 ). 第 三 行 給 出 分 配 給 類 的 空 間 , 以 及 類 的 類 型 . 這 裏 的 問 題 是 , 參 數 aC 不 應 該 可 執 行 . 類 的 四 種 類 型 是 字 符 串 , 可 執 行 類 , 結 束 標 點 , 和 開 始 標 點 . 最 後 一 行 顯 示 了 讀 入 的 完 整 參 數 行 . 下 個 例 子 裏 , 惹 禍 的 ’aC’ 被 轉 義 了 :

.Db on
.Em An escaped \&aC
.Db off

DEBUGGING ON
DEBUG(fargv) MACRO: ’.Em’ Line #: 2

DEBUGGING OFF 參 數’\&aC’ 表 現 出 同 樣 的 長 度 2, 這 是 因 爲 ’\&’ 序 列 的 長 度 爲 零 , 但 是 不 存 在 叫 做 ’\&aC’ 的 寄 存 器 , 因 此 它 的 類 型 是 字 符 串 . 其 他 診 斷 內 容 是 使 用 報 告 等 , 能 夠 自 我 解 釋 的 .

GROFF, TROFF AND NROFF

The -mdoc 宏 包 不 需 要 和 groff 的 兼 容 模 式 . 爲 了 便 於 在 線 閱 讀 , 這 個 宏 包 阻 止 了 分 頁 , 頁 頭 , 頁 腳 之 類 常 常 在 nroff 中 出 現 的 中 斷 . 此 時 即 使 在 手 冊 頁 尾 , groff (和 參 數 -Tascii ) 也 不 會 提 示 什 麼 . 對 分 頁 的 阻 止 使 得 nroff’d 文 件 不 適 合 硬 拷 貝 (hardcopy). 有 一 個 名 爲 ’cR’ 的 寄 存 器 可 以 通 過 在 文 件 /usr/src/share/tmac/doc-nroff (依 賴 於 宿 主 系 統 ) 中 置 零 , 恢 復 傳 統 風 格 . 相 關 文 件 FILES

/usr/share/tmac/tmac.doc 手 冊 宏 包
/usr/share/misc/mdoc.template 編 寫 手 冊 的 模 板
/usr/share/examples/mdoc/* 一 些 手 冊 頁 的 例 子 另 見 SEE ALSO

man(1), troff(1), mdoc(7)

BUGS 仍 然 沒 有 解 決 在 標 誌 參 數 中 的 連 字 符 , 在 描 述 DESCRIPTION 小 節 偶 爾 會 出 點 麻 煩 (在 連 字 符 處 斷 行 ). 文 檔 中 沒 有 聲 明 預 定 義 串 . 還 沒 有 把 3f 小 節 加 進 頭 例 程 (header routine) 中 .

’.Nm’ 字 體 不 應 當 在 NAME 小 節 中 改 變 . 應 該 檢 查 ’.Fn’ 防 止 行 太 短 的 時 候 斷 行 . 偶 然 它 會 斷 開 反 括 弧 , 而 有 時 候 如 果 某 行 已 滿 時 , 看 上 去 會 很 可 笑 . 當 使 用 nroff 格 式 化 文 檔 時 , 防 止 頁 頭 和 頁 腳 (不 是 初 始 的 頭 和 腳 ) 斷 開 的 方 法 有 可 能 偶 爾 在 頁 的 底 部 產 生 一 個 不 可 見 的 部 分 填 滿 的 行 (空 行 ). 列 表 和 顯 示 宏 不 做 任 何 保 存 , 顯 然 它 應 該 做 的 .

[中 文 版 維 護 人 ] 徐 明 <xuming [AT] users.net>

[中 文 版 最 新 更 新 ]

2003/05/13 《 中 國 Linux論 壇 man手 冊 頁 翻 譯 計 劃 》
http://cmpp.linuxforum.net 跋 本 頁 面 中 文 版 由 中 文 man 手 冊 頁 計 劃 提 供 。 中 文 man 手 冊 頁 計 劃 ： https://github.com/man-pages-zh/manpages-zh

BSD December 30, 1993 BSD