man 手册文件说明

来源：互联网发布：js监听软键盘弹出收起编辑：程序博客网时间：2024/05/29 06:49

原作者:laomai 主页:http://blog.csdn.net/laomai 本人仅做出排版修改

一、man文件简述

1、man文件的存放位置

man文件一般应放在/usr/share/man/的对应子目录下，子目录名的形式为manN。其中N是数字1-9。这个数字也就是man中的section.各section的作用如下节号叙述1用户命令(Commands)2系统调用(System calls)3库函数(Library calls)4设备文件 (Specical Files found in /dev)5文件格式 (File formats and conventiions)6游戏(Games)7帮助手册(Macro packages and conventions)8系统管理 (System)9内核 (kernel routines)

$ man 7 man 可以查到各section的具体含义。
在我的as3机器上， less命令的man文件路径为/usr/share/man/man1/less.1.gz，fork系统调用的man文件路径为/usr/share/man/man1/fork.2.gz，write有两个man文件，分别为 /usr/share/man/man1/write.1.gz和/usr/share/man/man1/write.2.gz

2、命名风格

由上面几个例子可以看出，man文件的名字为 <name>.<section>.gz
name就是用户执行man命令时输入的name参数，section为节号。

二、man文件格式

man文件本质上是一个roff格式的文件，有点象 html，只是标签的写法不同而已。
可以用以下几个命令看到完整的roff文件格式说明

 $info groff $man 7 groff $man 7 man $man 7 groff_man $man troff

下面列出几个本文中用到的常用标签.注意：所有的标签必须写在行首，前面不能有任何字符(包括空格和tab)。

注释:
- 标签: ./"
- 作用: 在行首的注释

标签: /"
作用:在行中的注释，即写在语句后面的注释

各级标题:
- 标签: .TH
- 格式: .TH title section [date] [source] [manual]
- 说明：.TH建立文章的标题,相当于html里的<h1>标签。
  每个 man 手册页，必须以一个 .TH 开始。manual 手册的标题，将显示在页眉的中部。当一个手册文件有多个man page时，每个man page的manual是不一样的。
  - title 是指手册页的标题名称，如 ls、mount 等。它也是用man命令查询时的名字。
  - section 是指 man 手册页中 1~8 的分类代码，此参数还能再跟一个字符串，如写成 1.1，表示 section 1.1，即第一部分中的第一小部分。title和section将显示在页眉的两侧和页脚的右侧。
  - source 表示工具的来源。会显示在页脚的左方
  - date一般为手册页编写的时间。会显示在页脚的中部。

标签: .SH
格式: .SH [text for heading]
说明：.SH 建立一个一级标题，类似于html里的<h2>。样式为:左对齐,宽体。
常见的.SH文字包括NAME手册页名称SYNOPSIS语法DESCRIPITION描述RETURN VALUE返回值EXIT STATUS命令返回码ERROR HANDLING错误处理ERRORS错误代码OPTIONS选项USAGE用法EXAMPLES示例FILES相关文件ENVIRONMENT相关环境变量DIAGNOSTICS诊断SECURITY安全性CONFORMING TO兼容性NOTES备注BUGSBugAUTHOR作者SEE ALSO 参阅

标签: .SS
格式: .SS [text for heading]
说明：.SS 建立一个二级标题，类似于html里的<h3>。样式为:右对齐,宽体。

段落设置
- 标签: .TP
- 格式: .TP[xn]
- 说明：.TP标签下的第2行开始缩进x个字符(在第1行超过x字符的前提下).字符的单位是n.如果第一行的字符数不超过x，则两行合为一行。这个功能有点象word的悬挂缩进。比如
```
 .TP 2n first                  second
```
  输出为：
  first
  second
  注意第二行前面有两个空格。而
```
 .TP 5n first                  second   
```
  输出为：
  first second
  这次只输出一行。
字体设置
- 标签:.B .B设置文字的字体为粗体(bold face),类似于html里的<b>。
- 标签:.I .I设置文字的字体为斜体(italic),类似于html里的<I>。
- 标签:.RB 这个相当于.R（罗马字体）与.B的组合，将文字交替的以罗马字体和粗体显示。.RI与之类似。
- .sp 空行。相当于html里的</p>
转义字符
- .为/&.
- -为/-

三、man文件制作示例

建立roff格式的文件

vi hello.1./" author : laomai.TH Hello 1 "2008-4-2" "Linux" "Hello Maunal"        /"  注意"2008-4-2"会被显示在                                                                                    /"  文件最后一行（页脚）的中部，                                                     /"  "GNU"在最后一行的行首                                                         /"  "GNU tools"在第一行（页眉）的中部.SH Name                                            hello /- GNU hello                          /"  - 必须用 /- 转义.SH SYNOPSIS.B hello.RB [/fB/-help/fR]                          /".RB为罗马字体+粗体交替显示.RB [/-a].sp                                         /" 空行.SH DESCRIPTION this is an example of man page.                .sp /&.is at begin of a line.                   /" 行首的.要用/&.转义   .TP                                          /fI italic word! /fR                        .sp.sp.SH AUTHOR.TP 3      laomai                         http://blog.csdn.net/laomai

测试显示效果
```
$ groff -Tascii -man hello.1
```
如果效果可以，则生成帮助文件
```
gzip hello.1
```
将帮助文件拷贝到合适位置
```
cp hello.1.gz /usr/share/man/man1
```
查看最终效果
```
man hello
```

四、致谢：

本文在以下资料的基础上修改和编辑而成
参考资料1: 制作自己的man手册
http://linux.chinaunix.net/bbs/viewthread.php?tid=834378&extra=&page=1
作者: mq110

参考资料2:Groff 宏包
http://blog.chinaunix.net/u1/37261/showart.php?id=488355
作者:nico