mdoc.samples

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’, 用來 說明 一個 帶引數的 選項: 為了 防止 把 兩個字元的字串 解釋成 宏名, 在這個 字串 前面 加上 ‘\&’ 轉義序列: 這裡的 字串 ‘Fl’ 和 ‘Ar’ 沒有 被解釋成 宏. 在 這篇文件 和 相應的 快速參考手冊 中, 引數列表 按 可呼叫引數 分析 的 宏 稱為 已分析, 可以 從 引數列表 呼叫 的 宏 稱為 可呼叫. 這裡 用的 術語 '分析' 可能是個 技術失誤, 幾乎 所有的 -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’) 保留住 反斜槓.

手冊頁結構分析 THE ANATOMY OF A MAN PAGE

手冊頁 可以 很容易的 透過 模板 構建, 模板 放在 /usr/share/misc/mdoc.template. 另外 在 /usr/share/examples/mdoc 目錄下 有一些 手冊頁 的 例子.

手冊頁的模板 A manual page template

模板中 的 第一個部分 是 (.Dd, .Os, .Dt) 宏; 文件日期, 手冊或其內容 針對的 作業系統, 手冊頁的標題 ((大寫)) 和 該手冊頁 所屬的節 (部分號). 這些宏 確認和標識了 這個手冊頁. 在 後面的 標題宏 TITLE MACROS 將 繼續 討論. 這個 模板中 的 其餘部分 是 小節首部 (section header) (.Sh); 其中 名稱 NAME, 總覽 SYNOPSIS 和 描述 DESCRIPTION 是 必不可少的. 這些 首部 在 頁結構宏域 中 討論 ( 介紹完 手冊域 之後 ) . 有一些 內容宏 被用來 示範 頁面佈局宏; 建議 接觸 頁面佈局宏 前 先看看 內容宏.

標題宏 TITLE MACROS

標題宏 是 頁結構宏域 的 第一部分, 但 在 過去, 人們 如果 編寫 手冊頁, 它 是 手冊的 第一部分, 也是 獨立部分. 這裡 設計了 三個宏 分別 描述 文件標題 或 手冊標題, 作業系統, 和 製作日期. 它們 放在 文件的 最前面, 一次 只 呼叫 一個, 用來 構建 文件的 頁頭 和 頁尾.

.Dt 文件標題 手冊區# [卷]

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

AMD	UNIX 歷史遺留的手冊文件 Ancestral Manual Documents
SMM	UNIX 系統管理員手冊 System Manager's Manual
URM	UNIX 參考手冊 Reference Manual
PRM	UNIX 程式設計師手冊 Programmer's Manual

預設的卷標 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’ 是 宏命令 或 宏請求, 緊隨其後 的 是 待處理的引數. 第二種 情況 下, 使用 內容宏 描述 一條 UNIX 命令 要 複雜 些; 一個 典型的 總覽 SYNOPSIS 命令列 顯示 如下: 這裡的 filter 是 命令名稱, 方括弧內 的 -flag 是一個 標誌 引數, 作為 可選引數 放在 代表 選項 的 方括弧內. 在 -mdoc 術語 中, infile 和 outfile 稱為 引數. 產生 上述效果 的 宏 是 這樣的: 第三種 情況 討論 命令 及其語法, 包括 它們的例子, 可能 還有 更多細節. 上面的例子裡, 可以把 infile 和 outfile 理解為 操作引數 operands 或 檔案引數 file arguments. 有些 命令列引數 羅列的 十分 長: 這裡 你 可能 討論 make 命令 和 它的引數 makefile, 作為 一個 標誌的引數, -f, 或者 討論 一個 可選的檔案操作物件 target. 在 具體的上下文 中, 這種細節 能夠 防止 混淆. 然而 -mdoc 宏包中 沒有為 標誌的引數 準備 宏. 作為 替代 是 ‘Ar’ 引數宏, 用於 描述 操作物件 或 檔案引數 如 target 以及 標誌的引數 如 variable. 上面的 make 命令列 是 這樣 產生的: 在 Keeps 小節中 將會 解釋 ‘.Bk’ 和 ‘.Ek’ 宏.

基本語法 General Syntax

手冊宏域 和 基本正文宏域 的 宏 有著 相似的語法, 僅有 微小差別: ‘.Ar’, ‘.Fl’, ‘.Nm’, 和 ‘.Pa’ 僅當 無引數呼叫時 才有 區別; ‘.Fn’ 和 ‘.Xr’ 的 引數列表 要求 一定的 順序; ‘.Op’ 和 ‘.Fn’ 宏有巢狀限制. 所有的 內容宏 能夠 識別和正確處理 標點符號, 每個 標點符號 要在 前面 用 空格 隔開. 如果 給出 這樣的 宏請求: 結果是: 標點符號 沒有 被識別 出來, 全都按 原文字型 輸出. 如果 標點符號 前面用 空格符 隔開: 結果是: 標點符號 被 識別出來 了, 預設的字型 也 有別於 原文文字的字型. 用 ‘\&’. 轉義符 可以 去掉 標點字元 的 特殊意義. Troff 作為 宏語言 有一定 的 限制, 當 表達的字串 中 含有 數學, 邏輯 或 引用 符號時 將 難於 處理: 問題是 troff 會 認為 它 應該 執行或運算 這些 符號 代表的操作. 要 防止 這一點 可以 用 ‘\&’ 轉義 這些 字元. 典型語法 在 下面 顯示的 第一個 內容宏 中 可以見到, ‘.Ad’.

手冊域 MANUAL DOMAIN

地址宏 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 函式風格 的 模型.

.Fn getchar

getchar()

.Fn strlen ) ,

strlen()),

.Fn \*qint align\*q \*qconst * char *sptrs\*q,

int align(const * char *sptrs),

不帶引數呼叫 ‘.Fn’ 是一個錯誤. ‘.Fn’ 宏可以被 (其他宏) 分析和呼叫, 注意 任何 對 其他宏 的 呼叫 應該在 ‘.Fn’ 宏呼叫 的 結尾處 給出 標記 (反括弧). 對於 八個 引數 以上的 函式 (儘管少見), 可以 用 宏 ‘.Fo’ (function open) 和 ‘.Fc’ (function close) 配合 ‘.Fa’ (function argument) 宏 的 使用, 突破 引數 過多 的 限制, 例如: 產生: 宏 ‘.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’ 宏: 產生: [[-k kilobytes] [-i interval] [-c count]] 宏 ‘.Op’, ‘.Oc’ 和 ‘.Oo’ 可以被 (其他宏) 分析和呼叫.

路徑名 Pathnames

‘.Pa’ 宏 用於 格式化 路徑 或 檔名. ‘.Pa’ 宏可以被 (其他宏) 分析和呼叫.

變數 Variables

基本的 變數 參考: 不帶引數呼叫 ‘.Va’ 宏是個錯誤. ‘.Va’ 宏可以被 (其他宏) 分析和呼叫.

手冊頁參照 Manual Page Cross References

‘.Xr’ 宏 把 第一個引數 當做 手冊頁 名稱, 第二個引數, 如果 存在, 當做 標點符號 或 手冊頁 的 部分號 (節號). 剩下 所有的引數 視做 標點符號. ‘.Xr’ 宏可以被 (其他宏) 分析和呼叫. 不帶引數呼叫 ‘.Xr’ 宏是個錯誤.

基本正文宏域 GENERAL TEXT DOMAIN

AT&T 宏

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

BSD 宏

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

FreeBSD 宏

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

字首宏不能被 (其他宏) 呼叫, 但是可以被分析.

這個 ‘.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’ 宏的一個示例, 用 空格模式宏 把 空格 去掉: 產生 還有一個: 產生 另一個示例用 ‘.Xo’ 和 引用宏: 測試一個變數的值. 產生 上面 所有的例子 都在 ‘.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’ 配製裝置用途宏. 其他一些 宏 可能 用來 產生 概要行, 象下面的:

下面 用到的 宏

.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’ 小節, 例如, 這樣 設 小節:

段落和空行 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’ 宏可以被 (其他宏) 分析和呼叫. 不帶引數 呼叫 ‘.Em’ 宏 是 一個錯誤.

.Li

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

Usage: .Li argument ...

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

.Sy

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

Usage: .Sy symbol ...

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

下面是 產生 這個例子 的 源文字: 這是 含有 兩個表項 的 懸掛列表:

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.

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

預定義串 PREDEFINED STRINGS

下面的串 是 預定義的, 可以 用在 troff 的 串翻譯序列 ‘\*(xx’ 中, 這裡的 xx 就是 定義的 串名; 以及 串翻譯序列 ‘\*x’, 這裡的 x 是串名. 翻譯序列 可以 用在 文字 的 任何地方.

String	Nroff	Troff
<=	<=	≤
>=	>=	≥
Rq	''	”
Lq	``	“
ua	^	↑
aa	'	´
ga	`	`
q	"	"
Pi	pi	pi
Ne	!=	≠
Le	<=	≤
Ge	>=	≥
Lt	<	>
Gt	>	<
Pm	+-	±
If	infinity	infinity
Na	NaN	NaN
Ba	|	|

注意: 那個 名為 ‘q’ 的 串 應該 寫成 ‘\*q’, 因為 它 只有 一個字元.

診斷 DIAGNOSTICS

-mdoc 的 除錯系統 比較 有限, 但是 可以 幫助你 檢測出 微妙的 錯誤, 例如 引數名 和 內部暫存器 或 宏名 衝突. (是什麼?) 暫存器 是 troff 的 算術儲存類, 用 一到二個字元 命名. -mdoc 對 troff 和 ditroff 而言, 所有 -mdoc 的 內部暫存器 由 兩個字元 組成, 格式是 <大寫字母> <小寫字母> 如 ‘Ar’, <小寫字母> <大寫字母> 如 ‘aR’ 或 <字母> <數字> 如 ‘C1’. 作為 亂上加亂, troff 有 它 自己的 內部暫存器, 由 兩個 小寫字母 組成, 或者 是 一個點 加上 一個字母, 或者 是 跳脫字元 (meta-character) 和 字元. 已經 介紹過的 示例中 展示過 怎樣用 轉義序列 ‘\&’ 防止 解釋宏. 這辦法 同樣 適用於 內部暫存器名. 如果 未經轉義的 暫存器名 出現在 宏請求的 引數列表 中, 其 後果 不可預測. 一般說來, 如果 大段的文字 沒有 出現在 該出現的 地方, 或者 短句, 如標籤, 消失了, 多半是 這個地方 誤解了 引數列表中的 引數型別. 既然 你的母親 都 沒打算 讓你 記住 那些 亂七八糟的 東西, 那就 用 一種辦法 來 找出 引數 是否 有效: ‘.Db’ (debug) 宏 可以 顯示出 對 大多數宏 的 引數列表的 解釋. 諸如 ‘.Pp’ 之類 的 宏 不包含 除錯資訊, 但是 所有 可呼叫宏 包含, 我們 強烈建議 一旦 有 疑點, 開啟 ‘.Db’ 宏. 在 這個 示例中, 我們把 介於 debug 宏 之間 的 文字 故意 弄出點 錯誤 (標誌引數 ‘aC’ 應該 寫成 ‘\&aC’ ): 結果輸出為: 除錯資訊的 第一行 是 呼叫的 宏名, 這裡是 ‘.Op’ 和 它 所在的 行號. 如果 涉及了 一個 或 多個 檔案 (特別是 其他檔案 包含進來), 行號有可能失靈. 但如果 只有 一個檔案, 它 應該是 準的. 第二行 給出了 引數計數, 引數 (‘Fl’) 和 它的長度. 如果 引數的長度 是 兩個字元, 將會 測試 看它 能否 執行 (不幸的是,含有 非零值 的 暫存器 看上去 都能執行). 第三行 給出 分配給類的 空間, 以及 類的型別. 這裡的 問題是, 引數 aC 不應該 可執行. 類的 四種類型是 字串, 可執行類, 結束標點, 和開始標點. 最後一行 顯示了 讀入的 完整 引數行. 下個例子裡, 惹禍的 ‘aC’ 被轉義了: 引數 ‘\&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),

BUGS

仍然 沒有 解決 在 標誌引數中的 連字元, 在 描述 DESCRIPTION 小節 偶爾 會 出點麻煩 (在 連字元處 斷行). 文件中 沒有 宣告 預定義串. 還沒有 把 3f 小節 加進 頭例程 (header routine) 中. ‘.Nm’ 字型 不應當在 NAME 小節 中 改變. 應該 檢查 ‘.Fn’ 防止 行 太短 的 時候 斷行. 偶然 它會 斷開 反括弧, 而 有時候 如果 某行 已滿時, 看上去 會 很可笑. 當 使用 nroff 格式化 文件 時, 防止 頁頭和頁尾 (不是 初始的 頭和腳) 斷開 的 方法 有可能 偶爾 在 頁的底部 產生 一個 不可見的 部分填滿的 行 (空行). 列表和顯示宏不做任何儲存, 顯然它應該做的.

[中文版維護人]

徐明 <[email protected]>

[中文版最新更新]

2003/05/13

《中國Linux論壇man手冊頁翻譯計劃》

http://cmpp.linuxforum.net

跋

本頁面中文版由中文 man 手冊頁計劃提供。 中文 man 手冊頁計劃： https://github.com/man-pages-zh/manpages-zh