制作自己man手册

一、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文件的名字为
    .

.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)。
     

1、注释:

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

2、各级标题:

  标签: .TH             
  格式: .TH title section [date] [source] [manual]
  说明：.TH建立文章的标题,相当于html里的

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


 标签: .SH  
 格式: .SH [text for heading]
 说明：.SH 建立一个一级标题，类似于html里的

。样式为:左对齐,宽体。
    常见的.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里的

。样式为:右对齐,宽体。
    

3、段落设置 

 标签: .TP
 格式: .TP[xn]
 说明：.TP标签下的第2行开始缩进x个字符(在第1行超过x字符的前提下).字符的单位是n.
     如果第一行的字符数不超过x，则两行合为一行。这个功能有点象word的悬挂缩进。　
 比如    
 .TP 2n
 first                 
 second       
 输出为：           
 first
   second
 注意第二行前面有两个空格。  
 
 而
 .TP 5n
 first                 
 second       
 输出为：    
 first second
 这次只输出一行。

4、字体设置 

 标签:.B 
 .B设置文字的字体为粗体(bold face),类似于html里的。
 
 标签:.I
  .I设置文字的字体为斜体(italic),类似于html里的。I
 
 标签:.RB
   这个相当于.R（罗马字体）与.B的组合，
   将文字交替的以罗马字体和粗体显示。.RI与之类似。 
  
 .sp 
 空行。相当于html里的

 

5、 转义字符

    .为/&.
 -为/-
  

三、man文件制作示例

1、建立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

2、测试显示效果

$ groff -Tascii -man hello.1   

3、如果效果可以，则生成帮助文件

gzip hello.1

4、将帮助文件拷贝到合适位置

cp hello.1.gz /usr/share/man/man1

5、查看最终效果

man hello