man 手册规范 & troff文件使用

在Linux下有许多命令，他们都有自己的帮助文档，有一天我们自己的的程序也需要帮助类似的帮助文档的时候应该如何来编写呢 ？ 相对这方面的资料较少，这里总结下。

• man 的帮助文件位置：

存放目录：

首先是目录以及存放规范,linux文档经常放在：MANPATH环境变量指定的目录中。一般在：/usr/share/man 这个目录里面。这个目录下面结构还有定义的：

remon@debian:/usr/share/man$ ls -l total 212 drwxr-xr-x 5 root root 4096 Feb 15 15:50 cs drwxr-xr-x 6 root root 4096 Jul 26 22:25 de drwxr-xr-x 5 root root 4096 Jul 26 22:01 es drwxr-xr-x 4 root root 4096 Jul 26 22:01 fi drwxr-xr-x 7 root root 4096 Jul 26 22:25 fr drwxr-xr-x 3 root root 4096 Jul 26 22:01 gl drwxr-xr-x 5 root root 4096 Jul 26 22:01 hu drwxr-xr-x 5 root root 4096 Jul 26 22:01 id drwxr-xr-x 5 root root 4096 Feb 15 15:50 it drwxr-xr-x 5 root root 4096 Feb 15 15:50 ja drwxr-xr-x 5 root root 4096 Feb 15 15:50 ko drwxr-xr-x 2 root root 57344 Jul 26 22:34 man1 drwxr-xr-x 2 root root 4096 Jul 26 22:01 man2 drwxr-xr-x 2 root root 20480 Jul 26 22:29 man3 drwxr-xr-x 2 root root 4096 Jul 26 22:29 man4 drwxr-xr-x 2 root root 12288 Jul 27 03:01 man5 drwxr-xr-x 2 root root 4096 Jul 26 22:27 man6 drwxr-xr-x 2 root root 12288 Jul 26 22:29 man7 drwxr-xr-x 2 root root 20480 Jul 27 03:01 man8 drwxr-xr-x 5 root root 4096 Feb 15 15:50 pl drwxr-xr-x 5 root root 4096 Jul 26 22:01 pt drwxr-xr-x 5 root root 4096 Jul 26 22:01 pt_BR drwxr-xr-x 5 root root 4096 Feb 15 15:50 ru drwxr-xr-x 5 root root 4096 Feb 15 15:50 sv drwxr-xr-x 5 root root 4096 Feb 15 15:50 tr drwxr-xr-x 5 root root 4096 Feb 15 15:50 zh_CN drwxr-xr-x 5 root root 4096 Feb 15 15:50 zh_TW

man[*]这类目录表示意思。linux帮助文档，一个特别的有意思的是，按照文档表示不同类型，分领域的（也就是分类别），过会我们会说这个类别按照什么分了。还有就是类似：zh_CN pl.ISO8859-2这些。文档还分语言.地域.字符编码 。可以支持统一命令，多个语言版本的文档，并且地域可以不一样，还可以指定字符集。如：zh_TW.big5 这个意思就是：中文_台湾地区.使用big5字符集编码的文档。

文档领域区分方法（就是类别）

我们看下下面的表格：

领域	描述	说明
1	用户命令	可由任何人启动的,如env、cat、man、touch文档
2	系统调用或内核函数	即由内核提供的函数 如link、sethostname、mkdir
3	库程序	即库函数 如acosh、asctime、btree、locale
4	与设备有关的信息	即/dev目录下的特殊文件 如zero null sda
5	文件格式描述	如/etc/passwd 文件格式描述说明在这个分类下
6	游戏	游戏的帮助文件
7	其他	包括 宏命令包、惯例等如 arp、boot、regex、unix utf8
8	系统管理	只能由root启动 如fdisk、fsck、renice、rpm、yum
9	内核	用来存放内核例行程序的文档
n	新文档	可能要移到更适合的领域
o	老文档	可能会在一段期限内保留
l	本地文档	与本特定系统有关的

如果文档属于那个类型的，它就放到 MANPATH/语言_区域.字符集/man[n]目录下面。 没有区域语言，代表是en英文文档。就直接放到：MANPATH/man[n]下面,基本上大部分文档都是这个下面。

举个列子吧：

linux下面有个命令是：passwd 修改密码信息的，每个用户都可以调用，所以它会放到man1/目录下面

但是同时，/etc/passwd有个保存用户账户信息配置文件，它的格式及说明信息文档，将放到/man5目录下了。这样按照领域（以后都叫这个了，呵呵）区分，不会出现相同名称文件找错的情况了。 上面提到的：1,2,3,4,5,7,8这些类型是我们经常用到的。 如果我想知道/dev/null 设备的意思，我可以到：man4这个目录下面找了。

帮助文件格式：

刚才说了，目录存放格式，帮助文件一样有它的格式的。首先是命名格式：

[命令名称.领域]:名字就是命令、函数或文件名的名称，后面跟一个点，再跟著领域字符。如：如果passwd命令说明文档，文件名命名是：passwd.1，加上目录存放为：man1/passwd.1 ，如果对应passwd格式说明文档，它将是：man5/passwd.5 。看下下面例子：

1 [chengmo@centos5 man5]$ ls p*
2 pam.5.gz       pam_env.conf.5.gz  passwd.5.gz  png.5.gz
3 pam.conf.5.gz  pam_krb5.5.gz      pbm.5.gz     pnm.5.gz
4 pam.d.5.gz     pam_ldap.5.gz      pgm.5.gz     ppm.5.gz
5 #/usr/share/man/man5 下面所有以p开头文件，从文件里面我们就知道它对应于那些配置文件格式说明了。
6 #pam.d.5.gz就是pam.d目录结构说明  pam.5.gz是pam模块结构说明

从这个里面看，.gz结尾，看来是通过gzip压缩过的，linux系统为节省文档存储空间，自带文档都经过压缩的。只是查看时候，我们需要解压然后查看。文档内容不会改变。

再啰嗦一下：

细心朋友一定看到个问题，上面显示：man目录下面结构例子里面，除了man[n]以及语言地区目录。还有一类目录：man1,man0p,man1p,man1x 这里说明下：

加p:表示POSIX Programmer 程序说明文档

加x:表示x windows桌面程序说明文档

0p:表示POSIX Programmer 一些c的头文件库，如：tcp.h,ulimit.h等说明文档

 

• man-pages文件内容格式规范

能够快捷方便查询linux文档，除了目录规范以及命名规范外。对于文档的内容也有一个格式规范呢。

一个文本文件，又不是用word格式，基本都是ascii字符，还有什么规范？

可能朋友会这么说，是的，它确实是文本文件，编辑一个随便的txt文件，就可以是一个linux文档，如：你写了个：testhellow.sh脚本，然后你写了一段文本存为：man/man1/testhellow.1文件。这个就算一个文档了。

你通过linux索引方法，是可以找得到的。 但是：它不是一个规范的文档。

规范格式文档是：

手册页内容	描 述
NAME	程序或者命令的名称、手册节号及发布日期
SYNOPSIS	怎样调用命令，带有所有选项和参数的完整列表
DESCRIPTl0N	命令及其用法的简短小结
RETURN VALUES	程序或者库函数返回值，以及产生特定返回值的环境
EXIT STATUS	经常用来替代服TURNVALUS
OPTIONS	按字母顺序排列的选项和参数清单，如果有的话
FILES	命令使用的或者能使用的文件清单
USAGE	用程序的语言说明的简明语法，如果有的话
ENVIROMENT	命令使用的或者能使用的环境变量清单
DIAGNOSTICS	命令产生的错误信息及其解决办法的清单
NOTES	不能够归入其他任何一种类别下的所有信息
CONFORMING TO	列出程序遵循的任何标难，比如PoSIX或ISO
SEE ALSO	和命令有关的交叉索引和信息
BUGS	指出己知的bug和错误功能，以及怎样和程序的作者联系修正它们
AUTHOR	命令的作者或者维护者的名字，可能带有电子邮件地址或URL地址

规范的文档，如果有相关描述，都会包含上面这些节点类型的。我们举例说明下：

01 [chengmo@centos5 ~]$ gtbl cat.1  | gtbl | groff -Tascii -man
02 CAT(1)                           User Commands                          CAT(1)
03
04 NAME
05        cat - concatenate files and print on the standard output
06
07 SYNOPSIS
08        cat [OPTION] [FILE]...
09
10 DESCRIPTION
11        Concatenate FILE(s), or standard input, to standard output.
12 省略....
13
14 EXAMPLES
15        cat f - g
16 省略....
17
18
19 AUTHOR
20        Written by Torbjorn Granlund and Richard M. Stallman.
21
22 REPORTING BUGS
23        Report bugs to <[email protected]>.
24
25 COPYRIGHT
26        Copyright (C) 2006 Free Software Foundation, Inc.
27 省略....
28 SEE ALSO
29        The full documentation for cat is maintained as a Texinfo  manual.   If
30 省略....
31
32 cat 5.97                          March 2007                            CAT(1)

这里自己解压了一个cat.1.gz然后通过自带命令查看文档格式如上图，这些你看到用到好多命令，显示一个文档，在下一节文档查询里面我们会知道原因的。

 

这里主要说的是linux文档结构，包括目录，命名，已经文档名称，格式等。这些不是强制的，系统也不好强制检测你自己的文档是否满足。但是，你如果有自己文档想加入系统索引，按照规定去做，才会让以后管理不止混乱了。俗话说：无规律不成方圆。是这个理。呵呵，今天说的比较啰嗦，不知道有没有说清楚，这次说的比较理论的，下一节实际检索文档方面的东西。