因为最近要搭建一个项目框架,所以这段时间都在研究一些相关的技术。比如怎么安排项目目录、怎么选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 |
|
使用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 |
|
-man告诉groff使用预定义好的man手册宏(即定义好的针对man手册的规则)集合,具体的groff
的使用方法自己去man
一下吧。
可以看到打印出了和我们直接使用man
命令相同的内容
1 |
|
1.2 help2man
那么我们想要自制一个man手册又要学一种文本格式了吗?不用!做为一个懒惰的程序员,可以直接用GNU为我们准备好的help2man
命令。使用这个命令可以给你的程序生成一个man手册,但是作为前提,你的程序必须提供两个选项:”–help“和”–version“。事实上,help2man
就是使用这两个选项来生成man手册的。
详细的内容以及对”–help“和”–version“的要求去看GNU官网吧: https://www.gnu.org/software/help2man/ 。我懒得复制粘贴了:)。
简单的用法如下:
1 |
|
或者想在Makefile里使用,automake提供了$(HELP2MAN)宏:
1 |
|
3 安装man文件
通过help2man
或者傻乎乎地自己写,我们得到了一个man手册文件。我们可以像1.1节里面提到的一样,直接对man文件使用groff
或者man
命令查看。但是要怎么样才能够达到像man ls
这样直接对程序使用获得使用手册的效果呢。
3.1 man手册安装位置
man手册都被安装到哪里了呢?你可以查看GNU hello项目中的Makefile文件,看它是怎么处理的,或者直接使用man
命令”-w“选项
1 |
|
这个/usr/share/man/
目录下保存的就是所有man手册了。
1 |
|
cs、zh_CN、zh_TW之类的好理解,就是不同的语言。下面解释一下man1~man8是什么意思。
在man里,将不同类型的手册进行了分类,当man程序去查找手册时,会查找对应类别的目录。由1~8:
1 |
|
按照分类GNU hello程序属于1类,因此man手册命名为hello.1。安装到/usr/share/man/man1
或者/usr/local/share/man/man1
目录下。接着就可以使用man
命令查看手册了。
扩展(Texinfo)
在man ./hello.1
最后一节中有这样一段话:
1 |
|
它让我们使用info
命令查看Texinfo手册,这又是什么东西呢?我查了一番资料之后发现,原来Texinfo是GNU提出的一种新的标准手册格式,这种格式支持超链接,不过并没有多少人使用它。