开发Linux中的程序使用手册（即man命令输出的手册）

1.关于本文

今天我研究了下Linux下的程序使用手册，也就是在控制台中用man命令输出的手册

这个手册是用一定的格式书写的文本文档，手册的扩展名都是.1

把它保存到路径 /usr/local/man/man1/ 下，就可以通过man命令调用了

如果不保存到 /usr/local/man/man1/ ，那就需要在man命令后面的参数中写下这个手册完整的地址（如 man ./test.1）

我的环境：通过命令`man --version`，得到man命令的版本为“man, version 1.6f”

2.一个示例手册代码及显示实例

文件：tsybius.man

这个文件的制作参考了 ksh.1

.\"{{{   Title
.TH TSYBIUS 1 "December 16, 2014" "1234" "User commands"
.W"}}}
.W"{{{   NAME
.SH NAME
tsybius \- a test man
.W"}}}
.W"{{{   SYNOPSIS
.SH SYNOPSIS
\fBtsybius\fP
[ \fB\(+-abcdefg\fP \fIoption\fP ]
.W"}}}
.W"{{{   OTHER
.SH OTHER
.B abcd
.I abcd
.PP 
abcd
.TP
abcd
.SS abcd
abcd
.IP \fBthis-is-1\fP
abcd111
.IP \fBthis-is-2\fP
abcd222
.IP \fBthis-is-3\fP 
abcd333
.PP

.nr P2 \n(PD
.nr PD 0
.IP \ \ \(bu
12345
.IP \ \ \(bu
67890
.IP \ \ \(bu
09876
.IP \ \ \(bu
54321
.nr PD \m(P2

.PP
--------TS1--------
.PP

.TS
center;
lfB lfB lfB lfB lfB.
abc bcd cde def efg
fgh ghi hij jkl klm
lmn mno nop opq pqr
qrs rst stu tuv uvw
vwx wxy xyz
.TE

.PP
--------TS2--------
.PP

.TS
expend;
afB lfB lw(3i).
\-A    Aaaaa    T{
    this is the note of Aaaaa!
T}
\-B    Bbbbb    T{
    this is the note of Bbbbb!
T}
\-C    Ccccc    T{
    this is the note of Ccccc!
T}
.TE

.PP
--------TS3--------
.PP

.TS
afB ltw(2.8i).
\fIabc\fP    T{
    abcd
T}
\fIwxy\fP    T{
    wxyz
T}
.TE

.PP
--------TSX--------
.PP

abcd
.RS
1234
.br
1234
.br
12345
.RE
12345
.RS
12345
.RE
12345

.PP

.ce
[abcdefg]

.sp
[abcdefg]

.IR "HelloWorld" ,
By Tsybius 2014/12/16

.W"}}}

使用这个命令可以预览这段手册代码的效果：

groff -Tascii -man tsybius.man

但是这个命令并不等于man命令，它只是把预览效果打印到控制台，并且无法解析许多man命令可以解析的代码，比如.TS-.TE块、.IR等命令。

把这个手册改名为tsybius.1，放到目录 /usr/local/man/man1/ 下，就可以用下面这个命令来显示手册了

man tsybius

显示的效果如下图：

图1（上半部分）

图2（下半部分）

3.对代码中宏的解释

代码中用到的几个宏的注释如下：

.\"  #注释
.TH  #格式，后面依次接数字、字符串、字符串、字符串，分别代表：
     #（1）数字（左上角、右上角、右下角括号内数字）；（2）"正下方文字（一般为日期）" ；
     #（3）"左下方文字"；（4）"正上方文字（User commands）"
.SH  #标题
\-   #转义字符：输出横杠
\fB文字\fP    #文字粗体显示
\fI文字\fP    #文字下划线显示
\(+- #符号±
.B   #文字粗体显示
.I   #文字下划线显示
.PP  #换行
.TP  #
.SS  #一级小标题
.IP  #二级小标题
31-41行代码段  #逐条显示文字并在前加·
47-55行代码段  #打印表格，表格居中，注意在 T{...T} 块中，不同列中间要用1个Tab而不是空格或多个Tab分隔
61-73行代码段  #打印表格，表格全屏，注意在 T{...T} 块中，不同列中间要用1个Tab而不是空格或多个Tab分隔
79-87行代码段  #打印表格，注意在 T{...T} 块中，不同列中间要用1个Tab而不是空格或多个Tab分隔
.RS  #向后缩进
.br  #换行（不改变缩进）
.RE  #向前缩进
.ce  #居中显示
.sp  #
.IR  #下划线显示后面引号内的文字，空格不加下划线

4.Makefile脚本

我们可以制作一个Makefile脚本安装或卸载上面的文档，脚本代码如下：

#功能：安装说明书test.man
#使用：1）安装后输入命令`man test`即可查看
#      2）请使用超级用户权限执行这个脚本
#作者：Tsybius 2014/12/16

#要添加的手册名
PROG=tsybius
#安装到的位置（测试）
#MANDIR=./man1
#安装到的位置
MANDIR=/usr/local/man/man1
#是否创建新目录
MKMANDIR=true
#手册文件扩展名
MANEXT=.1
#chmod语句赋予权限 如 755 644 等
MANMODE=644

all:

install.man:
    -mkdir $(MANDIR) 2> /dev/null
    cp $(PROG).man $(MANDIR)/$(PROG)$(MANEXT)
    chmod $(MANMODE) $(MANDIR)/$(PROG)$(MANEXT)

uninstall.man:
    rm -f $(MANDIR)/$(PROG)$(MANEXT)

clean:

以下是安装和卸载用的命令

make install.man
make uninstall.man

脚本第22行前的横杠，表示忽略后面命令的执行错误情况，如果不忽略，后面语句执行出错，会退出Makefile脚本

脚本第22行最后的 2> /dev/null，表示将错误输出重定向到 /dev/null，即不输出错误输出信息（2换成1，则是不输出标准输出信息）

END

转载于:https://my.oschina.net/Tsybius2014/blog/356779