man pages创建

因为最近要搭建一个项目框架,所以这段时间都在研究一些相关的技术。比如怎么安排项目目录、怎么选LICENSE、怎么用Makefile搞构建啊等等。今天就轻松一下,来看看man手册这个东西。看要怎么给自己的程序搞一个man手册,然后怎用Makefile安装上去。

1 概述

当我们在使用类unix系统遇到一个新的命令的时候,我们想要知道这个命令是用来干嘛的,支持什么选项,我们通常有两种做法:使用--help选项或者使用man命令(扩展:info命令)。使用--help选项时,通常是由这个命令打印出一串帮助信息;使用man命令时,会去特定目录下寻找对应的man文件。现在我们想要做的就是为自己的程序创建一个man文件,并且安装到特定目录下。

1.1 troff

在添加一个man文件之前,首先要了解一下man文件是如何编排的。以GNU hello项目下的man为例,文件为hello.1:

1
2
$ file hello.1
hello.1: troff or preprocessor input, ASCII text

使用file命令查看hello.1,发现其为ascii text文件,但是写着是troff或者预处理输入。

这个troff是什么呢?

它其实源自一个古老的排版程序,期间经过多次变化,历史比较复杂,有兴趣的小伙伴可以去wiki看看。它本质上是一个排版程序,但是你可以把它看作一种文本格式(但其实不是),类似于markdown。在编写可被troff解析的文件时,也可以使用.SH .B .TP等字符串来定义文本格式,这类似于markdown的各种标签。

.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.46.4.
.TH HELLO "1" "November 2014" "hello 2.10" "User Commands"
.SH NAME
hello - friendly greeting program
.SH SYNOPSIS
.B hello
[\fI\,OPTION\/\fR]...
.SH DESCRIPTION
Print a friendly, customizable greeting.

GNU重写了一个GNU troff(Groff),但是其本质都是一个排版程序。使用groff指令来看看排版后的hello.1文件:

1
$ groff -Tascii -man hello.1 | more

-man告诉groff使用预定义好的man手册宏(即定义好的针对man手册的规则)集合,具体的groff的使用方法自己去man一下吧。

可以看到打印出了和我们直接使用man命令相同的内容

1
$ man ./hello.1

1.2 help2man

那么我们想要自制一个man手册又要学一种文本格式了吗?不用!做为一个懒惰的程序员,可以直接用GNU为我们准备好的help2man命令。使用这个命令可以给你的程序生成一个man手册,但是作为前提,你的程序必须提供两个选项:”–help“和”–version“。事实上,help2man就是使用这两个选项来生成man手册的。

详细的内容以及对”–help“和”–version“的要求去看GNU官网吧: https://www.gnu.org/software/help2man/ 。我懒得复制粘贴了:)。

简单的用法如下:

1
$ help2man ./hello -o hello.1

或者想在Makefile里使用,automake提供了$(HELP2MAN)宏:

1
2
3
4
hello.1: hello
	$(HELP2MAN) --include=$(top_srcdir)/man/hello.x $(top_builddir)/hello -o $@-t
	chmod a=r $@-t
	mv -f $@-t $@

3 安装man文件

通过help2man或者傻乎乎地自己写,我们得到了一个man手册文件。我们可以像1.1节里面提到的一样,直接对man文件使用groff或者man命令查看。但是要怎么样才能够达到像man ls这样直接对程序使用获得使用手册的效果呢。

3.1 man手册安装位置

man手册都被安装到哪里了呢?你可以查看GNU hello项目中的Makefile文件,看它是怎么处理的,或者直接使用man命令”-w“选项

1
2
$ man -w ls
/usr/share/man/man1/ls.1.gz

这个/usr/share/man/目录下保存的就是所有man手册了。

1
$ tree -d /usr/share/man

cs、zh_CN、zh_TW之类的好理解,就是不同的语言。下面解释一下man1~man8是什么意思。

在man里,将不同类型的手册进行了分类,当man程序去查找手册时,会查找对应类别的目录。由1~8:

1
2
3
4
5
6
7
8
9
   1   Executable programs or shell commands
   2   System calls (functions provided by the kernel)
   3   Library calls (functions within program libraries)
   4   Special files (usually found in /dev)
   5   File formats and conventions eg /etc/passwd
   6   Games
   7   Miscellaneous (including macro packages and conventions), e.g. man(7), groff(7)
   8   System administration commands (usually only for root)
   9   Kernel routines [Non standard] 详细信息可以man man。

按照分类GNU hello程序属于1类,因此man手册命名为hello.1。安装到/usr/share/man/man1或者/usr/local/share/man/man1目录下。接着就可以使用man命令查看手册了。

扩展(Texinfo)

man ./hello.1最后一节中有这样一段话:

1
2
3
4
5
6
SEE ALSO
       The full documentation for hello is maintained as a Texinfo manual.  If the info and hello programs are properly installed at your site, the command

              info hello

       should give you access to the complete manual.

它让我们使用info命令查看Texinfo手册,这又是什么东西呢?我查了一番资料之后发现,原来Texinfo是GNU提出的一种新的标准手册格式,这种格式支持超链接,不过并没有多少人使用它。