9.4　编写手册页

如果正在编写一个新命令作为整个开发任务的一部分，你应该为其创建手册页。你可能已注意到，大多数手册页的排版格式都很相似，它们基本上都由以下几部分组成：

❑　Header（标题）

❑　Name（名称）

❑　Synopsis（语法格式）

❑　Description（说明）

❑　Options（选项）

❑　Files（相关文件）

❑　See also（其他参考）

❑　Bugs（已知漏洞）

你可以在手册页中省去无关部分。Linux的手册页还经常会在结尾出现一个Author（开发者）部分。

UNIX的手册页是通过工具nroff排版的，在大多数Linux系统中，用于完成相同功能的工具为groff，它是由GNU项目开发的。这两个工具都是在早期的排版工具roff或run-off的基础上开发的。nroff或groff命令的输入都是纯文本，只是乍看起来，它们的语法都显得非常晦涩难懂。但无需紧张，在UNIX编程中，编写新程序的一种最简单的方法就是以现有的程序作为起点，并对其进行修改，编写手册页也是一样。

对groff（或nroff）命令所使用的各种选项、命令和宏进行详细说明超出了本书讨论的范围。我们在这里只提供一个简单的模板，读者可以借鉴并写出自己的手册页。

下面是一个用于myapp应用程序的简单的手册页的源代码，它位于文件myapp.1中：

正如你所看到的，宏通过在一行开头的小数点（.）引入，并且一般采用缩写形式。第一行结尾的数字1表示这个命令出现在手册页的哪个部分。因为命令出现在手册页的第一部分，所以这里就是我们放置新应用程序说明的位置。

你可以通过修改这个样本或参考其他命令的手册页源代码来生成自己的手册页。你可能还需要看一下Linux的手册页mini-HowTo，它由Jens Schweikhardt编写，并作为Linux文档项目的一部分收录在http://www.tldp.org/中。

现在已经有了手册页的源代码，你可以用groff命令来处理它。groff命令通常产生ASCII文本（-Tascii）或PostScript（-Tps）。你可以用选项-man来告诉groff命令生成手册页，这会让groff加载专用的手册页宏定义：

它给出如下的输出结果：

现在你已测试了手册页，下一步就需要安装它。显示手册页的man命令通过环境变量MANPATH来搜索手册页。你可以将新的手册页放置到一个本地手册页目录中，或者将其直接放到系统目录/usr/man/man1中。

当用户第一次要求阅读这个手册页时，man命令将自动对其进行排版并显示排版结果。有些版本的man命令还可以自动生成并保存一份预排版（还有可能经过压缩）的ASCII文本版本的手册页，来加速对同一页面的后续访问请求的处理。