.\" Copyright (c) 1990, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"
.\" This tutorial sampler invokes every macro in the package several
.\" times and is guaranteed to give a worst case performance
.\" for an already extremely slow package.
.\"
.Dd December 30, 1993
.Os
.Dt MDOC.SAMPLES 7
.Sh NAME (名字)
.Nm mdoc.samples
.Nd 用
.Nm \-mdoc
編寫
.Bx
手冊 的 示範教程
.Sh SYNOPSIS (總覽)
.Nm man mdoc.samples
.Sh DESCRIPTION (描述)
這個 示範教程 用於 編寫
.Bx
手冊頁 (manual page), 它 使用了
.Nm \-mdoc
宏定義包, 這是個
.Em 基於內容
和
.Em 基於宏域 (domain Ns \-base)
的 格式化包, 交由
.Xr troff 1 
處理. 它的 前身
.Xr \-man 7
包, 定義了 頁面佈局 (page layout), 但是 把 諸如 字體控制 和 其他 排版 細節 
留給了 每一個 作者. 在
.Nm \-mdoc 
包裏, 頁面佈局宏 構成了
.Em "頁結構宏域 (page structure domain)"
它 由 標題, 小節首部, 顯示 (displays) 和 列表 宏 組成. 這些 基本項目 影響
正文 在 格式化頁上 的 物理位置.
作爲 頁結構宏域 的 補充, 這裏 還 定義了 另外 兩個 宏域, 手冊宏域 和
基本正文宏域. 基本正文宏域 定義了 一些 宏, 執行 例如 引文 或 文字強調 
之類的任務.
手冊宏域 定義的宏 是 非正式 日常用語 的 子集, 用於 描述 命令, 例程
和 相關的
.Bx
文件.
手冊宏域裏 的 宏 用來處理 命令名, 命令行參數和選項, 函數名稱, 函數參數,
路徑, 變量, 以及 到 其他手冊頁 的 參照 等.
這些 域項 留有 爲 作者 和 手冊頁的 未來用戶 設置的 值.
希望 從 手冊集中 獲得的 一致性 能夠爲 將來的 文檔工具 提供 更簡單的 轉換.
.Pp
從 整個的
.Ux
手冊頁 上 來看, 每個 手冊項
可以 簡單的 理解爲 一個 man page, 不用 注意 它的 實際長度, 
也沒有 性別歧視 意圖. (譯註: 可能是雙關語, man page...男人頁)
.Sh 開始 GETTING STARTED
因爲 人們 通常是 爲了 能夠 馬上 使用 這些材料 的 時候 才 閱讀 教程，所以 
我們 假設 此文檔的 用戶 是 缺乏耐心的．下面 簡述一下 這份文檔 剩餘部分 
的 組織:
.Bl -enum -offset indent
.It
.Tn "TROFF 特性"
.Bl -tag -width flag -compact -offset indent
.It "使用宏" .
.It "參數中傳遞空白符" .
.It "尾部的空白符" .
.It "轉義特殊字符" .
.El
.It
.Tn "手冊頁的結構分析"
.Bl -tag -width flag -compact -offset indent
.It "手冊頁的模板" .
.El
.It
.Tn "標題宏" .
.It
.Tn "手冊宏域和基本正文宏域的介紹" .
.Bl -tag -width flag -compact -offset indent
.It "名稱背後 ..." .
.It "基本語法" .
.El
.It
.Tn "手冊宏域"
.Bl -tag -width flag -compact -offset indent
.It "地址" .
.It "作者名字" .
.It "參數" .
.It "配置聲明 (僅用於手冊第四部分)" .
.It "命令修飾" .
.It "已定義的變量" .
.It "Errno's (僅用於手冊第二部分)" .
.It "環境變量" .
.It "函數參數" .
.It "函數聲明" .
.It "標誌 (Flags)" .
.It "函數 (庫例程)" .
.It "函數類型" .
.\" .It "頭文件 Header File (源代碼嵌入 including source code)" .
.It "交互命令" .
.It "名稱" .
.It "選項" .
.It "路徑" .
.It "變量" .
.It "參照" .
.El
.It
.Tn "基本正文宏域"
.Bl -tag -width flag -compact -offset indent
.It "AT&T 宏" .
.It "BSD 宏" .
.It "FreeBSD 宏" .
.It "UNIX 宏" .
.It "嵌入/引用宏 (Enclosure/Quoting)"
.Bl -tag -width flag -compact -offset indent
.It "尖括弧引用/嵌入" .
.It "方括弧引用/嵌入" .
.It "雙引號引用/嵌入宏" .
.It "圓括弧引用/嵌入" .
.It "單引號引用/嵌入" .
.It "前綴宏" .
.El
.It "No\-Op 或正文宏" .
.It "消除空白宏" .
.It "手冊節對照" .
.It "參考和引用" .
.It "返回值 (僅用於手冊頁第二和第三部分)"
.It "Trade Names (縮略和類型名稱)" .
.It "參數擴展" .
.El
.It
.Tn "頁結構宏域"
.Bl -tag -width flag -compact -offset indent
.It "小節首部" .
.It "段落和空行" .
.It "保持 (Keeps)" .
.It "顯示" .
.It "字體模式 (加重, 原文和 Symbolic)" .
.It "列表和欄" .
.El
.It
.Tn "預定義串"
.It
.Tn "診斷"
.It
.Tn "用 GROFF, TROFF 和 NROFF 格式化"
.It
.Tn "臭蟲 BUGS"
.El
.ne 7
.Sh TROFF 特性
使用
.Nm \-mdoc
宏包 的 目的 是 簡化 寫手冊頁 的 過程. 理論上講, 要使用
.Nm \-mdoc
不一定 要 學習
.Xr troff 1
的 隱藏細節; 然而, 有些 限制 無法迴避, 最好 把它們 擺平.
而且 你 應該 知道, 這個 宏包 的 速度 比較
.Em 慢.
.Ss 宏的用法 Macro Usage
在
.Xr troff 1 
裏, 宏調用的形式 是 在行首 以
.Ql \&\.
(句點符) 起始, 緊隨其後 是 作爲 宏名 的 兩個字符. 參數 跟在 宏名 之後,
用 空格符 隔開. 這個 位於行首的 句點符 使
.Xr troff 1
把 緊隨其後 的 兩個字符 視作 宏名. 在 某些情況下 要把
.Ql \&\.
(句點符) 放在 行首, 但不希望 被理解成 宏請求, 方法是 在
.Ql \&\.
(句點) 前 使用
.Ql \e&
轉義序列.
.Ql \e&
被 解釋成 一段 長度爲零 的 空白, 所以 不會 在 輸出端 顯示 出來.
.Pp
一般說來,
.Xr troff 1
宏 最多 接受 九個參數, 忽略掉 其餘的. 大多數 在
.Nm \-mdoc
裏的 宏 支持 九個參數, 某些場合 可以 續加 參數, 或擴展到 下一行. (見
.Sx 擴展 Extensions ) .
有些宏 能夠 處理 引號 引起來的 參數 (見 下面的
.Sx 在參數中傳遞空格符 ) .
.Pp
大多數
.Nm \-mdoc
的 基本正文宏域 和 手冊宏域 的宏 擁有 一種特性, 表現在 把 參數列表 當成
可調用的宏 
.Em 分析 (解釋) .
這意味着 如果 參數列表裏的參數 是 普通正文宏域 或 手冊宏域
裏的 宏, 並且 是 可調用宏, 那麼 處理的時候 會 執行 或 調用.
這種情況下的 參數, 即 宏名, 不需要 用
.Ql \&\.
(句點符) 引導.
這種風格 使 很多 宏 嵌套 在 一起; 例如 這個 選項宏
.Ql \&.Op ,
可能
.Em 調用
標誌和參數宏,
.Ql \&Fl
和
.Ql \&Ar ,
用來 說明 一個 帶參數的 選項:
.Bl -tag -width "\&.Op \&Fl s \&Ar bytes" -offset indent
.It Op Fl s Ar bytes
來自
.Li \&.Op \&Fl s \&Ar bytes
.El
.Pp
爲了 防止 把 兩個字符的字符串 解釋成 宏名, 在這個 字符串 前面 加上
.Ql \e& 
轉義序列:
.Bl -tag -width "\&.Op \&Fl s \&Ar bytes" -offset indent
.It Op \&Fl s \&Ar bytes
來自
.Li \&.Op \e&Fl s \e&Ar bytes
.El
.Pp
這裏的 字符串
.Ql \&Fl
和
.Ql \&Ar
沒有 被解釋成 宏.
在 這篇文檔 和 相應的 快速參考手冊
.Xr mdoc 7
中, 參數列表 按 可調用參數 分析 的 宏 稱爲 已分析, 可以 從 參數列表
調用 的 宏 稱爲 可調用.
這裏 用的 術語 '分析' 可能是個 技術失誤, 幾乎 所有的
.Nm \-mdoc
宏 都 被分析, 既 用它 指 可調用宏, 又 指 有 調用 其他宏的 能力, 顯得 很笨拙.
.Ss 在參數中傳遞空格符 Passing Space Characters in an Argument
某些時候 我們 希望 能夠 把 含有 一個或多個 空格符 的 字符串 作爲 單個參數
傳遞. 如果 要 突破 九個參數的限制, 或者 傳遞給 宏 的 參數 需要 一些 特定佈置, 
這個 能力 是必須的. 例如, 函數宏
.Ql \&.Fn
的 第一個參數 是 函數名稱, 剩下的參數 作爲 函數的參數.
.Tn "ANSI C"
規定 函數的參數 在 圓括弧內 聲明, 每個 參數 至少 由 兩個 標示符 組成.
例如,
.Fa int foo .
.Pp
有 兩個方法 傳遞 嵌有空格符 的 參數.
.Em 補充一點 :
不幸的是, 在
.Tn AT&T
.Xr troff 
中, 那個 最容易的方法, 就是 作爲 單個 參數 傳遞 兩個引號之間的 
字符串和空格符, 非常 消耗 時間 和 內存空間.
雖然 它 對
.Xr groff
並不費事, 但是 爲了 可移植性, 這種 做法 只限於 下列 有迫切需要 的 宏:
.Pp
.Bl -tag -width 4n -offset indent -compact
.It Li \&Cd
配置聲明 (手冊第四部分
.Sx 概要 SYNOPSIS )
.It Li \&Bl
列表開始 (指定寬度的)
.It Li \&Em
加重文字
.It Li \&Fn
函數 (手冊第二, 四部分)
.It Li \&It
列表項
.It Li \&Li
原文
.It Li \&Sy
Symbolic text
.It Li \&%B
書題
.It Li \&%J
期刊名
.It Li \&%O
參考選注
.It Li \&%R
報告題目(在參考文件中)
.It Li \&%T
在書籍或期刊中的題目
.El
.Pp
一種 傳遞 含空格符字符串 的 方法 是 用
.Ql \e\  
硬編碼 或 不可填充空格符, 也就是 在 空格符 前 加上 轉義符
.Ql \e .
這個 方法 適用於 任何宏, 但 有個 副效應, 它 干擾了 對 長行 的 調整.
.Xr Troff
把 這種 硬編碼的 空格符 看作 可顯示字符, 因此 無法 在需要的時候 把 字符串
分段 或 換行. 這種 方法 適用於 字符串 不會 到達 行邊界 時, 例如:
.Bl -tag -width "fetch(char *str)" -offset indent
.It Fn fetch char\ *str
來自
.Ql \&.Fn fetch char\e *str
.It Fn fetch "char *str"
也可以來自
.Ql \&.Fn fetch "\\*qchar *str\\*q"
.El
.Pp
如果 忽略
.Ql \e
或 引號,
.Ql \&.Fn
宏 會認爲 有 三個參數, 結果 成爲:
.Pp
.Dl Fn fetch char *str
.Pp
如果 想知道 參數列表 到達 行邊界 時 出現什麼, 參看
.Sx BUGS
小節.
.Ss 尾部的空白符 Trailing Blank Space Characters
.Xr Troff
可能 被 行尾的 空白符 搞亂, 它的防範規則 是 消除 所有 位於行末 的 空白符. 
如果 堅持 在 行末 加上 空白符, 可以 用 硬空格符 和
.Ql \e&
轉義字符. 例如,
.Ql string\e\ \e& .
.Ss 轉義特殊字符 Escaping Special Characters
特殊字符, 如 換行符
.Ql \en ,
是 通過 用
.Ql \ee
替換
.Ql \e
(e.g.例如
.Ql \een )
保留住 反斜槓.
.Sh "手冊頁結構分析 THE ANATOMY OF A MAN PAGE"
手冊頁 可以 很容易的 通過 模板 構建, 模板 放在
.Pa /usr/share/misc/mdoc.template . 
另外 在
.Pa /usr/share/examples/mdoc
目錄下 有一些 手冊頁 的 例子.
.Pp
.Ss 手冊頁的模板 A manual page template
.Bd -literal -offset indent
\&.\e" 所有的手冊頁都要求有下面的內容
\&.Dd 月 日, 年Month day, year
\&.Os 操作系統 [版本/發行號] 
\&.Dt 文檔標題 [手冊節號][卷] 
\&.Sh 名稱 NAME
\&.Nm 名稱 name
\&.Nd 對名稱的簡單描述 one line description of name
\&.Sh 總覽 SYNOPSIS
\&.Sh 描述 DESCRIPTION
\&.\e" 後面的內容取消註釋後可以用在你需要的任何地方.
\&.\e" 緊接着的這條命令用於手冊第二和第三部分, 函數的返回值.
\&.\e" .Sh 返回值 RETURN VALUES
\&.\e" 下面的命令用於手冊第1, 6, 7, 8部分.
\&.\e" .Sh 環境 ENVIRONMENT
\&.\e" .Sh 文件 FILES
\&.\e" .Sh 示例 EXAMPLES
\&.\e" 下面的命令用於手冊第1, 6, 7, 8部分
\&.\e"     (在shell下的命令返回值和標準錯誤類型的診斷)
\&.\e" .Sh 診斷 DIAGNOSTICS
\&.\e" 下面的命令用於手冊第二和第三部分中的錯誤和信號處理.
\&.\e" .Sh 錯誤 ERRORS
\&.\e" .Sh 另見 SEE ALSO
\&.\e" .Sh 遵循 CONFORMING TO
\&.\e" .Sh 歷史 HISTORY
\&.\e" .Sh 作者 AUTHORS
\&.\e" .Sh BUGS
.Ed
.Pp
模板中 的 第一個部分 是
.Pq Li \&.Dd , \&.Os , \&.Dt 
宏; 文檔日期, 手冊或其內容 針對的 操作系統, 手冊頁的標題
.Pq Em (大寫)
和 該手冊頁 所屬的節 (部分號).
這些宏 確認和標識了 這個手冊頁. 在 後面的
.Sx 標題宏 TITLE MACROS
將 繼續 討論.
.Pp
這個 模板中 的 其餘部分 是 小節首部 (section header)
.Pq Li \&.Sh ;
其中
.Sx 名稱 NAME ,
.Sx 總覽 SYNOPSIS
和
.Sx 描述 DESCRIPTION
是 必不可少的.
這些 首部 在
.Sx 頁結構宏域
中 討論 ( 介紹完
.Sx 手冊域
之後 ) .
有一些 內容宏 被用來 示範 頁面佈局宏; 建議 接觸 頁面佈局宏 前 先看看 內容宏.
.Sh 標題宏 TITLE MACROS
標題宏 是 頁結構宏域 的 第一部分, 但 在 過去, 人們 如果 編寫 手冊頁, 
它 是 手冊的 第一部分, 也是 獨立部分. 這裏 設計了 三個宏 分別 描述
文檔標題 或 手冊標題, 操作系統, 和 製作日期. 它們 放在 文檔的 最前面, 
一次 只 調用 一個, 用來 構建 文檔的 頁頭 和 頁腳.
.Bl -tag -width 6n
.It Li \&.Dt 文檔標題 手冊區# [卷]
文檔標題 是 手冊頁的 主題, 由於 troff 的 限制, 必須
.Tn 大寫 .
手冊節號 (部分號) 介於 1,\ ...,\ 8, 如果 指明瞭 手冊節號, 可以 忽略 卷標.
卷標 用 下列 標識的 一個 或 任意個:
.\" .Cl
.\" USD	UNIX 用戶增補文檔 User's Supplementary Documents
.\" .Cl
.\" PS1	UNIX 程序員增補文檔 Programmer's Supplementary Documents
.Pp
.Bl -column SMM -offset indent -compact
.It Li AMD	UNIX 歷史遺留的手冊文檔 Ancestral Manual Documents
.It Li SMM	UNIX 系統管理員手冊 System Manager's Manual
.It Li URM	UNIX 參考手冊 Reference Manual
.It Li PRM	UNIX 程序員手冊 Programmer's Manual
.El
.Pp
缺省的卷標
.Li URM
代表 手冊區 1, 6, and 7;
.Li SMM
代表 手冊區 8;
.Li PRM
代表 手冊區 2, 3, 4, and 5.
.\" .Cl
.\" MMI	UNIX Manual Master Index
.\" .Cl
.\" CON	UNIX Contributed Software Manual
.\" .Cl
.\" LOC	UNIX Local Manual
.It Li \&.Os 操作系統 發行號#
操作系統 的 名字 可能 是 縮寫, 像
.Tn BSD
或
.Tn FreeBSD
或
.Tn ATT .
發行號 應該 是 系統 專用的 標準發行術語, 像 4.3, 4.3+Tahoe, V.3, V.4.
識別不出的 參數 就 照原樣 顯示在 頁腳. 例如, 典型的頁腳 可能是:
.Pp
.Dl \&.Os BSD 4.3
.Pp
或
.Dl \&.Os FreeBSD 2.2
.Pp
或者 象 訂製的產品
.Pp
.Dl \&.Os CS Department
.Pp
作爲 伯克利的缺省設置, 不帶 參數 的
.Ql \&.Os
定義爲
.Tn BSD 
(指定在文件
.Pa /usr/share/tmac/mdoc/doc-common 
中). 你 應該 把缺省值 設成
.Tn 本機.
注意, 如果 不設置
.Ql \&.Os
宏, 頁面的左下角 會 很難看.
.It Li \&.Dd 月 日, 年 (month day, year)
日期 應當 寫的 正規點:
.Pp
.ne 5
.Dl January 25, 1989
.El
.Sh 手冊宏域 和 基本正文宏域的介紹
.Ss 名稱背後 What's in a name...
手冊宏域 的 宏名 來自 非正式的 日常用語, 用來 描述 命令, 子程序 及其 
相關文件. 在 寫 手冊頁 時, 文字用語 有些 輕微的變化, 分別描述 三個 
不同 應用面. 首先是
.Nm \-mdoc
宏請求 的 用法. 其次, 用
.Nm \-mdoc
宏 描述
.Ux
命令. 最後, 對 用戶 具體的描述 這條命令; 也就是 在 手冊頁 正文 裏 
討論這條命令.
.Pp
第一種 情況 下,
.Xr troff 1
宏 本身 就是 一種 命令; troff 命令 的 基本語法 是:
.Bd -filled -offset indent
\&.Va argument1 argument2 ... argument9
.Ed
.Pp
這裏的
.Ql \&.Va
是 宏命令 或 宏請求, 緊隨其後 的 是 待處理的參數.
第二種 情況 下, 使用 內容宏 描述 一條
.Ux
命令 要 複雜 些; 一個 典型的
.Sx 總覽 SYNOPSIS
命令行 顯示 如下:
.Bd -filled -offset indent
.Nm filter
.Op Fl flag
.Ar infile outfile
.Ed
.Pp
這裏的
.Nm filter
是 命令名稱, 方括弧內 的
.Fl flag
是一個
.Em 標誌
參數, 作爲 可選參數 放在 代表 選項 的 方括弧內. 在
.Nm \-mdoc
術語 中,
.Ar infile
和
.Ar outfile
稱爲
.Em 參數 .
產生 上述效果 的 宏 是 這樣的:
.Bd -literal -offset indent
\&.Nm filter
\&.Op \&Fl flag
\&.Ar infile outfile
.Ed
.Pp
第三種 情況 討論 命令 及其語法, 包括 它們的例子, 可能 還有 更多細節.
上面的例子裏, 可以把
.Ar infile
和
.Ar outfile
理解爲
.Em 操作參數 operands
或
.Em 文件參數 file arguments .
有些 命令行參數 羅列的 十分 長:
.Bl -tag -width make -offset indent
.It Nm make
.Op Fl eiknqrstv
.Op Fl D Ar variable
.Op Fl d Ar flags
.Op Fl f Ar makefile
.Bk -words
.Op Fl I Ar directory
.Ek
.Op Fl j Ar max_jobs
.Op Ar variable=value
.Bk -words
.Op Ar target ...
.Ek
.El
.Pp
這裏 你 可能 討論
.Nm make
命令 和 它的參數
.Ar makefile ,
作爲 一個 標誌的參數,
.Fl f ,
或者 討論 一個 可選的文件操作對象
.Ar target .
在 具體的上下文 中, 這種細節 能夠 防止 混淆. 然而
.Nm \-mdoc
宏包中 沒有爲 標誌的參數 準備 宏. 作爲 替代 是
.Ql \&Ar
參數宏, 用於 描述 操作對象 或 文件參數 如
.Ar target
以及 標誌的參數 如
.Ar variable .
上面的 make 命令行 是 這樣 產生的:
.Bd -literal -offset indent
\&.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
.Ed
.Pp
在 
.Sx Keeps 
小節中 將會 解釋
.Ql \&.Bk
和
.Ql \&.Ek
宏.
.Ss 基本語法 General Syntax
手冊宏域 和 基本正文宏域 的 宏 有着 相似的語法, 僅有 微小差別:
.Ql \&.Ar ,
.Ql \&.Fl ,
.Ql \&.Nm ,
和
.Ql \&.Pa
僅當 無參數調用時 纔有 區別;
.Ql \&.Fn
和
.Ql \&.Xr
的 參數列表 要求 一定的 順序;
.Ql \&.Op
和
.Ql \&.Fn
宏有嵌套限制. 所有的 內容宏 能夠 識別和正確處理 標點符號, 每個 標點符號 
要在 前面 用 空格 隔開. 如果 給出 這樣的 宏請求:
.Pp
.Dl \&.Li sptr, ptr),
.Pp
結果是:
.Pp
.Dl Li sptr, ptr),
.Pp
標點符號 沒有 被識別 出來, 全都按 原文字體 輸出. 如果 標點符號 前面用
空格符 隔開:
.Pp
.Dl \&.Li "sptr , ptr ) ,"
.Pp
結果是:
.Pp
.Dl Li sptr , ptr ) ,
.Pp
標點符號 被 識別出來 了, 缺省的字體 也 有別於 原文文字的字體.
.Pp
用
.Ql \e& .
轉義符 可以 去掉 標點字符 的 特殊意義.
.Xr Troff
作爲 宏語言 有一定 的 限制, 當 表達的字串 中 含有
數學, 邏輯 或 引用 符號時 將 難於 處理:
.Bd -literal -offset indent-two
\&{+,\-,/,*,\&%,<,>,<=,>=,=,==,&,`,',"}
.Ed
.Pp
問題是
.Xr troff
會 認爲 它 應該 執行或運算 這些 符號 代表的操作.
要 防止 這一點 可以 用
.Ql \e&
轉義 這些 字符. 典型語法 在 下面 顯示的 第一個 內容宏 中 可以見到,
.Ql \&.Ad .
.Sh 手冊域 MANUAL DOMAIN
.Ss 地址宏 Address Macro
地址宏 用 這種 格式 標明地址: addr1[,addr2[,addr3]].
.Pp
.Dl Usage: .Ad address ... 
.Bl -tag -width ".Ad f1 , f2 , f3 :" -compact -offset 14n
.It Li \&.Ad addr1
.Ad addr1
.It Li \&.Ad addr1\ .
.Ad addr1 .
.It Li \&.Ad addr1\ , file2
.Ad addr1 , file2
.It Li \&.Ad f1\ , f2\ , f3\ :
.Ad f1 , f2 , f3 :
.It Li \&.Ad addr\ )\ )\ ,
.Ad addr ) ) ,
.El
.Pp
不帶參數 調用
.Ql \&.Ad
是個 錯誤.
.Ql \&.Ad
可以被 (其他宏) 調用和分析.
.Ss 作者名稱 Author Name
The
.Ql \&.An
宏用以 說明 這個文檔的 描述對象的 作者, 或者 這篇手冊頁的 作者.
名字 信息 後面的 其他參數 被認爲是 標點符號.
.Pp
.Dl Usage: .An author_name ... 
.Bl -tag -width ".An Joe Author ) ) ," -compact -offset 14n
.It Li \&.An Joe\ Author
.An Joe Author
.It Li \&.An Joe\ Author\ ,
.An Joe\ Author ,
.It Li \&.An Joe\ Author\ \&Aq\ nobody@FreeBSD.ORG
.An Joe Author Aq nobody@FreeBSD.ORG
.It Li \&.An Joe\ Author\ )\ )\ ,
.An Joe Author ) ) ,
.El
.Pp
.Ql \&.An
宏可以被 (其他宏) 分析和調用, 
不帶參數調用
.Ql \&.An
是個錯誤.
.Ss 參數宏 Argument Macro
當 引用 命令行參數時 可以使用
.Ql \&.Ar
參數宏.
.Pp
.Dl Usage: .Ar argument ... 
.Bl -tag -width ".Ar file1 file2" -compact -offset 15n
.It Li \&.Ar
.Ar
.It Li \&.Ar file1
.Ar file1
.It Li \&.Ar file1\ .
.Ar file1 .
.It Li \&.Ar file1 file2
.Ar file1 file2
.It Li \&.Ar f1 f2 f3\ :
.Ar f1 f2 f3 :
.It Li \&.Ar file\ )\ )\ ,
.Ar file ) ) ,
.El
.Pp
如果不帶參數調用
.Ql \&.Ar
宏, 缺省爲
.Ql Ar .
.Ql \&.Ar
宏可以被 (其他宏) 分析和調用.
.Ss 配置定義 (手冊第四部分) Configuration Declaration
.Ql \&.Cd
宏用於描述
.Xr config 8
對 設備接口的定義 (手冊第四部分).
這個宏 接受 引號內的參數 (只能是雙引號).
.Pp
.Bl -tag -width "device le0 at scode?" -offset indent
.It Cd "device le0 at scode?"
來自:
.Ql ".Cd device le0 at scode?" .
.El
.Ss 命令修飾 Command Modifier
命令修飾宏和
.Ql \&.Fl
(標誌) 命令相似, 除了
.Ql \&.Cm
宏 不在 任何參數 前 加 短橫線 (dash).
傳統的標誌 以 短橫線 開頭, 但 一些 命令 或 命令的子集 不用這個.
命令修飾宏 也可以 和 交互命令 結合 使用, 如 編輯命令. 另見
.Sx Flags .
.Ss 已定義的變量 Defined Variables
在 頭文件 中 已經 定義了的變量 用
.Ql \&.Dv 
宏說明.
.Pp
.Dl Usage: .Dv defined_variable ... 
.Bl -tag -width ".Dv MAXHOSTNAMELEN" -compact -offset 14n
.It Li ".Dv MAXHOSTNAMELEN"
.Dv MAXHOSTNAMELEN
.It Li ".Dv TIOCGPGRP )"
.Dv TIOCGPGRP )
.El
.Pp
不帶參數調用
.Ql \&.Dv
是個錯誤.
.Ql \&.Dv
宏可以被 (其他宏) 分析和調用.
.Ss Errno's (僅供手冊第二部分)
這個
.Ql \&.Er
errno 宏 指明 手冊 第二部分, 庫函數 的 錯誤返回值.(譯註: 應該是系統調用)
下面的 第二個 例子 顯示了
.Ql \&.Er
配合
.Ql \&.Bq
基本正文宏 的 使用, 就象 用在 手冊 第二部分 一樣.
.Pp
.Dl Usage: .Er ERRNOTYPE ... 
.Bl -tag -width ".Bq Er ENOTDIR" -compact -offset 14n
.It Li \&.Er ENOENT
.Er ENOENT
.It Li \&.Er ENOENT\ )\ ;
.Er ENOENT ) ;
.It Li \&.Bq \&Er ENOTDIR
.Bq Er ENOTDIR
.El
.Pp
不帶參數調用
.Ql \&.Er
宏是個錯誤.
.Ql \&.Er
宏可以被 (其他宏) 分析和調用.
.Ss 環境變量 Environment Variables
.Ql \&.Ev
宏說明一個環境變量.
.Pp
.Dl Usage: .Ev argument ... 
.Bl -tag -width ".Ev PRINTER ) ) ," -compact -offset 14n
.It Li \&.Ev DISPLAY
.Ev  DISPLAY
.It Li \&.Ev PATH\ .
.Ev PATH .
.It Li \&.Ev PRINTER\ )\ )\ ,
.Ev PRINTER ) ) ,
.El
.Pp
不帶參數調用
.Ql \&.Ev
宏是個錯誤.
.Ql \&.Ev
宏可以被 (其他宏) 分析和調用.
.Ss 函數參數 Function Argument
.Ql \&.Fa
宏 用來 說明 在手冊的
.Sx 總覽 SYNOPSIS
小節 之外的 函數參數, 或者在
.Sx 總覽 SYNOPSIS
小節內, 其 參數列表對
.Ql \&.Fn
宏 而言 過長, 並且 必須 使用
.Ql \&.Fo
和
.Ql \&.Fc
宏時.
.Ql \&.Fa
也 有可能 用來 說明 結構成員.
.Pp
.Dl Usage: .Fa function_argument ... 
.Bl -tag -width ".Fa d_namlen\ )\ )\ ," -compact -offset 14n
.It Li \&.Fa d_namlen\ )\ )\ ,
.Fa d_namlen ) ) ,
.It Li \&.Fa iov_len
.Fa iov_len
.El
.Pp
不帶參數調用
.Ql \&.Fa
宏是個錯誤.
.Ql \&.Fa
宏可以被 (其他) 宏分析和調用.
.Ss 函數聲明 Function Declaration
.Ql \&.Fd
宏 用於 第二或 第三部分 手冊頁 的
.Sx 總覽 SYNOPSIS
小節.
.Ql \&.Fd
宏 既 不調用 其他宏, 也 不能 被 其他宏調用.
.Pp
.Dl Usage: .Fd include_file (or defined variable)
.Pp
在
.Sx 總覽 SYNOPSIS
小節, 如果 已經 說明了 某個 函數, 並且 沒有 出現 省略號, 則
.Ql \&.Fd
宏請求 能夠 產生 一個 斷行.
在 函數 和 函數聲明 之間, 垂直方向上 產生 一定的 空白.
.Ss 標誌 Flags
.Ql \&.Fl
宏 處理 命令行標誌. 它 在 標誌前 加一個 短橫線
.Ql \- ,
對於 交互命令 標誌, 它 不需要 短橫線, 可以用
.Ql \&.Cm
(命令修飾 command modifier)
宏替換, 它 沒有 短橫線.
.Pp
.Dl Usage: .Fl argument ... 
.Bl -tag -width ".Fl \-s \-t \-v" -compact -offset 14n
.It Li \&.Fl
.Fl
.It Li \&.Fl cfv
.Fl cfv
.It Li \&.Fl cfv\ .
.Fl cfv .
.It Li \&.Fl s v t
.Fl s v t
.It Li \&.Fl -\ ,
.Fl - ,
.It Li \&.Fl xyz\ )\ ,
.Fl xyz ) ,
.El
.Pp
如果
.Ql \&.Fl
宏 不帶 任何 參數, 將 只產生 一個 短橫線, 代表 stdin/stdout.
注意 如果 把 一個 短橫線 做爲
.Ql \&.Fl
的參數, 結果 會 得到 兩個短橫線.
.Ql \&.Fl
宏可以被 (其他宏) 分析和調用.
.Ss 函數(庫函數) Functions (library routines)
宏 .Fn 是 ANSI C 函數風格 的 模型.
.Bd -literal
Usage: .Fn [type] function [[type] parameters ... 
.Ed
.Bl -tag -width ".Fn int align. .const * char *sptrsxx" -compact
.It Li "\&.Fn getchar"
.Fn getchar
.It Li "\&.Fn strlen ) ,"
.Fn strlen ) ,
.It Li \&.Fn "\\*qint align\\*q" "\\*qconst * char *sptrs\\*q" ,
.Fn "int align" "const * char *sptrs" ,
.El
.Pp
不帶參數調用
.Ql \&.Fn
是一個錯誤.
.Ql \&.Fn
宏可以被 (其他宏) 分析和調用,
注意 任何 對 其他宏 的 調用 應該在
.Ql \&.Fn
宏調用 的 結尾處 給出 標記 (反括弧).
.Pp
對於 八個 參數 以上的 函數 (儘管少見), 可以 用 宏
.Ql \&.Fo
(function open) 和
.Ql \&.Fc
(function close) 配合
.Ql \&.Fa
(function argument) 宏 的 使用, 突破 參數 過多 的 限制, 例如:
.Bd -literal -offset indent
\&.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
.Ed
.Pp
產生:
.Bd -filled -offset indent
.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
.Ed
.Pp
宏
.Ql \&.Fo
和
.Ql \&.Fc
可以被 (其他宏) 分析和調用. 在
.Sx 總覽 SYNOPSIS
小節, 函數 總是 位於 行的開始 處.
如果 在
.Sx 總覽 SYNOPSIS
小節 有 一個以上的 函數聲明, 而且 函數類型 沒有 說明, 則 會產生 一個 斷行.
在 函數 和 函數 的 垂直方向 上 產生 一定的 空白. 此時
.Ql \&.Fn
宏 不按 troff 的 行長 檢查 單詞 邊界, 有可能 難看的 從 單詞中間 斷開.
以後 會 解決 這個 問題.
.Ss 函數類型 Function Type
這個宏 設計 用在
.Sx 總覽 SYNOPSIS
小節. 它 可以 毫無困難的 用在 手冊頁的 其他 地方, 但 它的 主要 目的
是 爲 第二 和 第三部分 手冊頁的
.Sx 總覽 SYNOPSIS
小節, 以 核心標準形式 (kernel normal form) 描述 函數類型
(它 導致 斷行, 在 下一行 顯示 函數 名稱).
.Pp
.Dl Usage: .Ft type ... 
.Bl -tag -width "\&.Ft struct stat" -offset 14n -compact
.It Li \&.Ft struct stat
.Ft struct stat
.El
.Pp
.Ql \&.Ft
宏不能被其他宏調用.
.Ss 交互命令 Interactive Commands
宏
.Ql \&.Ic
用於 說明 交互 或 內部命令.
.Pp
.Dl Usage: .Ic argument ... 
.Bl -tag -width ".Ic setenv , unsetenvxx" -compact -offset 14n
.It Li \&.Ic :wq
.Ic :wq
.It Li \&.Ic do while {...}
.Ic do while {...}
.It Li \&.Ic setenv\ , unsetenv
.Ic setenv , unsetenv
.El
.Pp
不帶參數調用
.Ql \&.Ic
是個錯誤.
.Ql \&.Ic
宏可以被 (其他宏) 分析和調用.
.Ss 名稱宏 Name Macro
.Ql \&.Nm
宏 用於 說明 文檔題目 或 主題. 它的特點 是 能夠 記住 調用時 帶的 第一個 
參數, 這個 參數 就是 該頁的 主題. 當 不帶 參數 調用它 時,
.Ql \&.Nm
宏 把 以前 記住的 參數 顯示 出來, 可以 爲作者 省點勁.
注意: 手冊第二部分或第三部分的函數名稱, 在
.Sx 名稱 NAME
小節 用
.Ql \&.Nm
說明, 在
.Sx 總覽 SYNOPSIS
和 其餘 小節 用
.Ql \&.Fn
說明. 對於 交互命令, 例如 在
.Xr csh 1
中的
.Ql while
命令, 應該 使用
.Ql \&.Ic
宏.
.Ql \&.Ic
宏和
.Ql \&.Nm ,
宏 非常接近, 只是 它 不能夠 記憶 調用時的 參數.
.Pp
.Dl Usage: .Nm argument ... 
.Bl -tag -width ".Nm mdoc.sample" -compact -offset 14n
.It Li \&.Nm mdoc.sample
.Nm  mdoc.sample
.It Li \&.Nm \e-mdoc
.Nm \-mdoc .
.It Li \&.Nm foo\ )\ )\ ,
.Nm foo ) ) ,
.It Li \&.Nm
.Nm
.El
.Pp
.Ql \&.Nm
宏可以被 (其他宏) 分析和調用.
.Ss 選項 Options
.Ql \&.Op
宏 把 命令行上 剩餘的 所有 參數 用 方括弧 括在一起, 把 最後的 標點符號
放到 方括弧 外面. 宏
.Ql \&.Oc
和
.Ql \&.Oo
用於 處理 跨行.
.Pp
.Dl Usage: .Op options ... 
.Bl -tag -width ".Op Fl c Ar objfil Op Ar corfil ," -compact -offset indent
.It Li \&.Op
.Op
.It Li ".Op Fl k"
.Op Fl k
.It Li ".Op Fl k ) ."
.Op Fl k ) .
.It Li ".Op Fl k Ar kookfile"
.Op Fl k Ar kookfile
.It Li ".Op Fl k Ar kookfile ,"
.Op Fl k Ar kookfile ,
.It Li ".Op Ar objfil Op Ar corfil"
.Op Ar objfil Op Ar corfil
.It Li ".Op Fl c Ar objfil Op Ar corfil ,"
.Op Fl c Ar objfil Op Ar corfil ,
.It Li \&.Op word1 word2
.Op word1 word2
.El
.Pp
應用
.Ql \&.Oc
和
.Ql \&.Oo
宏:
.Bd -literal -offset indent
\&.Oo
\&.Op \&Fl k \&Ar kilobytes
\&.Op \&Fl i \&Ar interval
\&.Op \&Fl c \&Ar count
\&.Oc
.Ed
.Pp
產生:
.Oo
.Op Fl k Ar kilobytes
.Op Fl i Ar interval
.Op Fl c Ar count
.Oc
.Pp
宏
.Ql \&.Op ,
.Ql \&.Oc
和
.Ql \&.Oo
可以被 (其他宏) 分析和調用.
.Ss 路徑名 Pathnames
.Ql \&.Pa
宏 用於 格式化 路徑 或 文件名.
.Pp
.Dl Usage: .Pa pathname 
.Bl -tag -width ".Pa /tmp/fooXXXXX ) ." -compact -offset 14n
.It Li \&.Pa /usr/share
.Pa /usr/share
.It Li \&.Pa /tmp/fooXXXXX\ )\ .
.Pa /tmp/fooXXXXX ) .
.El
.Pp
.Ql \&.Pa
宏可以被 (其他宏) 分析和調用.
.Ss 變量 Variables
基本的 變量 參考:
.Pp
.Dl Usage: .Va variable ... 
.Bl -tag -width ".Va char s ] ) ) ," -compact -offset 14n
.It Li \&.Va count
.Va count
.It Li \&.Va settimer ,
.Va settimer ,
.It Li \&.Va int\ *prt\ )\ :
.Va int\ *prt ) :
.It Li \&.Va char\ s\ ]\ )\ )\ ,
.Va char\ s ] ) ) ,
.El
.Pp
不帶參數調用
.Ql \&.Va
宏是個錯誤.
.Ql \&.Va
宏可以被 (其他宏) 分析和調用.
.Ss 手冊頁參照 Manual Page Cross References
.Ql \&.Xr
宏 把 第一個參數 當做 手冊頁 名稱, 第二個參數, 如果 存在,
當做 標點符號 或 手冊頁 的 部分號 (節號). 剩下 所有的參數
視做 標點符號.
.Pp
.Dl Usage: .Xr man_page [1,...,8] 
.Bl -tag -width ".Xr mdoc 7 ) ) ," -compact -offset 14n
.It Li \&.Xr mdoc
.Xr mdoc
.It Li \&.Xr mdoc\ ,
.Xr mdoc ,
.It Li \&.Xr mdoc 7
.Xr mdoc 7
.It Li \&.Xr mdoc 7\ )\ )\ ,
.Xr mdoc 7 ) ) ,
.El
.Pp
.Ql \&.Xr
宏可以被 (其他宏) 分析和調用.
不帶參數調用
.Ql \&.Xr
宏是個錯誤.
.Sh 基本正文宏域 GENERAL TEXT DOMAIN
.Ss AT&T 宏
.Bd -literal -offset indent -compact
Usage: .At [v6 | v7 | 32v | V.1 | V.4] ... 
.Ed
.Bl -tag -width ".At v6 ) ," -compact -offset 14n
.It Li ".At"
.At
.It Li ".At v6 ."
.At v6 .
.El
.Pp
.Ql \&.At
宏
.Em 不能
被 (其他宏) 分析, 也
.Em 不能
被 (其他宏) 調用. 該宏 最多 接受 兩個 參數.
.Ss BSD 宏
.Dl Usage: .Bx [Version/release] ... 
.Bl -tag -width ".Bx 4.3 ) ," -compact -offset 14n
.It Li ".Bx"
.Bx
.It Li ".Bx 4.3 ."
.Bx 4.3 .
.El
.Pp
.Ql \&.Bx
宏可以被 (其他宏) 分析和調用.
.Ss FreeBSD 宏
.Bd -literal -offset indent -compact
Usage: .Fx Version.release ... 
.Ed
.Bl -tag -width ".Fx 2.2 ) ," -compact -offset 14n
.It Li ".Fx 2.2 ."
.Fx 2.2 .
.El
.Pp
.Ql \&.Fx
宏
.Em 不能
被 (其他宏) 分析, 也
.Em 不能
被 (其他宏) 調用. 該宏 最多 接受 兩個 參數.
.Ss UNIX 宏
.Dl Usage: .Ux ... 
.Bl -tag -width ".Ux 4.3 ) ," -compact -offset 14n
.It Li ".Ux"
.Ux
.El
.Pp
.Ql \&.Ux
宏可以被 (其他宏) 分析和調用.
.Ss 嵌入和引用宏 Enclosure and Quoting Macros
嵌入 的 概念 和 引用 類似. 把 一句 或 多句 引用對象 嵌到 一對 字符 中, 
象 引號 或 括弧. 本篇 文檔中 將 混用 術語
.Ql 嵌入
和
.Ql 引用.
大多數 單行的 引用宏名 用 一個 小寫字母
.Ql q
結尾, 表明 這是 一個 引用(quoting), 但 也有 不規則變化.
每個 引用宏 都有 一對 開始(open) 和 結束(close) 宏, 各自 以
.Ql o
和
.Ql c
結尾. 在 某些限制時 這些宏 可以 跨行 使用, 單行的引用宏 可以 嵌套在裏面.
.Pp
.ne 5
.Bd -filled -offset indent
.Bl -column "quote " "close " "open " "Enclose Stringx(in XX) " XXstringXX
.Em " Quote	 Close	 Open	Function	Result"
\&.Aq	.Ac	.Ao	Angle Bracket Enclosure	<string>
\&.Bq	.Bc	.Bo	Bracket Enclosure	[string]
\&.Dq	.Dc	.Do	Double Quote	``string''
	.Ec	.Eo	Enclose String (in XX)	XXstringXX
\&.Pq	.Pc	.Po	Parenthesis Enclosure	(string)
\&.Ql			Quoted Literal	`st' or string
\&.Qq	.Qc	.Qo	Straight Double Quote	"string"
\&.Sq	.Sc	.So	Single Quote	`string'
.El
.Ed
.Pp
除了 下面的 不規則宏, 所有的 引用宏 可以被 (其他宏) 分析和調用. 所有的 
引用宏 能夠 正確 處理 標點符號, 只要 一次 一個字符, 中間 用 空格 隔開.
引用宏 檢查 開始和結束 符號, 以決定 把 它 放在 引用串的 前面還是後面.
這樣 就 有了 一定的 嵌套能力.
.Bl -tag -width xxx,xxxx
.It Li \&.Ec , \&.Eo
這些宏 的 第一個參數 是 各自的 開始和結束串.
.It Li \&.Ql
原文引用宏 的 表現在
.Xr troff
中和
.Xr nroff 
不一樣. 如果用
.Xr nroff 
格式化, 引用的原文 始終 被引用. 如果用 troff 格式化,
只有 寬度 小於 三個定寬字符 的 項 才被 引用.
This is to make short strings more visible where the font change
to literal (constant width) is less noticeable.
當 字體 變成 原文(定寬) 時, 短串顯得更容易被看到.
.It Li \&.Pf
前綴宏不能被 (其他宏) 調用, 但是可以被分析.
.Bl -tag -width "(namexx" -offset indent
.It Li ".Pf ( Fa name2"
變成
.Pf ( Fa name2 .
.El
.Pp
這個
.Ql \&.Ns
(無空格) 宏 執行 類似的 後綴 功能.
.El
.Pp
.ne 4
引用舉例:
.Bl -tag -width ".Aq Pa ctype.h ) ,xxxxxxxx" -compact -offset indent
.It Li \&.Aq
.Aq
.It Li \&.Aq \&Ar ctype.h\ )\ ,
.Aq Ar ctype.h ) ,
.It Li \&.Bq
.Bq
.It Li \&.Bq \&Em Greek \&, French \&.
.Bq Em Greek , French .
.It Li \&.Dq
.Dq
.It Li ".Dq string abc ."
.Dq string abc .
.It Li ".Dq \'^[A-Z]\'"
.Dq \'^[A-Z]\'
.It Li "\&.Ql man mdoc"
.Ql man mdoc
.It Li \&.Qq
.Qq
.It Li "\&.Qq string ) ,"
.Qq string ) ,
.It Li "\&.Qq string Ns ),"
.Qq string Ns ),
.It Li \&.Sq
.Sq
.It Li "\&.Sq string
.Sq string
.El
.Pp
作爲 嵌套引用宏的 典型範例, 參見
.Ql \&.Op
選項宏. 它們 都 來自 上面 列出的 基本 引用宏.
.Ql \&.Xo
和
.Ql \&.Xc
擴展的 參數列表宏 同樣 來自 相同的 基本例程, 並且, 在 最壞的情況 下, 是
.Nm \-mdoc
宏 用法的 很好範例.
.Ss No\-Op 或正文宏 or Normal Text Macro
宏
.Ql \&.No
用在 某個 宏命令行 上, 意如其名, 將
.Em 不
被格式化, 語法 遵循 一般的 內容宏.
.Ss 無空格宏 No Space Macro
.Ql \&.Ns
在 宏請求 之間 消除 不需要的 空格.
它 用在 舊式風格的 參數列表 中, 標誌和參數 間 沒有 空格:
.Bl -tag -width ".Op Fl I Ns Ar directoryxx" -offset indent
.It Li ".Op Fl I Ns Ar directory"
產生
.Op Fl I Ns Ar directory
.El
.Pp
注意:
.Ql \&.Ns
宏 在 消除空格後 總會 調用
.Ql \&.No
宏, 除非 還有 其他 宏名 跟在 後面.
.Ql \&.Ns
宏可以被 (其他宏) 分析和調用.
.Ss 手冊頁對照參考 Section Cross References
.Ql \&.Sx
宏 指定了 到 同一個文檔內的 小節首部 的 對照參考.
該宏可以被 (其他宏) 分析和調用.
.Pp
.Bl -tag -width "Li \&.Sx FILES" -offset 14n
.It Li \&.Sx FILES
.Sx FILES
.El
.Ss 參考和引言 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.
下面的宏 試圖 適度的 處理 參考資料. 最好情況時, 這些宏 便於 手工
插入 一段 相關風格的 參考資料.
.Pp
.Bl -tag -width 6n -offset indent -compact
.It Li ".Rs"
參考開始. 它 導致 一次 斷行, 並且 開始 收集 參考資料, 直到 遇到 參考結束宏.
.It Li ".Re"
參考結束. 則 打印出 參考信息.
.It Li ".%A"
參考資料 的 作者名字, 一次一個.
.It Li ".%B"
書名.
.It Li ".\&%C"
城市/地點.
.It Li ".\&%D"
日期.
.It Li ".%J"
期刊名.
.It Li ".%N"
發行號.
.It Li ".%O"
可選信息.
.It Li ".%P"
頁碼.
.It Li ".%R"
報告名.
.It Li ".%T"
文章題目.
.It Li ".%V"
卷.
.El
.Pp
用
.Ql %
符號 開始的 宏 不能被 (其他宏) 調用, 只能 被 trade name macro 分析,
結果 返回給 調用者 (此時 結果 不太好 預測). 其目的 是 允許 trade name 
能夠 很好的 打印在
.Xr troff Ns / Ns Xr ditroff
的 輸出端.
.Ss 返回值 Return Values
.Ql \&.Rv
宏 產生 一些 用在
.Sx 返回值 RETURN VALUES
小節的 文字.
.Pp
.Dl Usage: .Rv [-std function]
.Pp
.Ql \&.Rv -std atexit
將輸出 下列文字:
.Pp
.Dl .Rv -std atexit
.Pp
這個
.Fl std
選項 僅用於 手冊頁的 第二和第三部分.
.Ss Trade Names (或縮略和類型名)
trade name 宏 一般說來 是 一個 很小的 大寫字母宏, 用於 所有 大於
兩個字符的 大寫單詞.
.Pp
.Dl Usage: .Tn symbol ... 
.Bl -tag -width ".Tn ASCII" -compact -offset 14n
.It Li \&.Tn DEC
.Tn DEC
.It Li \&.Tn ASCII
.Tn ASCII
.El
.Pp
.Ql \&.Tn
宏可以被 (其他宏) 分析和調用.
.Ss 擴展參數 Extended  Arguments
.Ql \&.Xo
和
.Ql \&.Xc
宏 可以 在 宏的邊界 擴展 參數列表. 如果 某個宏 要求 所有的參數 在 一行上 
出現, 則 參數列表 不能 在 這兒 被 擴展. 例如
.Ql \&.Op .
.Pp
這裏有
.Ql \&.Xo
宏的一個示例, 用 空格模式宏 把 空格 去掉:
.Bd -literal -offset indent
\&.Sm off
\&.It Xo Sy I Ar operation
\&.No \een Ar count No \een
\&.Xc
\&.Sm on
.Ed
.Pp
產生
.Bd -filled -offset indent
.Bl -tag -width flag -compact
.Sm off
.It Xo Sy I Ar operation
.No \en Ar count No \en
.Xc
.Sm on
.El
.Ed
.Pp
還有一個:
.Bd -literal -offset indent
\&.Sm off
\&.It Cm S No \&/ Ar old_pattern Xo
\&.No \&/ Ar new_pattern
\&.No \&/ Op Cm g
\&.Xc
\&.Sm on
.Ed
.Pp
產生
.Bd -filled -offset indent
.Bl -tag -width flag -compact
.Sm off
.It Cm S No \&/ Ar old_pattern Xo
.No \&/ Ar new_pattern
.No \&/ Op Cm g
.Xc
.Sm on
.El
.Ed
.Pp
另一個示例用
.Ql \&.Xo
和 引用宏:
測試一個變量的值.
.Bd -literal -offset indent
\&.It Xo
\&.Ic .ifndef
\&.Oo \e&! Oc Ns Ar variable
\&.Op Ar operator variable ...
\&.Xc
.Ed
.Pp
產生
.Bd -filled -offset indent
.Bl -tag -width flag -compact
.It Xo
.Ic .ifndef
.Oo \&! Oc Ns Ar variable
.Op Ar operator variable ...
.Xc
.El
.Ed
.Pp
上面 所有的例子 都在
.Ql \&.It
(list-item) 宏 的 參數列表 中 使用了
.Ql \&.Xo
宏. 擴展宏 不經常 使用, 一般用來 擴展 list-item 宏 的 參數列表.
這也 不幸的 是 擴展宏 最苛刻的 地方. 前兩個例子裏 空格 被去掉; 第三個 例子中, 
希望 能 輸出 部分 空格, 而不是 全部. 在 這種情況下 用 這些宏, 要 確保
.Ql \&.Xo
和
.Ql \&.Xc
宏 擺放到 第三個例子 中 示範的位置. 如果
.Ql \&.Xo
宏 沒有 單獨 出現在
.Ql \&.It
的 參數表 中, 則 無法預測 空格 情況. 這種情況下,
.Ql \&.Ns
(no space macro) 一定 不能 作爲 一行的 第一個宏 或 最後一個宏. 當前
.Bx
發佈的 超過 900個 手冊頁 (事實上大約1500個) 中,
只有 十五個 用到了
.Ql \&.Xo
宏.
.Sh 頁結構宏宏域 PAGE STRUCTURE DOMAIN
.Ss 小節首部 Section Headers
每個 手冊頁 裏 都用到了 下面 列出的 三個
.Ql \&.Sh
小節首部宏. 作者 寫 手冊頁 時 可以 酌情考慮 其他 建議使用的 小節首部.
.Ql \&.Sh
宏 最多 帶 九個 參數. 它 可以 被 (其他宏) 分析, 但不能 被調用.
.Bl -tag -width ".Sh SYNOPSIS"
.It \&.Sh 名稱 NAME
.Ql \&.Sh 名稱 NAME
宏是 必不可少的. 否則 無法設置 頁頭, 頁腳 和 缺省的 頁佈局, 樣子 會 很難看.
.Sx 名稱 NAME
小節 至少 由 三項 組成. 第一個 是
.Ql \&.Nm
名稱宏, 命名 手冊頁的 主題. 第二個 是 名稱描述宏
.Ql \&.Nd ,
它 把 主題名稱 和 第三項, 描述, 分離開來.
描述 應該 儘可能的 精簡易懂, 少佔空間.
.It \&.Sh 總覽 SYNOPSIS
.Sx SYNOPSIS
總覽小節 描述 該 手冊頁對象 的 典型用途.
請求的宏 是 下面 的 任意一個,
.Ql ".Nm" ,
.Ql ".Cd" ,
.Ql ".Fn" ,
(也可能是
.Ql ".Fo" ,
.Ql ".Fc" ,
.Ql ".Fd" ,
.Ql ".Ft"
宏). 函數名稱宏
.Ql ".Fn"
用在 手冊頁 的 第二第三部分, 命令 和 基本名稱宏
.Ql \&.Nm
用在 手冊頁 的 1, 5, 6, 7, 8 部分. 手冊 第四部分 需要
.Ql ".Nm" , 
.Ql ".Fd"
或
.Ql ".Cd"
配製設備用途宏. 其他一些 宏 可能 用來 產生 概要行, 象下面的:
.Pp
.Bd -filled -offset indent
.Nm cat
.Op Fl benstuv
.Op Fl
.Ar
.Ed
.Pp
下面 用到的 宏
.Pp
.Dl \&.Nm cat
.Dl \&.Op \&Fl benstuv
.Dl \&.Op \&Fl
.Dl \&.Ar
.Pp
.Sy 注意 :
宏
.Ql \&.Op ,
.Ql \&.Fl ,
和
.Ql \&.Ar
能夠 識別 管道符
.Ql \*(Ba ,
因此 命令行 如:
.Pp
.Dl ".Op Fl a | Fl b"
.Pp
的 表現 會 出軌.
.Xr Troff
一般把 \*(Ba 當做 特殊符號. 參見
.Sx 預定義串 PREDEFINED STRINGS ,
在 其他情況下 \*(Ba 的使用.
.It \&.Sh 描述 DESCRIPTION
大多數 情況下
.Sx 描述 DESCRIPTION
小節 的 第一段話 是 關於 這個 命令, 函數 或 文件 的 摘要, 後跟 字典式的
選項 以及 相應的解釋. 創建 這樣的 列表, 應該 使用
.Ql \&.Bl
列表開始,
.Ql \&.It
列表項和
.Ql \&.El
列表結束宏 (參見下面的
.Sx 列表和欄目 Lists and Columns
).
.El
.Pp
下面的
.Ql \&.Sh
小節首部 是 手冊頁 編排的 常見內容, 爲了 保證 連續性, 應 適當 使用.
它們 按照 應該 出現 的 順序 排列.
.Bl -tag -width SYNOPSIS
.It \&.Sh 環境 ENVIRONMENT
.Sx 環境 ENVIRONMENT
小節 用來 揭示 相關的 環境變量 和 線索, 它們的 行爲, 表現, 用法.
.It \&.Sh 示例 EXAMPLES
有 很多 辦法 創建 示例, 詳見 下面的
.Sx 示例 EXAMPLES
小節.
.It \&.Sh 文件 FILES
由 手冊頁的 主題對象 創建 或 使用 的 文件, 應該 通過
.Ql \&.Pa
宏在
.Sx 文件 FILES
小節 陳列 出來.
.It \&.Sh 另見 SEE ALSO
如果 提及 其他 手冊頁 或 參照 相應的 手冊, 應 把它們 放在
.Sx 另見 SEE ALSO
小節. 參照主題 由
.Ql \&.Xr
宏指定. 在
.Sx 另見 SEE ALSO
小節 的 參照主題 應該按 手冊節號 排序, 按 字母順序 陳列, 並用 逗號 隔開, 
例如:
.Pp
.Xr ls 1 ,
.Xr ps 1 ,
.Xr group 5 ,
.Xr passwd 5 .
.Pp
這時候 不太適合 用
.Xr refer 1
風格 的 參考引用.
.It \&.Sh 遵循 CONFORMING TO
如果 那些 命令, 庫函數 或 文件 遵循 一定的 標準 實現, 如
.St -p1003.2
或
.St -ansiC ,
那就 不需要 這一小節. 如果 命令 不符合 任何標準, 應該 把 它的歷史 放在
.Sx 歷史 HISTORY
小節.
.It \&.Sh 歷史 HISTORY
任何 不屬於 已知標準 的 命令 應該 在 這一節 給出 它的 大致歷史.
.It \&.Sh 作者 AUTHORS
如果 有 必要, 把 致謝名單 也 列這兒.
.It \&.Sh 診斷 DIAGNOSTICS
應該 把 診斷命令 放在 這一節.
.It \&.Sh 錯誤 ERRORS
特定的 錯誤處理, 尤其是 庫函數 (手冊頁第二第三部分), 放這兒.
.Ql \&.Er
宏 用來 指定 一個 errno.
.It \&.Sh BUGS
明顯的 問題 放這兒...
.El
.Pp
可以 增加一些 用戶 制定的
.Ql \&.Sh
小節, 例如, 這樣 設 小節:
.Bd -literal -offset 14n
\&.Sh PAGE STRUCTURE DOMAIN
.Ed
.Ss 段落和空行 Paragraphs and Line Spacing.
.Bl -tag -width 6n
.It \&.Pp
.Ql \&.Pp
把 段落命令 放在 所需的位置, 可以 產生 一個空行. 在
.Ql \&.Sh
或
.Ql \&.Ss
宏 後面 不需要 這個 宏, 
.Ql \&.Bl
宏 的 前面 也不需要. (
.Ql \&.Bl
聲明瞭 垂直方向 的 距離, 除非 給出 -compact 標誌).
.El
.\" This worked with version one, need to redo for version three
.\" .Pp
.\" .Ds I
.\" .Cw (ax+bx+c) \ is\ produced\ by\ \&
.\" .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\&
.\" .Cl Cx \t\t
.\" .Li \&.Cx\ (
.\" .Cx
.\" .Cl Cx \t\t
.\" .Li \&.Va ax
.\" .Cx
.\" .Cl Cx \t\t
.\" .Li \&.Sy \+
.\" .Cx
.\" .Cl Cx \&(\&
.\" .Va ax
.\" .Cx +
.\" .Va by
.\" .Cx +
.\" .Va c )
.\" .Cx \t
.\" .Em is produced by
.\" .Cx \t
.\" .Li \&.Va by
.\" .Cx
.\" .Cl Cx \t\t
.\" .Li \&.Sy \+
.\" .Cx
.\" .Cl Cx \t\t
.\" .Li \&.Va c )
.\" .Cx
.\" .Cl Cx \t\t
.\" .Li \&.Cx
.\" .Cx
.\" .Cw
.\" .De
.\" .Pp
.\" This example shows the same equation in a different format.
.\" The spaces
.\" around the
.\" .Li \&+
.\" signs were forced with
.\" .Li \e :
.\" .Pp
.\" .Ds I
.\" .Cw (ax\ +\ bx\ +\ c) \ is\ produced\ by\ \&
.\" .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\&
.\" .Cl Cx \t\t
.\" .Li \&.Cx\ (
.\" .Cx
.\" .Cl Cx \t\t
.\" .Li \&.Va a
.\" .Cx
.\" .Cl Cx \t\t
.\" .Li \&.Sy x
.\" .Cx
.\" .Cl Cx \t\t
.\" .Li \&.Cx \e\ +\e\ \e&
.\" .Cx
.\" .Cl Cx \&(\&
.\" .Va a
.\" .Sy x
.\" .Cx \ +\ \&
.\" .Va b
.\" .Sy y
.\" .Cx \ +\ \&
.\" .Va c )
.\" .Cx \t
.\" .Em is produced by
.\" .Cl Cx \t\t
.\" .Li \&.Va b
.\" .Cx
.\" .Cl Cx \t\t
.\" .Li \&.Sy y
.\" .Cx
.\" .Cl Cx \t\t
.\" .Li \&.Cx \e\ +\e\ \e&
.\" .Cx
.\" .Cl Cx \t\t
.\" .Li \&.Va c )
.\" .Cx
.\" .Cl Cx \t\t
.\" .Li \&.Cx
.\" .Cx
.\" .Cw
.\" .De
.\" .Pp
.\" The incantation below was
.\" lifted from the
.\" .Xr adb 1
.\" manual page:
.\" .Pp
.\" .Ds I
.\" .Cw \&[?/]m_b1_e1_f1[?/]\& is\ produced\ by
.\" .Cl Cx \t\t
.\" .Li \&.Cx Op Sy ?/
.\" .Cx
.\" .Cl Cx \t\t
.\" .Li \&.Nm m
.\" .Cx
.\" .Cl Cx Op Sy ?/
.\" .Nm m
.\" .Ad \ b1 e1 f1
.\" .Op Sy ?/
.\" .Cx \t
.\" .Em is produced by
.\" .Cx \t
.\" .Li \&.Ar \e\ b1 e1 f1
.\" .Cx
.\" .Cl Cx \t\t
.\" .Li \&.Op Sy ?/
.\" .Cx
.\" .Cl Cx \t\t
.\" .Li \&.Cx
.\" .Cx
.\" .Cw
.\" .De
.\" .Pp
.Ss 保持 Keeps
目前 只實現了 對單詞的 保持 能力. 這個宏 有
.Ql \&.Bk
(開始保持 begin-keep) 和
.Ql \&.Ek
(結束保持 end-keep ) .
.Ql \&.Bk
宏 的 唯一 參數是
.Fl words ,
用於 防止 在 選項語句 的 中間 斷行. 在 make 命令行參數的 例子裏 (參見
.Sx 名稱背後 What's in a name ) ,
keep 宏防止
.Xr nroff
把 標誌 和 參數 分成 兩行.
(事實上 可以 用 選項宏 防止 此類 事情, 但 當我們 決定 在
.Xr troff
中 作爲 基本選項, 強制 右邊界對齊 時, 它 在 稀疏行裏 展開的 很糟糕.
使用 保持宏 時 需要 多做點事, 增加 一個
.Fl line
選項 ) .
.Ss 示例和顯示
有 五種類型 的 顯示, 一個 快速的單行縮進顯示
.Ql \&.D1 ,
快速的單行原文顯示
.Ql \&.Dl ,
原文塊, 填充塊, 和由
.Ql \&.Bd
(begin-display) 顯示開始 和
.Ql \&.Ed
(end-display) 顯示結束 宏對 組成的 不規則塊.
.Pp
.Bl -tag -width \&.Dlxx
.It Li \&.D1
(D-one) 顯示 一行 縮進文字. 該宏 可以被 (其他宏) 分析, 但 不能 被調用.
.Pp
.Dl Fl ldghfstru
.Pp
上面是這樣產生的:
.Li \&.Dl Fl ldghfstru .
.It Li \&.Dl
(D-ell) 顯示 一行 縮進的
.Em 原文 literal .
.Ql \&.Dl
示例宏 已經 遍佈 這篇 文檔. 它 允許 縮進 (顯示) 一行 文字.
其 缺省字體 設爲 定寬 (原文), 它 可以 被 其他宏 分析 和 識別.
然而 不能 被 其他宏 調用.
.Pp
.Dl % ls -ldg /usr/local/bin
.Pp
上面是這樣產生的
.Li \&.Dl % ls -ldg /usr/local/bin .
.It Li \&.Bd
顯示開始.
.Ql \&.Bd
的 顯示 必須由
.Ql \&.Ed
宏 結束. 顯示 可以 嵌套在 顯示 和 列表中.
.Ql \&.Bd
有 這樣的 語法:
.Pp
.Dl ".Bd display-type [-offset offset_value] [-compact]"
.Pp
顯示類型 必須是 下面四個 之一, 可以 指定 一個 縮進量.
.Ql \&.Bd .
.Pp
.Bl -tag -width "file file_name  " -compact
.It Fl ragged
以 打字 形式 顯示 一塊 正文, 其 右(和左)邊界 是 不平整邊界.
.It Fl filled
顯示 填充 (格式化) 塊. 塊中文字 被 格式化 (邊界 已經 填充過, 
不再是 左邊 不對齊 ).
.It Fl literal
顯示 原文塊, 適用於 源程序, 或 那種 簡單的, 用 table 和
空格 調整的 文字.
.It Fl file Ar file_name
閱讀 並 顯示 跟在
.Fl file
標誌 後面的 文件. 原文模式 被打開, table 設爲 8個字符 寬, 然而 文件中 
出現的 任何
.Xr troff/ Ns Nm \-mdoc
命令 都將 被處理.
.It Fl offset Ar string
如果
.Fl offset
指定爲 下面 字符串 之一, 這些 字符串 解釋爲 對 以後的 正文塊的 縮進層次.
.Pp
.Bl -tag -width "indent-two" -compact
.It Ar left
正文塊 按 當前 左邊界 對齊, 這是
.Ql \&.Bd 
的 缺省模式.
.It Ar center
應該 是把 正文塊 布在 中間. 不幸的是, 目前 只能在 大致的 中間位置
靠左 對齊.
.It Ar indent
按 缺省 縮進值 或 table 值 縮進. 這個 缺省 縮進值 同時 用於
.Ql \&.D1
顯示, 因此 你 應該 使 這兩種 顯示 一致. 縮進值 一般 設爲 6n, 
大約 2/3 英寸 (六個字符寬度).
.It Ar indent-two
縮進 缺省值的 兩倍.
.It Ar right
在 距離 右邊界 大約 兩英寸處 把 正文塊 靠
.Em 左
對齊. 這個宏 要 試驗 效果, 有可能
.Xr troff 
怎麼 都 弄不對.
.El
.El
.It ".Ed"
End-display.
顯示結束.
.El
.Ss 字體模式 Font Modes
現有 五個宏 用於 改變 手冊頁的 文字外觀:
.Bl -tag -width \&.Emxx
.It \&.Em
文字 可以 用
.Ql \&.Em
宏 加重或強調. 常用的 強調字體 是 斜體 (italic).
.Pp
.Dl Usage: .Em argument ... 
.Bl -tag -width ".Em vide infra ) ) ," -compact -offset 14n
.It Li ".Em does not"
.Em does not
.It Li ".Em exceed 1024 ."
.Em exceed 1024 .
.It Li ".Em vide infra ) ) ,"
.Em vide infra ) ) ,
.El
.Pp
.Ql \&.Em
宏可以被 (其他宏) 分析和調用. 不帶參數 調用
.Ql \&.Em
宏 是 一個錯誤.
.It \&.Li
.Ql \&.Li
原文宏 用來 顯示 字符, 變量, 常數, 任何 希望 照 輸入文字 原樣顯示 的 內容.
.Pp
.Dl Usage: .Li argument ... 
.Bl -tag -width ".Li cntrl-D ) ,"  -compact -offset 14n
.It Li \&.Li \een
.Li \en
.It Li \&.Li M1 M2 M3\ ;
.Li M1 M2 M3 ;
.It Li \&.Li cntrl-D\ )\ ,
.Li cntrl-D ) ,
.It Li \&.Li 1024\ ...
.Li 1024 ...
.El
.Pp
.Ql \&.Li
宏可以被 (其他宏) 分析和調用.
.It \&.Sy
一般說來 symbolic 強調宏 無論在 象徵主義 角度, 還是 傳統的英語 裏,
都是 用 黑體 (bold) 顯示.
.Pp
.Dl Usage: .Sy symbol ... 
.Bl -tag -width ".Sy Important Noticex" -compact -offset 14n
.It Li \&.Sy Important Notice
.Sy Important Notice
.El
.Pp
.Ql \&.Sy
宏可以被 (其他宏) 分析和調用.
.Ql \&.Sy
的參數 可以 用 引號括起.
.It Li \&.Bf
字體模式開始.
.Ql \&.Bf
字體模式 必須用
.Ql \&.Ef
宏結束. 字體模式宏 可以 嵌套.
.Ql \&.Bf
宏 用 下面的 語法:
.Pp
.Dl ".Bf font-mode"
.Pp
字體模式 必須 是 下列 三種 之一:
.Ql \&.Bf .
.Pp
.Bl -tag -width "file file_name  " -compact
.It Sy \&Em | Fl emphasis
就象 是 把
.Ql \&.Em
宏 用在 整個 正文塊 一樣.
.It Sy \&Li | Fl literal
就象 是 把
.Ql \&.Li
宏 用在 整個 正文塊 一樣.
.It Sy \&Sy | Fl symbolic
就象 是 把
.Ql \&.Sy
宏 用在 整個 正文塊 一樣.
.El
.It ".Ef"
字體模式結束.
.El
.Ss 標記欄和列表 Tagged Lists and Columns
有 多種 用
.Ql ".Bl"
列表開始宏 初始化的 列表. 表項 用
.Ql ".It"
項目宏 指定, 每一個 列表 必須 用
.Ql ".El"
宏結束. 列表 可以 嵌套在 列表和顯示 中. 欄 可以 用在 列表 中, 但是 列表 
不能 列在 欄裏.
.Pp
另外 還可以 指定 列表屬性, 像標記寬度, 列表偏移, 以及 緊湊模式
(允許 或 不允許 表項間的 空行)
在本文中 大多 使用了 標記風格 (tag style) 的 列表
.Pq Fl tag .
作爲 步距變化, 表示 列表類型的 列表類型 是個 突出來 (overhanging) 的 列表
.Pq Fl ohang .
這種 列表類型 在
.Tn TeX
用戶中 很流行, 但 看過 很多 頁 的 標記列表 後 可能會 覺得 有點 滑稽.
.Ql ".Bl" 
宏 可以 接受 下面的 列表類型:
.Pp
.Bl -ohang -compact
.It Fl bullet
.It Fl item
.It Fl enum
這三個 是 最簡單的 列表類型. 一旦 使用了
.Ql ".Bl"
宏, 只能用
.Ql ".It"
宏 組織 表項 . 例如, 可以 這樣 寫 一個 簡單的 數字列表"
.Bd -literal -offset indent-two
\&.Bl -enum -compact
\&.It
\&Item one goes here.
\&.It
\&And item two here.
\&.It
\&Lastly item three goes here.
\&.El
.Ed
.Pp
結果是:
.Pp
.Bl -enum -offset indent-two -compact
.It
Item one goes here.
.It
And item two here.
.It
Lastly item three goes here.
.El
.Pp
簡單的布告欄:
.Bd -literal -offset indent-two
\&.Bl -bullet -compact
\&.It
\&Bullet one goes here.
\&.It
\&Bullet two here.
\&.El
.Ed
.Pp
產生:
.Bl -bullet -offset indent-two -compact
.It
Bullet one goes here.
.It
Bullet two here.
.El
.Pp
.It Fl tag
.It Fl diag
.It Fl hang
.It Fl ohang
.It Fl inset
這些 列表類型 收集
.Ql \&.It
宏 指定的 參數, 並且 創建 一個 標籤, 它 可能會
.Em 插入 inset
後面的 文字中,
.Em 懸掛 (hanged)
顯示在 後面的 文字前,
.Em 突前 (overhanged)
顯示在 更高 位置, 並且 不能 縮進 或
.Em 標記 tagged .
這個 列表 由
.Ql Fl ohang
列表類型 構建.
.Ql \&.It
宏 只能 被 插入 (inset), 懸掛 (hang), 和 標記列表類型宏 分析,
且 不能 被調用. 
.El
這是 一個 插入標籤 的 例子:
.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
.Pp
下面是 產生 這個例子 的 源文本:
.Bd -literal -offset indent
\&.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
.Ed
.Pp
這是 含有 兩個表項 的 懸掛列表:
.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
.Pp
它們的 源文本爲:
.Bd -literal -offset indent
\&.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
.Ed
.Pp
帶有 可選 寬度項的 標記列表 可以 控制 標記的 寬度.
.Pp
.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
.Pp
源文本是:
.Bd -literal -offset indent
\&.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
.Ed
.Pp
可接受的 寬度說明:
.Bl -tag -width Ar -offset indent
.It Fl width Ar "\&Fl"
把 寬度 設置爲 標誌 (flag) 的 缺省 寬度. 所有 可調用的 宏 都有
一個 缺省 寬度值. 目前
.Ql \&.Fl 
的 值 設爲 十個 字符寬度, 大約 5/6 英寸.
.It Fl width Ar "24n"
設置 寬度 爲 24 個 字符寬度, 大約 兩英寸. 要使 比例 調整正常, 字母
.Ql n
必不可少
.It Fl width Ar "ENAMETOOLONG"
設置 寬度爲 所給串的 長度.
.It Fl width  Ar "\\*qint mkfifo\\*q"
同樣, 設置 寬度爲 所給串的 長度.
.El
.Pp
如果 沒有 爲 標記列表類型 指定 寬度, 第一次 調用
.Ql \&.It
的 時候, 格式化軟件 試圖 決定 適當的寬度. 如果
.Ql ".It"
的 第一個 參數 是 可調用宏, 就 使用 這個宏的 缺省寬度, 就像 把 宏名 當做寬度.
可是 如果 列表中 的 其他表項 得到 另一個 可調用宏, 則 認爲 它是 新的, 
嵌套的 列表.
.Sh 預定義串 PREDEFINED STRINGS
下面的串 是 預定義的, 可以 用在 troff 的 串翻譯序列
.Ql \&\e*(xx
中, 這裏的
.Em xx
就是 定義的 串名; 以及 串翻譯序列
.Ql \&\e*x ,
這裏的
.Em x
是串名. 翻譯序列 可以 用在 文本 的 任何地方.
.Pp
.Bl -column "String " "Nroff " "Troff " -offset indent
.It Sy "String	Nroff	Troff"
.It Li "<=" Ta \&<\&= Ta \*(<=
.It Li ">=" Ta \&>\&= Ta \*(>=
.It Li "Rq" Ta "''" Ta \*(Rq
.It Li "Lq" Ta "``" Ta \*(Lq
.It Li "ua" Ta ^ Ta \*(ua
.It Li "aa" Ta ' Ta \*(aa
.It Li "ga" Ta \` Ta \*(ga
.\" .It Li "sL" Ta ` Ta \*(sL
.\" .It Li "sR" Ta ' Ta \*(sR
.It Li "q" Ta \&" Ta \*q
.It Li "Pi" Ta pi Ta \*(Pi
.It Li "Ne" Ta != Ta \*(Ne
.It Li "Le" Ta <= Ta \*(Le
.It Li "Ge" Ta >= Ta \*(Ge
.It Li "Lt" Ta < Ta \*(Gt
.It Li "Gt" Ta > Ta \*(Lt
.It Li "Pm" Ta +- Ta \*(Pm
.It Li "If" Ta infinity Ta \*(If
.It Li "Na" Ta \fINaN\fP Ta \*(Na
.It Li "Ba" Ta \fR\&|\fP Ta \*(Ba
.El
.Pp
.Sy 注意 :
那個 名爲
.Ql q
的 串 應該 寫成
.Ql \e*q ,
因爲 它 只有 一個字符.
.Sh 診斷 DIAGNOSTICS
.Nm \-mdoc
的 除錯系統 比較 有限, 但是 可以 幫助你 檢測出 微妙的 錯誤,
例如 參數名 和 內部寄存器 或 宏名 衝突. (是什麼?) 寄存器 是
.Xr troff
的 算術存儲類, 用 一到二個字符 命名.
.Nm \-mdoc
對
.Xr troff
和
.Xr ditroff
而言, 所有
.Nm \-mdoc
的 內部寄存器 由 兩個字符 組成, 格式是 <大寫字母> <小寫字母> 如
.Ql \&Ar ,
<小寫字母> <大寫字母> 如
.Ql \&aR
或 <字母> <數字> 如
.Ql \&C\&1 .
作爲 亂上加亂,
.Xr troff
有 它 自己的 內部寄存器, 由 兩個 小寫字母 組成, 或者 是 一個點 加上 
一個字母, 或者 是 轉義字符 (meta-character) 和 字符. 已經 介紹過的 
示例中 展示過 怎樣用 轉義序列
.Ql \e& 
防止 解釋宏. 這辦法 同樣 適用於 內部寄存器名.
.Pp
.\" Every callable macro name has a corresponding register
.\" of the same name (<upper_case><lower_case>).
.\" There are also specific registers which have
.\" been used for stacks and arrays and are listed in the
.\" .Sx Appendix .
.\" .Bd -ragged -offset 4n
.\" [A-Z][a-z]	registers corresponding to macro names (example ``Ar'')
.\" [a-z][A-Z]	registers corresponding to macro names (example ``aR'')
.\" C[0-9]		argument types (example C1)
.\" O[0-9]		offset stack (displays)
.\" h[0-9]		horizontal spacing stack (lists)
.\" o[0-9]		offset (stack) (lists)
.\" t[0-9]		tag stack (lists)
.\" v[0-9]		vertical spacing stack (lists)
.\" w[0-9]		width tag/label stack
.\" .Ed
.\" .Pp
如果 未經轉義的 寄存器名 出現在 宏請求的 參數列表 中, 其 後果 不可預測.
一般說來, 如果 大段的文字 沒有 出現在 該出現的 地方, 或者 短句, 如標籤, 
消失了, 多半是 這個地方 誤解了 參數列表中的 參數類型.
既然 你的母親 都 沒打算 讓你 記住 那些 亂七八糟的 東西, 那就 用 一種辦法
來 找出 參數 是否 有效: 
.Ql \&.Db
(debug) 宏 可以 顯示出 對 大多數宏 的 參數列表的 解釋.
諸如
.Ql \&.Pp
之類 的 宏 不包含 調試信息, 但是 所有 可調用宏 包含, 我們 強烈建議 一旦
有 疑點, 打開
.Ql \&.Db
宏.
.Pp
.Dl Usage: \&.Db [on | off]
.Pp
在 這個 示例中, 我們把 介於 debug 宏 之間 的 文本 故意 弄出點 錯誤 (標誌參數
.Ql \&aC
應該 寫成
.Ql \e&aC
):
.Bd -literal -offset indent
\&.Db on
\&.Op Fl aC Ar file )
\&.Db off
.Ed
.Pp
結果輸出爲:
.Bd -literal -offset indent
DEBUGGING ON
DEBUG(argv) MACRO: `.Op'  Line #: 2
	Argc: 1  Argv: `Fl'  Length: 2
	Space: `'  Class: Executable
	Argc: 2  Argv: `aC'  Length: 2
	Space: `'  Class: Executable
	Argc: 3  Argv: `Ar'  Length: 2
	Space: `'  Class: Executable
	Argc: 4  Argv: `file'  Length: 4
	Space: ` '  Class: String
	Argc: 5  Argv: `)'  Length: 1
	Space: ` '  Class: Closing Punctuation or suffix
	MACRO REQUEST: .Op Fl aC Ar file )
DEBUGGING OFF
.Ed
.Pp
調試信息的 第一行 是 調用的 宏名, 這裏是
.Ql \&.Op 
和 它 所在的 行號. 如果 涉及了 一個 或 多個 文件 (特別是 其他文件 
包含進來), 行號有可能失靈. 但如果 只有 一個文件, 它 應該是 準的.
第二行 給出了 參數計數, 參數
.Pq Ql \&Fl
和 它的長度. 如果 參數的長度 是 兩個字符, 將會 測試 看它 能否 執行 
(不幸的是,含有 非零值 的 寄存器 看上去 都能執行).
第三行 給出 分配給類的 空間, 以及 類的類型. 這裏的 問題是, 參數 aC 
不應該 可執行. 類的 四種類型是 字符串, 可執行類, 結束標點, 和開始標點.
最後一行 顯示了 讀入的 完整 參數行. 下個例子裏, 惹禍的
.Ql \&aC
被轉義了:
.Bd -literal -offset indent
\&.Db on
\&.Em An escaped \e&aC
\&.Db off
.Ed
.Bd -literal -offset indent
DEBUGGING ON
DEBUG(fargv) MACRO: `.Em'  Line #: 2
	Argc: 1  Argv: `An'  Length: 2
	Space: ` '  Class: String
	Argc: 2  Argv: `escaped'  Length: 7
	Space: ` '  Class: String
	Argc: 3  Argv: `aC'  Length: 2
	Space: ` '  Class: String
	MACRO REQUEST: .Em An escaped &aC
DEBUGGING OFF
.Ed
.Pp
參數
.Ql \e&aC
表現出 同樣的 長度2, 這是 因爲
.Ql \e&
序列的 長度 爲零, 但是 不存在 叫做
.Ql \e&aC
的 寄存器, 因此 它的類型 是 字符串.
.Pp
其他 診斷內容 是 使用報告等, 能夠 自我解釋的.
.Sh GROFF, TROFF AND NROFF
The
.Nm \-mdoc
宏包 不需要 和
.Xr groff 
的 兼容模式.
.Pp
爲了 便於 在線閱讀, 這個宏包 阻止了 分頁, 頁頭, 頁腳 之類 常常在
.Xr nroff 
中 出現的 中斷. 此時 即使在 手冊頁 尾,
.Xr groff
(和參數
.Fl T Ns Ar ascii
) 也 不會 提示 什麼. 對 分頁的 阻止 使得
.Xr nroff Ns 'd
文件 不適合 硬拷貝 (hardcopy). 有一個 名爲
.Ql \&cR
的 寄存器 可以 通過 在 文件
.Pa /usr/src/share/tmac/doc-nroff
(依賴於宿主系統) 中置零, 恢復 傳統風格.
.Sh 相關文件 FILES
.Bl -tag -width /usr/share/man0/template.doc -compact
.It Pa /usr/share/tmac/tmac.doc
手冊宏包
.It Pa /usr/share/misc/mdoc.template
編寫 手冊 的 模板
.It Pa /usr/share/examples/mdoc/*
一些 手冊頁 的 例子
.El
.Sh 另見 SEE ALSO
.Xr man 1 ,
.Xr troff 1 ,
.Xr mdoc 7
.Sh BUGS
仍然 沒有 解決 在 標誌參數中的 連字符, 在
.Sx 描述 DESCRIPTION
小節 偶爾 會 出點麻煩 (在 連字符處 斷行).
.Pp
文檔中 沒有 聲明 預定義串.
.Pp
還沒有 把 3f 小節 加進 頭例程 (header routine) 中.
.Pp
.Ql \&.Nm
字體 不應當在
.Sx NAME
小節 中 改變.
.Pp
應該 檢查
.Ql \&.Fn
防止 行 太短 的 時候 斷行.
偶然 它會 斷開 反括弧, 而 有時候 如果 某行 已滿時, 看上去 會 很可笑.
.Pp
當 使用 nroff 格式化 文檔 時, 防止 頁頭和頁腳 (不是 初始的 頭和腳) 斷開 的 方法
有可能 偶爾 在 頁的底部 產生 一個 不可見的 部分填滿的 行 (空行).
.Pp
列表和顯示宏不做任何保存, 顯然它應該做的.
.\" Note what happens if the parameter list overlaps a newline
.\" boundary.
.\" to make sure a line boundary is crossed:
.\" .Bd -literal
.\" \&.Fn struct\e\ dictionarytable\e\ *dictionarylookup struct\e\ dictionarytable\e\ *tab[]
.\" .Ed
.\" .Pp
.\" produces, nudge nudge,
.\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] ,
.\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] ,
.\" nudge
.\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] .
.\" .Pp
.\" If double quotes are used, for example:
.\" .Bd -literal
.\" \&.Fn \*qstruct dictionarytable *dictionarylookup\*q \*qchar *h\*q \*qstruct dictionarytable *tab[]\*q
.\" .Ed
.\" .Pp
.\" produces, nudge nudge,
.\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" ,
.\" nudge
.\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" ,
.\" nudge
.\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" .
.\" .Pp
.\" Not a pretty sight...
.\" In a paragraph, a long parameter containing unpaddable spaces as
.\" in the former example will cause
.\" .Xr troff
.\" to break the line and spread
.\" the remaining words out.
.\" The latter example will adjust nicely to
.\" justified margins, but may break in between an argument and its
.\" declaration.
.\" In
.\" .Xr nroff
.\" the right margin adjustment is normally ragged and the problem is
.\" not as severe.
.Sh "[中文版維護人]"
.Sy 徐明 <xuming@users.sourceforge.net>
.Sh "[中文版最新更新]"
.Sy 2003/05/13
.Sh "《中國Linux論壇man手冊頁翻譯計劃》"
.Sy http://cmpp.linuxforum.net
.Sh "跋"
.br
本頁面中文版由中文 man 手冊頁計劃提供。
.br
中文 man 手冊頁計劃：\fBhttps://github.com/man-pages-zh/manpages-zh\fR