宏的用法 Macro Usage

在 troff(1) 裡, 宏呼叫的形式 是 在行首 以 ‘.’ (句點符) 起始, 緊隨其後 是 作為 宏名 的 兩個字元. 引數 跟在 宏名 之後, 用 空格符 隔開. 這個 位於行首的 句點符 使 troff(1) 把 緊隨其後 的 兩個字元 視作 宏名. 在 某些情況下 要把 ‘.’ (句點符) 放在 行首, 但不希望 被理解成 宏請求, 方法是 在 ‘.’ (句點) 前 使用 ‘\&’ 轉義序列. ‘\&’ 被 解釋成 一段 長度為零 的 空白, 所以 不會 在 輸出端 顯示 出來.

一般說來, troff(1) 宏 最多 接受 九個引數, 忽略掉 其餘的. 大多數 在 -mdoc 裡的 宏 支援 九個引數, 某些場合 可以 續加 引數, 或擴充套件到 下一行. (見 擴充套件 Extensions). 有些宏 能夠 處理 引號 引起來的 引數 (見 下面的 在引數中傳遞空格符).

大多數 -mdoc 的 基本正文宏域 和 手冊宏域 的宏 擁有 一種特性, 表現在 把 引數列表 當成 可呼叫的宏 分析 (解釋). 這意味著 如果 引數列表裡的引數 是 普通正文宏域 或 手冊宏域 裡的 宏, 並且 是 可呼叫宏, 那麼 處理的時候 會 執行 或 呼叫. 這種情況下的 引數, 即 宏名, 不需要 用 ‘.’ (句點符) 引導. 這種風格 使 很多 宏 巢狀 在 一起; 例如 這個 選項宏 ‘.Op’, 可能 呼叫 標誌和引數宏, ‘Fl’ 和 ‘Ar’, 用來 說明 一個 帶引數的 選項:

為了 防止 把 兩個字元的字串 解釋成 宏名, 在這個 字串 前面 加上 ‘\&’ 轉義序列:

這裡的 字串 ‘Fl’ 和 ‘Ar’ 沒有 被解釋成 宏. 在 這篇文件 和 相應的 快速參考手冊 mdoc(7) 中, 引數列表 按 可呼叫引數 分析 的 宏 稱為 已分析, 可以 從 引數列表 呼叫 的 宏 稱為 可呼叫. 這裡 用的 術語 '分析' 可能是個 技術失誤, 幾乎 所有的 -mdoc 宏 都 被分析, 既 用它 指 可呼叫宏, 又 指 有 呼叫 其他宏的 能力, 顯得 很笨拙.

在引數中傳遞空格符 Passing Space Characters in an Argument

某些時候 我們 希望 能夠 把 含有 一個或多個 空格符 的 字串 作為 單個引數 傳遞. 如果 要 突破 九個引數的限制, 或者 傳遞給 宏 的 引數 需要 一些 特定佈置, 這個 能力 是必須的. 例如, 函式宏 ‘.Fn’ 的 第一個引數 是 函式名稱, 剩下的引數 作為 函式的引數. ANSI C 規定 函式的引數 在 圓括弧內 宣告, 每個 引數 至少 由 兩個 標示符 組成. 例如, int foo.

有 兩個方法 傳遞 嵌有空格符 的 引數. 補充一點: 不幸的是, 在 AT&T troff 中, 那個 最容易的方法, 就是 作為 單個 引數 傳遞 兩個引號之間的 字串和空格符, 非常 消耗 時間 和 記憶體空間. 雖然 它 對 groff 並不費事, 但是 為了 可移植性, 這種 做法 只限於 下列 有迫切需要 的 宏:

一種 傳遞 含空格符字串 的 方法 是 用 ‘\ ’ 硬編碼 或 不可填充空格符, 也就是 在 空格符 前 加上 轉義符 ‘\’. 這個 方法 適用於 任何宏, 但 有個 副效應, 它 干擾了 對 長行 的 調整. Troff 把 這種 硬編碼的 空格符 看作 可顯示字元, 因此 無法 在需要的時候 把 字串 分段 或 換行. 這種 方法 適用於 字串 不會 到達 行邊界 時, 例如:

如果 忽略 ‘\’ 或 引號, ‘.Fn’ 宏 會認為 有 三個引數, 結果 成為:

如果 想知道 引數列表 到達 行邊界 時 出現什麼, 參看 BUGS 小節.

尾部的空白符 Trailing Blank Space Characters

Troff 可能 被 行尾的 空白符 搞亂, 它的防範規則 是 消除 所有 位於行末 的 空白符. 如果 堅持 在 行末 加上 空白符, 可以 用 硬空格符 和 ‘\&’ 跳脫字元. 例如, ‘string\ \&’.

轉義特殊字元 Escaping Special Characters

特殊字元, 如 換行符 ‘\n’, 是 透過 用 ‘\e’ 替換 ‘\’ (e.g.例如 ‘\en’) 保留住 反斜槓.

手冊頁的模板 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 是 必不可少的. 這些 首部 在 頁結構宏域 中 討論 ( 介紹完 手冊域 之後 ) . 有一些 內容宏 被用來 示範 頁面佈局宏; 建議 接觸 頁面佈局宏 前 先看看 內容宏.

名稱背後 What's in a name...

手冊宏域 的 宏名 來自 非正式的 日常用語, 用來 描述 命令, 子程式 及其 相關檔案. 在 寫 手冊頁 時, 文字用語 有些 輕微的變化, 分別描述 三個 不同 應用面. 首先是 -mdoc 宏請求 的 用法. 其次, 用 -mdoc 宏 描述 UNIX 命令. 最後, 對 使用者 具體的描述 這條命令; 也就是 在 手冊頁 正文 裡 討論這條命令.

第一種 情況 下, troff(1) 宏 本身 就是 一種 命令; troff 命令 的 基本語法 是:

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

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

.Nm filter
.Op Fl flag
.Ar infile outfile

第三種 情況 討論 命令 及其語法, 包括 它們的例子, 可能 還有 更多細節. 上面的例子裡, 可以把 infile 和 outfile 理解為 操作引數 operands 或 檔案引數 file arguments. 有些 命令列引數 羅列的 十分 長:

這裡 你 可能 討論 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’ 宏有巢狀限制. 所有的 內容宏 能夠 識別和正確處理 標點符號, 每個 標點符號 要在 前面 用 空格 隔開. 如果 給出 這樣的 宏請求:

結果是:

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

結果是:

標點符號 被 識別出來 了, 預設的字型 也 有別於 原文文字的字型.

用 ‘\&’. 轉義符 可以 去掉 標點字元 的 特殊意義. Troff 作為 宏語言 有一定 的 限制, 當 表達的字串 中 含有 數學, 邏輯 或 引用 符號時 將 難於 處理:

{+,-,/,*,%,<,>,<=,>=,=,==,&,`,',"}

問題是 troff 會 認為 它 應該 執行或運算 這些 符號 代表的操作. 要 防止 這一點 可以 用 ‘\&’ 轉義 這些 字元. 典型語法 在 下面 顯示的 第一個 內容宏 中 可以見到, ‘.Ad’.

地址宏 Address Macro

地址宏 用 這種 格式 標明地址: addr1[,addr2[,addr3]].

不帶引數 呼叫 ‘.Ad’ 是個 錯誤. ‘.Ad’ 可以被 (其他宏) 呼叫和分析.

作者名稱 Author Name

The ‘.An’ 宏用以 說明 這個文件的 描述物件的 作者, 或者 這篇手冊頁的 作者. 名字 資訊 後面的 其他引數 被認為是 標點符號.

‘.An’ 宏可以被 (其他宏) 分析和呼叫, 不帶引數呼叫 ‘.An’ 是個錯誤.

引數宏 Argument Macro

當 引用 命令列引數時 可以使用 ‘.Ar’ 引數宏.

如果不帶引數呼叫 ‘.Ar’ 宏, 預設為 ‘file ...’. ‘.Ar’ 宏可以被 (其他宏) 分析和呼叫.

配置定義 (手冊第四部分) Configuration Declaration

‘.Cd’ 宏用於描述 config(8) 對 裝置介面的定義 (手冊第四部分). 這個宏 接受 引號內的引數 (只能是雙引號).

命令修飾 Command Modifier

命令修飾宏和 ‘.Fl’ (標誌) 命令相似, 除了 ‘.Cm’ 宏 不在 任何引數 前 加 短橫線 (dash). 傳統的標誌 以 短橫線 開頭, 但 一些 命令 或 命令的子集 不用這個. 命令修飾宏 也可以 和 互動命令 結合 使用, 如 編輯命令. 另見 Flags.

已定義的變數 Defined Variables

在 標頭檔案 中 已經 定義了的變數 用 ‘.Dv’ 宏說明.

不帶引數呼叫 ‘.Dv’ 是個錯誤. ‘.Dv’ 宏可以被 (其他宏) 分析和呼叫.

Errno's (僅供手冊第二部分)

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

不帶引數呼叫 ‘.Er’ 宏是個錯誤. ‘.Er’ 宏可以被 (其他宏) 分析和呼叫.

環境變數 Environment Variables

‘.Ev’ 宏說明一個環境變數.

不帶引數呼叫 ‘.Ev’ 宏是個錯誤. ‘.Ev’ 宏可以被 (其他宏) 分析和呼叫.

函式引數 Function Argument

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

不帶引數呼叫 ‘.Fa’ 宏是個錯誤. ‘.Fa’ 宏可以被 (其他) 宏分析和呼叫.

函式宣告 Function Declaration

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

在 總覽 SYNOPSIS 小節, 如果 已經 說明了 某個 函式, 並且 沒有 出現 省略號, 則 ‘.Fd’ 宏請求 能夠 產生 一個 斷行. 在 函式 和 函式宣告 之間, 垂直方向上 產生 一定的 空白.

標誌 Flags

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

如果 ‘.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

產生:

宏 ‘.Fo’ 和 ‘.Fc’ 可以被 (其他宏) 分析和呼叫. 在 總覽 SYNOPSIS 小節, 函式 總是 位於 行的開始 處. 如果 在 總覽 SYNOPSIS 小節 有 一個以上的 函式宣告, 而且 函式型別 沒有 說明, 則 會產生 一個 斷行. 在 函式 和 函式 的 垂直方向 上 產生 一定的 空白. 此時 ‘.Fn’ 宏 不按 troff 的 行長 檢查 單詞 邊界, 有可能 難看的 從 單詞中間 斷開. 以後 會 解決 這個 問題.

函式型別 Function Type

這個宏 設計 用在 總覽 SYNOPSIS 小節. 它 可以 毫無困難的 用在 手冊頁的 其他 地方, 但 它的 主要 目的 是 為 第二 和 第三部分 手冊頁的 總覽 SYNOPSIS 小節, 以 核心標準形式 (kernel normal form) 描述 函式型別 (它 導致 斷行, 在 下一行 顯示 函式 名稱).

‘.Ft’ 宏不能被其他宏呼叫.

互動命令 Interactive Commands

宏 ‘.Ic’ 用於 說明 互動 或 內部命令.

不帶引數呼叫 ‘.Ic’ 是個錯誤. ‘.Ic’ 宏可以被 (其他宏) 分析和呼叫.

名稱宏 Name Macro

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

‘.Nm’ 宏可以被 (其他宏) 分析和呼叫.

選項 Options

‘.Op’ 宏 把 命令列上 剩餘的 所有 引數 用 方括弧 括在一起, 把 最後的 標點符號 放到 方括弧 外面. 宏 ‘.Oc’ 和 ‘.Oo’ 用於 處理 跨行.

應用 ‘.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’ 宏 用於 格式化 路徑 或 檔名.

‘.Pa’ 宏可以被 (其他宏) 分析和呼叫.

變數 Variables

基本的 變數 參考:

不帶引數呼叫 ‘.Va’ 宏是個錯誤. ‘.Va’ 宏可以被 (其他宏) 分析和呼叫.

手冊頁參照 Manual Page Cross References

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

‘.Xr’ 宏可以被 (其他宏) 分析和呼叫. 不帶引數呼叫 ‘.Xr’ 宏是個錯誤.

AT&T 宏

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

‘.At’ 宏 不能 被 (其他宏) 分析, 也 不能 被 (其他宏) 呼叫. 該宏 最多 接受 兩個 引數.

BSD 宏

‘.Bx’ 宏可以被 (其他宏) 分析和呼叫.

FreeBSD 宏

Usage: .Fx Version.release ...

‘.Fx’ 宏 不能 被 (其他宏) 分析, 也 不能 被 (其他宏) 呼叫. 該宏 最多 接受 兩個 引數.

UNIX 宏

‘.Ux’ 宏可以被 (其他宏) 分析和呼叫.

嵌入和引用宏 Enclosure and Quoting Macros

嵌入 的 概念 和 引用 類似. 把 一句 或 多句 引用物件 嵌到 一對 字元 中, 象 引號 或 括弧. 本篇 文件中 將 混用 術語 ‘嵌入’ 和 ‘引用.’ 大多數 單行的 引用宏名 用 一個 小寫字母 ‘q’ 結尾, 表明 這是 一個 引用(quoting), 但 也有 不規則變化. 每個 引用宏 都有 一對 開始(open) 和 結束(close) 宏, 各自 以 ‘o’ 和 ‘c’ 結尾. 在 某些限制時 這些宏 可以 跨行 使用, 單行的引用宏 可以 巢狀在裡面.

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

.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’ (無空格) 宏 執行 類似的 字尾 功能.

引用舉例:

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

No-Op 或正文宏 or Normal Text Macro

宏 ‘.No’ 用在 某個 宏命令列 上, 意如其名, 將 不 被格式化, 語法 遵循 一般的 內容宏.

無空格宏 Space Macro

‘.Ns’ 在 宏請求 之間 消除 不需要的 空格. 它 用在 舊式風格的 引數列表 中, 標誌和引數 間 沒有 空格:

注意: ‘.Ns’ 宏 在 消除空格後 總會 呼叫 ‘.No’ 宏, 除非 還有 其他 宏名 跟在 後面. ‘.Ns’ 宏可以被 (其他宏) 分析和呼叫.

手冊頁對照參考 Section Cross References

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

參考和引言 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. 下面的宏 試圖 適度的 處理 參考資料. 最好情況時, 這些宏 便於 手工 插入 一段 相關風格的 參考資料.

用 ‘%’ 符號 開始的 宏 不能被 (其他宏) 呼叫, 只能 被 trade name macro 分析, 結果 返回給 呼叫者 (此時 結果 不太好 預測). 其目的 是 允許 trade name 能夠 很好的 列印在 troff/ditroff 的 輸出端.

返回值 Return Values

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

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

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

Trade Names (或縮略和型別名)

trade name 宏 一般說來 是 一個 很小的 大寫字母宏, 用於 所有 大於 兩個字元的 大寫單詞.

‘.Tn’ 宏可以被 (其他宏) 分析和呼叫.

擴充套件引數 Extended Arguments

‘.Xo’ 和 ‘.Xc’ 宏 可以 在 宏的邊界 擴充套件 引數列表. 如果 某個宏 要求 所有的引數 在 一行上 出現, 則 引數列表 不能 在 這兒 被 擴充套件. 例如 ‘.Op’.

這裡有 ‘.Xo’ 宏的一個示例, 用 空格模式宏 把 空格 去掉:

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

產生

還有一個:

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

產生

另一個示例用 ‘.Xo’ 和 引用宏: 測試一個變數的值.

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

產生

上面 所有的例子 都在 ‘.It’ (list-item) 宏 的 引數列表 中 使用了 ‘.Xo’ 宏. 擴充套件宏 不經常 使用, 一般用來 擴充套件 list-item 宏 的 引數列表. 這也 不幸的 是 擴充套件宏 最苛刻的 地方. 前兩個例子裡 空格 被去掉; 第三個 例子中, 希望 能 輸出 部分 空格, 而不是 全部. 在 這種情況下 用 這些宏, 要 確保 ‘.Xo’ 和 ‘.Xc’ 宏 擺放到 第三個例子 中 示範的位置. 如果 ‘.Xo’ 宏 沒有 單獨 出現在 ‘.It’ 的 引數表 中, 則 無法預測 空格 情況. 這種情況下, ‘.Ns’ (no space macro) 一定 不能 作為 一行的 第一個宏 或 最後一個宏. 當前 BSD 釋出的 超過 900個 手冊頁 (事實上大約1500個) 中, 只有 十五個 用到了 ‘.Xo’ 宏.

小節首部 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

帶有 可選 寬度項的 標記列表 可以 控制 標記的 寬度.

源文字是:

.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

可接受的 寬度說明:

如果 沒有 為 標記列表型別 指定 寬度, 第一次 呼叫 ‘.It’ 的 時候, 格式化軟體 試圖 決定 適當的寬度. 如果 ‘.It’ 的 第一個 引數 是 可呼叫宏, 就 使用 這個宏的 預設寬度, 就像 把 宏名 當做寬度. 可是 如果 列表中 的 其他表項 得到 另一個 可呼叫宏, 則 認為 它是 新的, 巢狀的 列表.