如何 – Linux / UNIX 创建手册页
几乎所有的 UNIX 类操作系统都预装了手册页。
Troff 和 Groff Macro
troff 是 AT&T 为 Unix 操作系统开发的文档处理系统。troff 排版系统包括一组称为宏的命令，这些命令在开始处理文档之前运行。这些宏包括设置页眉和页脚、定义新命令，以及通常影响输出的格式。在 Linux 下，所有新的手册页都应使用 groff an.tmac 包进行标记。groff (GNU troff) 软件是一个排版包，它读取混合了格式化命令的纯文本并生成格式化的输出。
关于手册页布局的简要说明
所有手册页都遵循通用的布局，建议您也对您的手册页使用相同的布局：
NAME
The name of the command or function, followed by a one-line description of what it does.
SYNOPSIS
In the case of a command, you get a formal description of how to run it and what command line options it takes.
DESCRIPTION
A textual description of the functioning of the command or function.
EXAMPLES
Some examples of common usage.
SEE ALSO
A list of related commands or functions.
BUGS
List known bugs.
AUTHOR
Specify your contact information.
COPYRIGHT
Specify your copyright information.
您可以添加其他一些部分，例如退出状态、环境、文件和历史记录等。下表显示了手册的章节编号以及它们包含的页面类型。
手册页部分
该手册通常分为 8 个编号部分，在 Linux 或类 UNIX 操作系统下组织如下：
| 部分 | 描述 |
|---|---|
| 1 | 可执行 shell 命令 |
| 2 | 系统调用（内核提供的函数） |
| 3 | 库调用（程序库内的函数） |
| 4 | 特殊文件（通常在 /dev 中） |
| 5 | 文件格式和约定，例如 /etc/passwd |
| 6 | 游戏 |
| 7 | 杂项（包括宏包和约定），例如 man(7)、groff(7) |
| 8 | 系统管理命令（通常仅适用于 root） |
| 9 | 内核例程[非标准] |
要查看可以与命令 man 一起使用的选项和部分信息，请输入以下命令：
man man
手册页位置
系统将其手册页存储在 /usr/share/man/ 目录中，如 about 部分所述。例如，目录 /usr/share/man/man1 存储用户 shell 命令的手册页。您可以通过键入以下命令来查看它：
cd /usr/share/man/man1 ls -l zcat ls.1.gz
自定义手册页位置
建议你将自己的 man 页面存放在 /usr/local/man 目录中。你可以在 /etc/man.config 文件中设置 man 搜索路径：
MANPATH /usr/man MANPATH /usr/share/man MANPATH /usr/local/man MANPATH /usr/local/share/man MANPATH /usr/X11R6/man
有关如何确定手册页搜索路径的更多详细信息，请参阅 manpath 手册页：
man manpath
如何创建自己的手册页？
groff (GNU Troff) 软件是一个排版包，它读取混合了格式化命令的纯文本并生成格式化的输出（如手册页）。它附带各种宏包（如 man 和 mandoc）来创建手册页。创建一个文件，如下所示
$ vi nuseradd
.\" Manpage for nuseradd. .\" Contact vivek@example.net.in to correct errors or typos. .TH man 8 "06 May 2010" "1.0" "nuseradd man page" .SH NAME nuseradd \- create a new LDAP user .SH SYNOPSIS nuseradd [USERNAME] .SH DESCRIPTION nuseradd is high level shell program for adding users to LDAP server. On Debian, administrators should usually use nuseradd.debian(8) instead. .SH OPTIONS The nuseradd does not take any options. However, you can supply username. .SH SEE ALSO useradd(8), passwd(5), nuseradd.debian(8) .SH BUGS No known bugs. .SH AUTHOR Vivek Gite (vivek@example.net.in)
保存并关闭文件。要查看手册页，请输入：
man ./nuseradd
示例输出：
图 01 手册页实际运行情况
man 7 mdoc
如何安装我的手册页？
只需输入以下命令：
cp nuseradd /usr/local/man/man8/nuseradd.1 gzip /usr/local/man/man8/nuseradd.1 man nuseradd
您也可以使用如下安装命令（推荐用于 shell 脚本）：
install -g 0 -o 0 -m 0644 nuseradd.1 /usr/local/man/man8/ gzip /usr/local/man/man8/nuseradd.1
结论
您学习了如何在 Linux 和类 Unix 系统下创建手册页。请参阅以下资源以获取更多信息：
- GNU Troff（Groff） ——一个 GNU 项目。
- 参见手册页 mdoc、groff 和 install 命令。