原作者: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>.gzname就是用户执行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 备注 BUGS Bug AUTHOR 作者 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