man2:一个快速查找命令使用示例的工具

话说,在UNIX系操作系统中(Linux、macOS、FreeBSD等),有一个man命令用于获取帮助手册。man的帮助手册是分章节的,其中最常用的是默认的第1章节中的命令手册。例如,查看grep命令的使用方法:

$ man grep
GREP(1)                     General Commands Manual                    GREP(1)

NAME
       grep, egrep, fgrep, rgrep - print lines matching a pattern

SYNOPSIS
       grep [OPTIONS] PATTERN [FILE...]
       grep [OPTIONS] [-e PATTERN]...  [-f FILE]...  [FILE...]

DESCRIPTION
       grep searches the named input FILEs for lines containing a match to the
       given PATTERN.  If no files are specified, or if the file “-” is given,
       grep  searches  standard  input.   By default, grep prints the matching
       lines.

       In addition, the variant programs egrep, fgrep and rgrep are  the  same
       as  grep -E,  grep -F,  and  grep -r, respectively.  These variants are
       deprecated, but are provided for backward compatibility.

OPTIONS
   Generic Program Information
       --help Output a usage message and exit.
// .... 省略 ....

关于 man 命令的章节区分,可以看下 Linux man命令的使用方法

man很实用,但过于“学术化”,缺乏使用示例以帮助更好地理解。 所以,tldr出现了,这个工具很好用,但是有几个小问题:

  1. 公司开发机器中我没有成功把命令示例文档下载下来。
  2. 文档布局稍繁琐。
  3. 命令示例文档与工具强绑定。

所以,这里造一个名为man2的轮子用于快速查看命令示例。

1. 实现思路

1.1 文档形式与布局

文档采用markdown编写,以.md为后缀,命令名称作为后缀,例如git.md。如果要为子命令/命令选项编写一个单独的文档,例如为git clone编写一个文档,则文档命名为git clone.md,注意两个单词之间只有一个空格。

默认支持多语言,以locale(区域)作目录划分,例如简体中文的文档放在zh_CN目录下。

如何识别使用哪个locale呢?

  • 方法1:直接用操作系统的locale
  • 方法2:通过配置文件读取
  • 方法3:优先配置文件,若为设置,则使用配置系统locale

方法3更合适。

于是,文档布局如下:

├── config.json         # 配置locale
├── en_US               # 英文文档目录
└── zh_CN               # 简体中文文档目录
    ├── convert.md
    ├── find.md
    ├── git clone.md
    ├── grep.md
    └── ls.md

然后,约定上面的文档和配置放在~/.man2-docs目录下。

1.2 man2 命令的实现

  1. 获取命令行参数,得到用户要查询的命令
  2. 得到locale
  3. 从locale对应的目录中寻找文档,找到则打印出来,否则报错

基于上面的思路,挑一个编程语言实现就行了。我这里用的Nodejs。

因为是在终端(Terminal)中输出 markdown 文档,有高亮效果自然更好。 Nodejs 中的 marked-terminal 库,可以实现高亮效果。

2. 如何使用 man2

安装man2命令:

$ npm install man2 -g

下载文档(当然,也可以用自己整理的文档):

$ git clone https://github.com/letiantian/man2-docs.git ~/.man2-docs

使用示例:

$ man2 grep

## 当前目录中查找含有 ls 的文件

    grep "ls" -r .

## 高亮命中的内容

    grep --color=auto "ls" -r .

## 高亮命中的内容,并给出行号

    grep --color=auto "ls" -n -r .

## 高亮命中的内容,并给出行号

    grep --exclude-dir={.bzr,CVS,.git,.hg,.svn,node_modules} "ls" -n -r .