Man pages 一直是 UN*x 文档的主要来源。 每当我创建一个将要长期存在的脚本时，我都会以第 1 节 man page 的形式创建文档。 这可以防止我的手机在周末 junior 系统管理员寻找我的笔记时响起。

我认识的一些人倾向于回避编写 man pages，因为他们认为使用 troff 或 groff 正确格式化 man pages 太困难了。 幸运的是，我有一种更容易完成这项工作的方法。

Marc Vertes (mvertes@free.fr) 编写了一个出色的 GNU AWK 脚本，名为 txt2man，它几乎可以在任何 UN*X 类系统上运行，并且可以将纯 ASCII 文本文件转换为正确的 man page 格式。 txt2man（当前版本 1.5.5-1）由 Fedora Project 分发，可从 EPEL 存储库获得。 作者的主页是 http://mvertes.free.fr/txt2man/。

为您的系统下载并安装正确的 txt2man 包后，您就可以开始创建 man page 了。 首先，将您的信息整理到一个 ASCII 文本文件中。 您仍然必须对文件应用特定的格式，但没有 troff/groff 那么复杂。

在命令行中，键入 txt2man -h 以查看内置文档，其中将描述要添加到文件中的内容，以便稍后正确格式化。 如何格式化文本的最佳示例实际上是显示的帮助本身。

使用命令

$ txt2man -h 2>&1 | txt2man -T 

将显示内置帮助并通过 txt2man 管道传输，以生成格式化的 man page 并使用默认寻呼机预览它。 没有 "-T" 选项的相同命令将显示 troff/groff 格式的输出本身。 如果我们将命令的输出重定向到文件

$ txt2man -h 2>&1 | txt2man > txt2man.1

并使用 gzip 压缩生成的文件

$ gzip txt2man.1

我们可以将文件视为常规 man page

$ man ./txt2man.1.gz

请注意，我为我的 man page 指定了第 1 节。 默认情况下，man 将在第 8 节中查找系统管理命令，在第 1 节中查找常规命令。

现在，我们需要做的就是将我们的新 man page 复制到我们系统的相应目录中，如 $MANPATH 环境变量中所指定，或者可能在 /etc/man.conf 中，具体取决于您的 UN*X/Linux 发行版。 在我的 RHEL5 系统上，我将用户生成的 man pages 保存在 /usr/local/man 中

$ cp ./txt2man.1.gz /usr/local/man

最后，我使用以下命令更新 whatis 数据库

# /usr/sbin/makewhatis

现在，我的 man page 可供所有用户使用。