使用 groff 編寫 man 手冊頁

groff 是大多數 Unix 系統上所提供的流行的文本格式化工具 nroff/troff 的 GNU 版本。它一般用於編寫手冊頁，即命令、編程介面等的在線文檔。在本文中，我們將給你展示如何使用 groff 編寫你自己的 man 手冊頁。

在 Unix 系統上最初有兩個文本處理系統：troff 和 nroff，它們是由貝爾實驗室為初始的 Unix 所開發的（事實上，開發 Unix 系統的部分原因就是為了支持這樣的一個文本處理系統）。這個文本處理器的第一個版本被稱作 roff（意為 「runoff」——徑流）；稍後出現了 troff，在那時用於為特定的 排字機 Typesetter 生成輸出。nroff 是更晚一些的版本，它成為了各種 Unix 系統的標準文本處理器。groff 是 nroff 和 troff 的 GNU 實現，用在 Linux 系統上。它包括了幾個擴展功能和一些列印設備的驅動程序。

groff 能夠生成文檔、文章和書籍，很多時候它就像是其它的文本格式化系統（如 TeX）的血管一樣。然而，groff（以及原來的 nroff）有一個固有的功能是 TeX 及其變體所缺乏的：生成普通 ASCII 輸出。其它的系統在生成列印的文檔方面做得很好，而 groff 卻能夠生成可以在線瀏覽的普通 ASCII（甚至可以在最簡單的印表機上直接以普通文本列印）。如果要生成在線瀏覽的文檔以及列印的表單，groff 也許是你所需要的（雖然也有替代品，如 Texinfo、Lametex 等等）。

groff 還有一個好處是它比 TeX 小很多；它所需要的支持文件和可執行程序甚至比最小化的 TeX 版本都少。

groff 一個特定的用途是用于格式化 Unix 的 man 手冊頁。如果你是一個 Unix 程序員，你肯定需要編寫和生成各種 man 手冊頁。在本文中，我們將通過編寫一個簡短的 man 手冊頁來介紹 groff 的使用。

像 TeX 一樣，groff 使用特定的文本格式化語言來描述如何處理文本。這種語言比 TeX 之類的系統更加神秘一些，但是更加簡潔。此外，groff 在基本的格式化器之上提供了幾個宏軟體包；這些宏軟體包是為一些特定類型的文檔所定製的。舉個例子， mgs 宏對於寫作文章或論文很適合，而 man 宏可用於 man 手冊頁。

編寫 man 手冊頁

用 groff 編寫 man 手冊頁十分簡單。要讓你的 man 手冊頁看起來和其它的一樣，你需要從源頭上遵循幾個慣例，如下所示。在這個例子中，我們將為一個虛構的命令 coffee 編寫 man 手冊頁，它用於以各種方式控制你的聯網咖啡機。

使用任意文本編輯器，輸入如下代碼，並保存為 coffee.man。不要輸入每行的行號，它們僅用於本文中的說明。

.TH COFFEE 1 "23 March 94"
.SH NAME
coffee - Control remote coffee machine
.SH SYNOPSIS
fBcoffeefP [ -h | -b ] [ -t fItypefP ]
fIamountfP
.SH DESCRIPTION
fBcoffeefP queues a request to the remote
coffee machine at the device fB/dev/cf0fR.
The required fIamountfP argument specifies
the number of cups, generally between 0 and
12 on ISO standard coffee machines.
.SS Options
.TP
fB-hfP
Brew hot coffee. Cold is the default.
.TP
fB-bfP
Burn coffee. Especially useful when executing
fBcoffeefP on behalf of your boss.
.TP
fB-t fItypefR
Specify the type of coffee to brew, where
fItypefP is one of fBcolumbianfP,
fBregularfP, or fBdecaffP.
.SH FILES
.TP
fC/dev/cf0fR
The remote coffee machine device
.SH "SEE ALSO"
milk(5), sugar(5)
.SH BUGS
May require human intervention if coffee
supply is exhausted.

清單 1：示例 man 手冊頁源文件

不要讓這些晦澀的代碼嚇壞了你。字元串序列 fB、fI 和 fR 分別用來改變字體為粗體、斜體和正體（羅馬字體）。fP 設置字體為前一個選擇的字體。

其它的 groff 請求 request 以點（.）開頭出現在行首。第 1 行中，我們看到的 .TH 請求用於設置該 man 手冊頁的標題為 COFFEE、man 的部分為 1、以及該 man 手冊頁的最新版本的日期。（說明，man 手冊的第 1 部分用於用戶命令、第 2 部分用於系統調用等等。使用 man man 命令了解各個部分）。

在第 2 行，.SH 請求用於標記一個 節 section 的開始，並給該節名稱為 NAME。注意，大部分的 Unix man 手冊頁依次使用 NAME、 SYNOPSIS、DESCRIPTION、FILES、SEE ALSO、NOTES、AUTHOR 和 BUGS 等節，個別情況下也需要一些額外的可選節。這只是編寫 man 手冊頁的慣例，並不強制所有軟體都如此。

第 3 行給出命令的名稱，並在一個橫線（-）後給出簡短描述。在 NAME 節使用這個格式以便你的 man 手冊頁可以加到 whatis 資料庫中——它可以用於 man -k 或 apropos 命令。

第 4-6 行我們給出了 coffee 命令格式的大綱。注意，斜體 fI...fP 用於表示命令行的參數，可選參數用方括弧擴起來。

第 7-12 行給出了該命令的摘要介紹。粗體通常用於表示程序或文件的名稱。

在 13 行，使用 .SS 開始了一個名為 Options 的子節。

接著第 14-25 行是選項列表，會使用參數列表樣式表示。參數列表中的每一項以 .TP 請求來標記；.TP 後的行是參數，再之後是該項的文本。例如，第 14-16 行：

.TP
fB-hP
Brew hot coffee. Cold is the default.

將會顯示如下：

-h     Brew hot coffee. Cold is the default.

第 26-29 行創建該 man 手冊頁的 FILES 節，它用於描述該命令可能使用的文件。可以使用 .TP 請求來表示文件列表。

第 30-31 行，給出了 SEE ALSO 節，它提供了其它可以參考的 man 手冊頁。注意，第 30 行的 .SH 請求中 "SEE ALSO" 使用括弧擴起來，這是因為 .SH 使用第一個空格來分隔該節的標題。任何超過一個單詞的標題都需要使用引號擴起來成為一個單一參數。

最後，第 32-34 行，是 BUGS 節。

格式化和安裝 man 手冊頁

為了在你的屏幕上查看這個手冊頁格式化的樣式，你可以使用如下命令：

$ groff -Tascii -man coffee.man | more

-Tascii 選項告訴 groff 生成普通 ASCII 輸出；-man 告訴 groff 使用 man 手冊頁宏集合。如果一切正常，這個 man 手冊頁顯示應該如下。

COFFEE(1)                                               COFFEE(1)
NAME
       coffee - Control remote coffee machine
SYNOPSIS
       coffee [ -h | -b ] [ -t type ] amount
DESCRIPTION
       coffee  queues  a  request to the remote coffee machine at
       the device /dev/cf0. The required amount  argument  speci-
       fies the number of cups, generally between 0 and 12 on ISO
       standard coffee machines.
   Options
       -h     Brew hot coffee. Cold is the default.
       -b     Burn coffee. Especially useful when executing  cof-
              fee on behalf of your boss.
       -t type
              Specify  the  type of coffee to brew, where type is
              one of columbian, regular, or decaf.
FILES
       /dev/cf0
              The remote coffee machine device
SEE ALSO
       milk(5), sugar(5)
BUGS
       May  require  human  intervention  if  coffee  supply   is
       exhausted.

格式化的 man 手冊頁

如之前提到過的，groff 能夠生成其它類型的輸出。使用 -Tps 選項替代 -Tascii 將會生成 PostScript 輸出，你可以將其保存為文件，用 GhostView 查看，或用一個 PostScript 印表機列印出來。-Tdvi 會生成設備無關的 .dvi 輸出，類似於 TeX 的輸出。

如果你希望讓別人在你的系統上也可以查看這個 man 手冊頁，你需要安裝這個 groff 源文件到其它用戶的 %MANPATH 目錄裡面。標準的 man 手冊頁放在 /usr/man。第一部分的 man 手冊頁應該放在 /usr/man/man1 下，因此，使用命令：

$ cp coffee.man /usr/man/man1/coffee.1

這將安裝該 man 手冊頁到 /usr/man 中供所有人使用（注意使用 .1 擴展名而不是 .man）。當接下來執行 man coffee 命令時，該 man 手冊頁會被自動重新格式化，並且可查看的文本會被保存到 /usr/man/cat1/coffee.1.Z 中。

如果你不能直接複製 man 手冊頁的源文件到 /usr/man（比如說你不是系統管理員），你可創建你自己的 man 手冊頁目錄樹，並將其加入到你的 %MANPATH。%MANPATH 環境變數的格式同 %PATH 一樣，舉個例子，要添加目錄 /home/mdw/man 到 %MANPATH ，只需要：

$ export MANPATH=/home/mdw/man:$MANPATH

groff 和 man 手冊頁宏還有許多其它的選項和格式化命令。找到它們的最好辦法是查看 /usr/lib/groff 中的文件； tmac 目錄包含了宏文件，自身通常會包含其所提供的命令的文檔。要讓 groff 使用特定的宏集合，只需要使用 -m macro （或 -macro） 選項。例如，要使用 mgs 宏，使用命令：

groff -Tascii -mgs files...

groff 的 man 手冊頁對這個選項描述了更多細節。

不幸的是，隨同 groff 提供的宏集合沒有完善的文檔。第 7 部分的 man 手冊頁提供了一些，例如，man 7 groff_mm 會給你 mm 宏集合的信息。然而，該文檔通常只覆蓋了在 groff 實現中不同和新功能，而假設你已經了解過原來的 nroff/troff 宏集合（稱作 DWB：the Documentor's Work Bench）。最佳的信息來源或許是一本覆蓋了那些經典宏集合細節的書。要了解更多的編寫 man 手冊頁的信息，你可以看看 man 手冊頁源文件（/usr/man 中），並通過它們來比較源文件的輸出。

這篇文章是《Running Linux》 中的一章，由 Matt Welsh 和 Lar Kaufman 著，奧萊理出版（ISBN 1-56592-100-3）。在本書中，還包括了 Linux 下使用的各種文本格式化系統的教程。這期的《Linux Journal》中的內容及《Running Linux》應該可以給你提供在 Linux 上使用各種文本工具的良好開端。

祝好，撰寫快樂！

Matt Welsh （mdw@cs.cornell.edu）是康奈爾大學的一名學生和系統程序員，在機器人和視覺實驗室從事於時時機器視覺研究。

（題圖：wikimedia.org）

via: http://www.linuxjournal.com/article/1158

作者：Matt Welsh 譯者：wxy 校對：wxy

本文由 LCTT 原創編譯，Linux中國 榮譽推出

本文轉載來自 Linux 中國: https://github.com/Linux-CN/archive