Provided by: manpages-zh_1.5-1_all bug

NAME ()
     mdoc.samples - 用 -mdoc 編寫 BSD 手冊 的 示範教程

SYNOPSIS ()
     man mdoc.samples

DESCRIPTION (z)
     這 示範教程 用於 編寫 BSD 手冊 (manual page), 它 使用了 -mdoc 宏定義包,
     這是 e 和  (domain-base) 的 格式化包, 交由 troff(1) 處理.
     它的 前 -man(7) 包, 定義了 雇布局 (page layout), 但是 把 諸如 字型控制
     和 其他 排版 細節 留給了 每一 作者. 在 -mdoc 包裏, 雇布局宏 構成了
     c (page structure domain) 它 由 標題, 小節熙, 顯示 (displays) 和
     列表 宏 組成. 這些 基本項目 影響 正文 在 格式化隊W 的 物理位置.  作為
     項硎c宏域 的 補充, 這裏 還 定義了 另外 兩 宏域, 手冊宏域 和
     基本正文宏域. 基本正文宏域 定義了 一些 宏, 執行 例如 引文 或 文字強調
     之類的任務.  手冊宏域 定義的宏 是 非正式 日常用語 的 子集, 用於 描z 命令,
     例程 和 相關的 BSD 檔案.  手冊宏域裏 的 宏 用來處理 命令名,
     命令行參數和選項, 函數名稱, 函數參數, 路徑, 變量, 以及 到 其他手冊 的
     參照 等.  這些 域項 留有 為 作者 和 手冊隍 未來使用者 設置的 .  希望 從
     手冊集中 獲得的 一P性 能夠為 將來的 文件工具 提供 更簡單的 轉換.

     從 整茠 UNIX 手冊 上 來看, 每 手冊項 可以 簡單的 理解為 一 man page,
     不用 注意 它的 實際長度, 也沒有 性別歧視 意圖. (譯注: 可能是雙關語, man
     page...男人)

}l GETTING STARTED
     因為 人 通常是 為了 能夠 馬上 使用 這些材料 的 時 才 閱讀 教程,所以
     我 假設 此文件的 使用者 是 缺乏@心的.下 簡z一下 這份文件 剩餘部分 的
     組織:

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

           2.   手冊隍熊硎c分析
                      手冊隍獐猁O.

           3.   標題宏.

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

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

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

           7.   項硎c宏域
                      小節熙.
                      段落和空行.
                      保持 (Keeps).
                      顯示.
                      字型模式 (加, 鴗憍M Symbolic).
                      列表和欄.

           8.   預定義串

           9.   診斷

           10.  用 GROFF, TROFF 和 NROFF 格式化

           11.  臭蟲 BUGS

TROFFS性
     使用 -mdoc 宏包 的 目的 是 簡化 寫手冊 的 過程. 理論上講, n使用 -mdoc
     不一定 n 學習 troff(1) 的 腌臟細節; 然而, 有些 制 無法回避, 最好 把它
     擺.  而且 你 應該 知道, 這 宏包 的 速度 比較 C.

  k Macro Usagetroff(1) 裏, 宏調用的形式 是 在行 以 '.' (句點符) 起始, 緊隨其後 是
     作為 宏名 的 兩茼r符. 參數 跟在 宏名 之後, 用 空格符 隔開. 這 位於行漯
     句點符 使 troff(1) 把 緊隨其後 的 兩茼r符 視作 宏名. 在 某些情況下 n把
     '.' (句點符) 放在 行, 但不希望 被理解成 宏請求, 方法是 在 '.' (句點) 前
     使用 '\&' 轉義序列.  '\&' 被 解釋成 一段 長度為零 的 空白, 所以 不會 在
     輸出端 顯示 出來.

     一般說來, troff(1) 宏 最多 接受 九荌捊, 忽略掉 其餘的. 大多數 在 -mdoc
     裏的 宏 支持 九荌捊, 某些場合 可以 續加 參數, 或擴展到 下一行. (見 Xi
     Extensions).  有些宏 能夠 處理 引號 引起來的 參數 (見 下悸
     b).

     大多數 -mdoc 的 基本正文宏域 和 手冊宏域 的宏 擁有 一種特性, 表現在 把
     參數列表 當成 可調用的宏 R ().  這意味著 如果 參數列表裏的參數 是
     普通正文宏域 或 手冊宏域 裏的 宏, 並且 是 可調用宏, 那麼 處理的時 會
     執行 或 調用.  這種情況下的 參數, 即 宏名, 不需n 用 '.' (句點符) 引導.
     這種榆 使 很多 宏 嵌套 在 一起; 例如 這 選項宏 '.Op', 可能 北
     標誌和參數宏, 'Fl' 和 'Ar', 用來 說明 一 帶參數的 選項:

           [-s bytes]         來自 .Op Fl s Ar bytes

     為了 防止 把 兩茼r符的字符串 解釋成 宏名, 在這 字符串 前 加上 '\&'
     轉義序列:

           [Fl s Ar bytes]    來自 .Op \&Fl s \&Ar bytes

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

  b Passing Space Characters in an Argument
     某些時 我 希望 能夠 把 含有 一茤峖h 空格符 的 字符串 作為 單荌捊
     傳遞. 如果 n 突破 九荌捊漕, 或者 傳遞給 宏 的 參數 需n 一些 特定布置,
     這 能力 是必須的. 例如, 函數宏 '.Fn' 的 第一荌捊 是 函數名稱,
     剩下的參數 作為 函數的參數.  ANSI C 規定 函數的參數 在 圓括弧內 聲明, 每
     參數 至少 由 兩 標示符 組成.  例如, int foo.

     有 兩茪隤k 傳遞 嵌有空格符 的 參數.  R@I: 不幸的是, 在 AT&T troff
     中, 那 最容易的方法, 就是 作為 單 參數 傳遞 兩茪瑏馱孜〞
     字符串和空格符, 非常 消耗 時間 和 記憶體空間.  雖然 它 對 groff 並不費事,
     但是 為了 可移植性, 這種 做法 只於 下列 有═覬愯 的 宏:

           Cd    配置聲明 (手冊第四部分 n SYNOPSIS)
           Bl    列表開始 (指定寬度的)
           Em    加咫憒r
           Fn    函數 (手冊第二, 四部分)
           It    列表項
           Li    鴗
           Sy    Symbolic text
           %B    書題
           %J    期刊名
           %O    參考選注
           %R    報告題目(在參考檔案中)
           %T    在書籍或期刊中的題目

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

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

           fetch(char *str)  也可以來自 '.Fn fetch "char *str"'

     如果 忽略 '\' 或 引號, '.Fn' 宏 會認為 有 三荌捊, 結果 成為:

           fetch(char, *str)

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

   Trailing Blank Space Characters
     Troff 可能 被 行尾的 空白符 搞亂, 它的防S規則 是 消除 所有 位於行末 的
     空白符.  如果 堅持 在 行末 加上 空白符, 可以 用 硬空格符 和 '\&'
     轉義字符. 例如, 'string\ \&'.

  qSr Escaping Special Characters
     特殊字符, 如 換行符 '\n', 是 通過 用 '\e' 替換 '\' (e.g.例如 '\en')
     保留住 反斜槓.

UcR THE ANATOMY OF A MAN PAGE
     手冊 可以 很容易的 通過 模板 構建, 模板 放在
     /usr/share/misc/mdoc.template.  另外 在 /usr/share/examples/mdoc 目錄下
     有一些 手冊 的 例子.

  UO A manual page template
           .\" 所有的手冊雲τ求有下悸漱漁e
           .Dd 月 日, 年Month day, year
           .Os 作業系統 [版本/發行號]
           .Dt 文件標題 [手冊節號][卷]
           .Sh 名稱 NAME
           .Nm 名稱 name
           .Nd 對名稱的簡單描z one line description of name
           .Sh 總覽 SYNOPSIS
           .Sh 描z DESCRIPTION
           .\" 後悸漱漁e取消注釋後可以用在你需n的任何地方.
           .\" 緊接著的這條命令用於手冊第二和第三部分, 函數的返回.
           .\" .Sh 返回 RETURN VALUES
           .\" 下悸漫R令用於手冊第1, 6, 7, 8部分.
           .\" .Sh 環境 ENVIRONMENT
           .\" .Sh 檔案 FILES
           .\" .Sh 示例 EXAMPLES
           .\" 下悸漫R令用於手冊第1, 6, 7, 8部分
           .\"     (在shell下的命令返回M標準錯誤類型的診斷)
           .\" .Sh 診斷 DIAGNOSTICS
           .\" 下悸漫R令用於手冊第二和第三部分中的錯誤和信號處理.
           .\" .Sh 錯誤 ERRORS
           .\" .Sh 另見 SEE ALSO
           .\" .Sh 遵循 CONFORMING TO
           .\" .Sh 歷史 HISTORY
           .\" .Sh 作者 AUTHORS
           .\" .Sh BUGS

     模板中 的 第一茬﹞ 是 (.Dd, .Os, .Dt) 宏; 文件日期, 手冊或其內容 針對的
     作業系統, 手冊隍獐陏D ((jg)) 和 該手冊 所屬的節 (部分號).  這些宏
     確認和標識了 這茪漭U. 在 後悸 D TITLE MACROS 將 繼續 討論.

     這 模板中 的 其餘部分 是 小節熙 (section header) (.Sh); 其中 W NAME,
     ` SYNOPSISyz DESCRIPTION 是 必不可少的.  這些 熙 在 c 中
     討論 ( 介紹完 U 之後 ) .  有一些 內容宏 被用來 示範 雇布局宏; 建議
     接觸 雇布局宏 前 先看看 內容宏.

D TITLE MACROS
     標題宏 是 項硎c宏域 的 第一部分, 但 在 過去, 人 如果 編寫 手冊, 它 是
     手冊的 第一部分, 也是 獨立部分. 這裏 設p了 三荍 分別 描z 文件標題 或
     手冊標題, 作業系統, 和 製作日期. 它 放在 文件的 最前, 一次 只 調用 一,
     用來 構建 文件的 黃Y 和 飧}.

     .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

             或者 像 q制的產品

                   .Os CS Department

             作為 伯克利的預設設置, 不帶 參數 的 '.Os' 定義為 BSD (指定在檔案
             /usr/share/tmac/mdoc/doc-common 中). 你 應該 把預設 設成 本機.
             注意, 如果 不設置 '.Os' 宏, 雇的左下角 會 很難看.

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

                   January 25, 1989

U M紹
  WI What's in a name...
     手冊宏域 的 宏名 來自 非正式的 日常用語, 用來 描z 命令, 子程式 及其
     相關檔案. 在 寫 手冊 時, 文字用語 有些 輕微的變化, 分別描z 三 不同
     應用. 漸是 -mdoc 宏請求 的 用法. 其次, 用 -mdoc 宏 描z UNIX 命令. 最後,
     對 使用者 具體的描z 這條命令; 也就是 在 手冊 正文 裏 討論這條命令.

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

           .Va argument1 argument2 ... argument9

     這裏的 '.Va' 是 巨集 或 宏請求, 緊隨其後 的 是 待處理的參數.  第二種 情況
     下, 使用 內容宏 描z 一條 UNIX 命令 n 復雜 些; 一 典型的 ` SYNOPSIS
     命令行 顯示 如下:

           filter [-flag] infile outfile

     這裏的 filter 是 命令名稱, 方括弧內 的 -flag 是一 x 參數, 作為
     可選參數 放在 代表 選項 的 方括弧內. 在 -mdoc 術語 中, infileoutfile
     稱為 .  產生 上z效果 的 宏 是 這樣的:

           .Nm filter
           .Op Fl flag
           .Ar infile outfile

     第三種 情況 討論 命令 及其語法, 包括 它怐漕狺l, 可能 還有 更多細節.  上-
     悸漕狺l裏, 可以把 infileoutfile 理解為 @ 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' 參數宏, 用於 描z 操作對象 或 檔案參數 如 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' 宏.

  yk General Syntax
     手冊宏域 和 基本正文宏域 的 宏 有著 相似的語法, 僅有 微小差別: '.Ar',
     '.Fl', '.Nm', 和 '.Pa' 僅當 無參數調用時 才有 區別; '.Fn' 和 '.Xr' 的
     參數列表 n求 一定的 順序; '.Op' 和 '.Fn' 宏有嵌套制. 所有的 內容宏 能夠
     識別和正確處理 標點符號, 每 標點符號 n在 前 用 空格 隔開. 如果 給出
     這樣的 宏請求:

           .Li sptr, ptr),

     結果是:

           sptr, ptr),

     標點符號 沒有 被識別 出來, 全都按 鴗憒r型 輸出. 如果 標點符號 前悼
     空格符 隔開:

           .Li sptr , ptr ) ,

     結果是:

           sptr, ptr),

     標點符號 被 識別出來 了, 預設的字型 也 有別於 鴗憭憒r的字型.

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

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

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

U MANUAL DOMAIN
  a} 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' 可以被 (其他宏) 調用和分析.

  @W Author Name
     The '.An' 宏用以 說明 這茪憟顗 描z對象的 作者, 或者 這篇手冊隍 作者.
     名字 信息 後悸 其他參數 被認為是 標點符號.

           Usage: .An author_name
                   .An Joe Author
                                  Joe Author
                   .An Joe Author ,
                                  Joe Author,
                   .An Joe Author Aq nobody@FreeBSD.ORG
                                  Joe Author <nobody@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' 宏可以被 (其他宏)
     分析和調用.

  tmwq () Configuration Declaration
     '.Cd' 宏用於描z config(8) 對 設備接口的定義 (手冊第四部分).  這荍 接受
     引號內的參數 (只能是雙引號).

           device le0 at scode?  來自: '.Cd device le0 at scode?'.

  RO Command Modifier
     命令袡╡貍M '.Fl' (標誌) 命令相似, 除了 '.Cm' 宏 不在 任何參數 前 加
     短橫線 (dash).  傳統的標誌 以 短橫線 開頭, 但 一些 命令 或 命令的子集
     不用這.  命令袡╡ 也可以 和 交互命令 結合 使用, 如 編輯命令. 另見
     Flags.

  wwqq 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' 宏可以被 (其他宏) 分析和調用.

  q Environment Variables
     '.Ev' 宏說明一蚗藿疻僆q.

           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' 宏可以被 (其他) 宏分析和調用.

  n Function Declaration
     '.Fd' 宏 用於 第二或 第三部分 手冊 的 ` SYNOPSIS 小節.  '.Fd' 宏 既
     不調用 其他宏, 也 不能 被 其他宏調用.

           Usage: .Fd include_file (or defined variable)

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

  x Flags
     '.Fl' 宏 處理 命令行標誌. 它 在 標誌前 加一 短橫線 '-', 對於 交互命令
     標誌, 它 不需n 短橫線, 可以用 '.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' 的參數, 結果 會 得到 兩茧u橫線.  '.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 小節 有 一茈H上的 函數聲明,
     而且 函數類型 沒有 說明, 則 會產生 一 斷行.  在 函數 和 函數 的 垂直方向
     上 產生 一定的 空白. 此時 '.Fn' 宏 不按 troff 的 行長 檢查 單詞 邊界,
     有可能 難看的 從 單詞中間 斷開.  以後 會 解決 這 問題.

   Function Type
     這荍 設p 用在 ` SYNOPSIS 小節. 它 可以 毫無困難的 用在 手冊隍 其他
     地方, 但 它的 主n 目的 是 為 第二 和 第三部分 手冊隍 ` SYNOPSIS 小節,
     以 核心標準形式 (kernel normal form) 描z 函數類型 (它 導P 斷行, 在 下一行
     顯示 函數 名稱).

           Usage: .Ft type ...
                   .Ft struct stat  struct stat

     '.Ft' 宏不能被其他宏調用.

  RO Interactive Commands
     宏 '.Ic' 用於 說明 交互 或 內部命令.

           Usage: .Ic argument ...
                   .Ic :wq             :wq
                   .Ic do while {...}  do while {...}
                   .Ic setenv , unsetenv
                                       setenv, unsetenv

     不帶參數調用 '.Ic' 是蚇欞~.  '.Ic' 宏可以被 (其他宏) 分析和調用.

  W Name Macro
     '.Nm' 宏 用於 說明 文件題目 或 主題. 它的特點 是 能夠 記住 調用時 帶的
     第一 參數, 這 參數 就是 該隍 主題. 當 不帶 參數 調用它 時, '.Nm' 宏 把
     以前 記住的 參數 顯示 出來, 可以 為作者 省點勁.  注意:
     手冊第二部分或第三部分的函數名稱, 在 W 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' 可以被 (其他宏) 分析和調用.

  |W Pathnames
     '.Pa' 宏 用於 格式化 路徑 或 檔名.

           Usage: .Pa pathname
                   .Pa /usr/share   /usr/share
                   .Pa /tmp/fooXXXXX ) .
                                    /tmp/fooXXXXX).

     '.Pa' 宏可以被 (其他宏) 分析和調用.

  q Variables
     基本的 變量 參考:

           Usage: .Va variable ...
                   .Va count   count
                   .Va settimer,
                               settimer,
                   .Va int *prt ) :
                               int *prt):
                   .Va char s ] ) ) ,
                               char s])),

     不帶參數調用 '.Va' 宏是蚇欞~.  '.Va' 宏可以被 (其他宏) 分析和調用.

  U 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' 宏可以被 (其他宏) 分析和調用.

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

            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'

     除了 下悸 不規則宏, 所有的 引用宏 可以被 (其他宏) 分析和調用. 所有的
     引用宏 能夠 正確 處理 標點符號, 只n 一次 一茼r符, 中間 用 空格 隔開.
     引用宏 檢查 開始和結束 符號, 以決定 把 它 放在 引用串的 前掄椄O後.  這樣
     就 有了 一定的 嵌套能力.

     .Ec, .Eo  這些宏 的 第一荌捊 是 各自的 開始和結束串.

     .Ql       鴗憭犍峓 的 表現在 troff 中和 nroff 不一樣. 如果用 nroff
               格式化, 引用的鴗 始終 被引用. 如果用 troff 格式化, 只有 寬度
               小於 三茤w寬字符 的 項 才被 引用.  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' 用在 某 巨集行 上, 意如其名, 將  被格式化, 語法 遵循 一般的
     內容宏.

  L Space Macro
     '.Ns' 在 宏請求 之間 消除 不需n的 空格.  它 用在 舊式榆瑼 參數列表 中,
     標誌和參數 間 沒有 空格:

           .Op Fl I Ns Ar directory
                            產生 [-Idirectory]

     注意: '.Ns' 宏 在 消除空格後 總會 調用 '.No' 宏, 除非 還有 其他 宏名 跟在
     後.  '.Ns' 宏可以被 (其他宏) 分析和調用.

  U Section Cross References
     '.Sx' 宏 指定了 到 同一茪憟韝漯 小節熙 的 對照參考.  該宏可以被
     (其他宏) 分析和調用.

                   .Sx FILES     FILES

  M 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     參考開始. 它 導P 一次 斷行, 並且 開始 收集 參考資料, 直到
                   遇到 參考結束宏.
           .Re     參考結束. 則 列印出 參考信息.
           .%A     參考資料 的 作者名字, 一次一.
           .%B     書名.
           .%C     城市/地點.
           .%D     日期.
           .%J     期刊名.
           .%N     發行號.
           .%O     可選信息.
           .%P     飭X.
           .%R     報告名.
           .%T     文章題目.
           .%V     卷.

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

  ^ Return Values
     '.Rv' 宏 產生 一些 用在 ^ RETURN VALUES 小節的 文字.

           Usage: .Rv [-std function]

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

     The atexit() function returns the value 0 if successful; otherwise the
     value -1 is returned and the global variable errno is set to indicate the
     error.

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

   Trade Names ()
     trade name 宏 一般說來 是 一 很小的 大寫字母宏, 用於 所有 大於 兩茼r符的
     大寫單詞.

           Usage: .Tn symbol ...
                   .Tn DEC
                          DEC
                   .Tn ASCII
                          ASCII

     '.Tn' 宏可以被 (其他宏) 分析和調用.

  Xi Extended Arguments
     '.Xo' 和 '.Xc' 宏 可以 在 宏的邊界 擴展 參數列表. 如果 某荍 n求
     所有的參數 在 一行上 出現, 則 參數列表 不能 在 這兒 被 擴展. 例如 '.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' 和 引用宏: 測試一蚥僆q的.

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

     產生

           .ifndef [!]variable [operator variable ...]

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

c PAGE STRUCTURE DOMAIN
  p` Section Headers
     每 手冊 裏 都用到了 下 列出的 三 '.Sh' 小節熙“. 作者 寫 手冊 時
     可以 酌情考慮 其他 建議使用的 小節熙.  '.Sh' 宏 最多 帶 九 參數. 它
     可以 被 (其他宏) 分析, 但不能 被調用.

     .Sh 名稱 NAME
               '.Sh 名稱 NAME' 宏是 必不可少的. 否則 無法設置 黃Y, 飧} 和
               預設的 階洹, 樣子 會 很難看.  W NAME 小節 至少 由 三項
               組成. 第一 是 '.Nm' 名稱宏, 命名 手冊隍 主題. 第二 是
               名稱描z宏 '.Nd', 它 把 主題名稱 和 第三項, 描z, 分離開來.  描z
               應該 盡可能的 精簡易懂, 少佔空間.

     .Sh 總覽 SYNOPSIS
               SYNOPSIS 總覽小節 描z 該 手冊飪龠H 的 典型用途.  請求的宏 是
               下 的 任意一, '.Nm', '.Cd', '.Fn', (也可能是 '.Fo', '.Fc',
               '.Fd', '.Ft' 宏). 函數名稱宏 '.Fn' 用在 手冊 的 第二第三部分,
               命令 和 基本名稱宏 '.Nm' 用在 手冊 的 1, 5, 6, 7, 8 部分. 手冊
               第四部分 需n '.Nm', '.Fd' 或 '.Cd' 配制設備用途宏. 其他一些 宏
               可能 用來 產生 概n行, 像下悸:

                     cat [-benstuv] [-] file ...

               下 用到的 宏

                     .Nm cat
                     .Op Fl benstuv
                     .Op Fl
                     .Ar

              `N: 宏 '.Op', '.Fl', 和 '.Ar' 能夠 識別 管道符 '|', 因此
               命令行 如:

                     .Op Fl a | Fl b

               的 表現 會 出y.  Troff 一般把 | 當做 特殊符號. 參見 wwq
               PREDEFINED STRINGS, 在 其他情況下 | 的使用.

     .Sh 描z DESCRIPTION
               大多數 情況下 yz DESCRIPTION 小節 的 第一段話 是 關於 這
               命令, 函數 或 檔案 的 摘n, 後跟 字典式的 選項 以及 相應的解釋.
               創建 這樣的 列表, 應該 使用 '.Bl' 列表開始, '.It' 列表項和
               '.El' 列表結束宏 (參見下悸 CM Lists and Columns ).

     下悸 '.Sh' 小節熙 是 手冊 編排的 常見內容, 為了 保証 連續性, 應 適當
     使用.  它 按照 應該 出現 的 順序 排列.

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

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

     .Sh 檔案 FILES
               由 手冊隍 主題對象 創建 或 使用 的 檔案, 應該 通過 '.Pa' 宏在
                FILES 小節 陳列 出來.

     .Sh 另見 SEE ALSO
               如果 提及 其他 手冊 或 參照 相應的 手冊, 應 把它 放在 t
               SEE ALSO 小節. 參照主題 由 '.Xr' 宏指定. 在 t 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 C''), 那就
               不需n 這一小節. 如果 命令 不符合 任何標準, 應該 把 它的歷史
               放在 v HISTORY 小節.

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

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

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

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

     .Sh BUGS  明顯的 問題 放這兒...

     可以 增加一些 使用者 制定的 '.Sh' 小節, 例如, 這樣 設 小節:

                   .Sh PAGE STRUCTURE DOMAIN

  qM Paragraphs and Line Spacing.
     .Pp     '.Pp' 把 段落命令 放在 所需的位置, 可以 產生 一茠臟. 在 '.Sh' 或
             '.Ss' 宏 後 不需n 這 宏, '.Bl' 宏 的 前 也不需n. ( '.Bl'
             聲明了 垂直方向 的 距離, 除非 給出 -compact 標誌).

  O Keeps
     目前 只實現了 對單詞的 保持 能力. 這荍 有 '.Bk' (開始保持 begin-keep) 和
     '.Ek' (結束保持 end-keep ) .  '.Bk' 宏 的 唯一 參數是 -words, 用於 防止
     在 選項語句 的 中間 斷行. 在 make 命令行參數的 例子裏 (參見 WI
     What's in a name), keep 宏防止 nroff 把 標誌 和 參數 分成 兩行.  (事實上
     可以 用 選項宏 防止 此類 事情, 但 當我 決定 在 troff 中 作為 基本選項,
     強制 右邊界對齊 時, 它 在 稀疏行裏 展開的 很糟糕.  使用 保持宏 時 需n
     多做點事, 增加 一 -line 選項 ) .

  M示
     有 內媄型 的 顯示, 一 快速的單行縮進顯示 '.D1', 快速的單行鴗暩膆
     '.Dl', 鴗撊, 填充塊, 和由 '.Bd' (begin-display) 顯示開始 和 '.Ed' (end-
     display) 顯示結束 宏對 組成的 不規則塊.

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

                  -ldghfstru

            上惇O這樣產生的: .Dl -ldghfstru.

     .Dl    (D-ell) 顯示 一行 縮進的  literal.  '.Dl' 示例宏 已經 遍布 這篇
            文件. 它 允許 縮進 (顯示) 一行 文字.  其 預設字型 設為 定寬 (鴗),
            它 可以 被 其他宏 分析 和 識別.  然而 不能 被 其他宏 調用.

                  % ls -ldg /usr/local/bin

            上惇O這樣產生的 .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茼r符 寬, 然而 檔案中 出現的
                              任何 troff/-mdoc 命令 都將 被處理.
            -offset string    如果 -offset 指定為 下 字符串 之一, 這些 字符串
                              解釋為 對 以後的 正文塊的 縮進層次.

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

     .Ed    End-display.  顯示結束.

  r Font Modes
     現有 太宏 用於 改變 手冊隍 文字外觀:

     .Em    文字 可以 用 '.Em' 宏 加咿帢j調. 常用的 強調字型 是 斜體 (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    字型模式結束.

  OMC 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

     產生:
               +o   Bullet one goes here.
               +o   Bullet two here.

     -tag
     -diag
     -hang
     -ohang
     -inset
     這些 列表類型 收集 '.It' 宏 指定的 參數, 並且 創建 一 標簽, 它 可能會
     J inset 後悸 文字中, a (hanged) 顯示在 後悸 文字前, e
     (overhanged) 顯示在 更高 位置, 並且 不能 縮進 或 O 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.

     下惇O 產生 這茖狺l 的 源文本:

           .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使 比例
                         調整正常, 字母 'n' 必不可少

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

           -width "int mkfifo"
                         同樣, 設置 寬度為 所給串的 長度.

     如果 沒有 為 標記列表類型 指定 寬度, 第一次 調用 '.It' 的 時, 格式化軟體
     試圖 決定 適當的寬度. 如果 '.It' 的 第一 參數 是 可調用宏, 就 使用 這-
     荍貌 預設寬度, 就像 把 宏名 當做寬度.  可是 如果 列表中 的 其他表項 得到
     另一 可調用宏, 則 認為 它是 新的, 嵌套的 列表.

wwq 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         |         |

    `N: 那 名為 'q' 的 串 應該 寫成 '\*q', 因為 它 只有 一茼r符.

E DIAGNOSTICS
     -mdoc 的 除錯系統 比較 有, 但是 可以 幫助你 檢測出 微妙的 錯誤, 例如
     參數名 和 內部寄存器 或 宏名 沖突. (是什麼?) 寄存器 是 troff 的
     算術存儲類, 用 一到二茼r符 命名.  -mdoc 對 troff 和 ditroff 而言, 所有
     -mdoc 的 內部寄存器 由 兩茼r符 組成, 格式是 <大寫字母> <小寫字母> 如
     'Ar', <小寫字母> <大寫字母> 如 'aR' 或 <字母> <數字> 如 'C1'.  作為
     亂上加亂, troff 有 它 自己的 內部寄存器, 由 兩 小寫字母 組成, 或者 是
     一蚋I 加上 一茼r母, 或者 是 轉義字符 (meta-character) 和 字符. 已經
     介紹過的 示例中 展示過 怎樣用 轉義序列 '\&' 防止 解釋宏. 這辦法 同樣
     適用於 內部寄存器名.

     如果 未經轉義的 寄存器名 出現在 宏請求的 參數列表 中, 其 後果 不可預測.
     一般說來, 如果 大段的文字 沒有 出現在 該出現的 地方, 或者 短句, 如標簽,
     消失了, 多半是 這茼a方 誤解了 參數列表中的 參數類型.  既然 你的母親 都
     沒打算 讓你 記住 那些 亂七八糟的 東西, 那就 用 一種辦法 來 找出 參數 是否
     有效: '.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
                   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

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

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

           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

     參數 '\&aC' 表現出 同樣的 長度2, 這是 因為 '\&' 序列的 長度 為零, 但是
     不存在 叫做 '\&aC' 的 寄存器, 因此 它的類型 是 字符串.

     其他 診斷內容 是 使用報告等, 能夠 自我解釋的.

GROFF, TROFF AND NROFF

     The -mdoc 宏包 不需n 和 groff 的 相容模式.

     為了 便於 在線閱讀, 這荍誑] 阻止了 分, 黃Y, 飧} 之類 常常在 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/*    一些 手冊 的 例子

t SEE ALSO
     man(1), troff(1), mdoc(7)

BUGS

     仍然 沒有 解決 在 標誌參數中的 連字符, 在 yz DESCRIPTION 小節 偶爾 會
     出點麻煩 (在 連字符處 斷行).

     文件中 沒有 聲明 預定義串.

     還沒有 把 3f 小節 加進 頭例程 (header routine) 中.

     '.Nm' 字型 不應當在 NAME 小節 中 改變.

     應該 檢查 '.Fn' 防止 行 太短 的 時 斷行.  偶然 它會 斷開 反括弧, 而
     有時 如果 某行 已滿時, 看上去 會 很可笑.

     當 使用 nroff 格式化 文件 時, 防止 黃Y和飧} (不是 初始的 頭和腳) 斷開 的
     方法 有可能 偶爾 在 隍漫陶 產生 一 不可見的 部分填滿的 行 (空行).

     列表和顯示宏不做任何保存, 顯然它應該做的.

[]
    } <xuming@users.sourceforge.net>

[]
     2003/05/13

mLinuxanhttp://cmpp.linuxforum.net