2017-11-18
话说，在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出现了，这个工具很好用，但是有几个小问题：
- 公司开发机器中我没有成功把命令示例文档下载下来。
- 文档布局稍繁琐。
- 命令示例文档与工具强绑定。
所以，这里造一个名为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 命令的实现
- 获取命令行参数，得到用户要查询的命令
- 得到locale
- 从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 .