Simplified and community-driven man pages
2016-03-01简单介绍
今天来说说 tldr。[1] 正如标题所言， tldr 致力于提供简化的 man page。相比于详细的 man page，tldr 提供了几个常用的例子并附加相关的说明。按照官方的说法, tldr 是这样定义的：
Simplified and community-driven man pages.
之前也有一个很火的项目: the-art-of-command-line, 它的介绍是:
Master the command line, in one page
tldr 现在已经有很多大家贡献的命令，或许有些没有，或许有些不够好，这也许是一个诟病。但是不用担心，因为你完全可以自己总结， 使用并维护自己的那一份，感觉不错的也可以去官方 repo 提个 PR 分享一下。当然，这是方便使用而已，需要深入使用或者其他场景使用的， 那就使用 man 吧。
亮点所在
- 具体实现和源文件分离。类似的项目还有一个 cheat. 与 tldr 的主要区别在于它的实现和源文件是绑定的。也就是说你只能用安装它才能使用。相对的是，tldr 的主要 repo 只是专注于 markdown 文件它规定了 markdown 文件的规范和格式，方便不同的 client 解析展示。而具体的实现，不管是网页形式还是命令行的， 是由社区用户来提供的实现和源文件的解耦，不仅对于平时的维护工作是有利的，降低来用户的贡献准入门槛（只要懂 markdown 就行）， 还有利于其他有能力的用户自行编写 client 来丰富社区资源进一步推动社区的发展。
- 丰富的客户端。在 tldr 登上 HackerNews 头条，吸引来大量的目光，star 数从 2000 左右飙到了 6000 多后， 各式各样的客户端也是纷纷出来了。基本通用的流行语言已经都有相应的 client。
不足之处
下面谈谈我对它可能存在的问题的猜想：
- 由于实现和源文件分离，这意味着大部分的 client 是由社区贡献的。这就涉及到 client 的质量问题了。潜在的良莠不齐的 client 可能会影响实际用户的使用感受。另一方面，这对于源文件的格式要求制定也是需要深思熟虑的。当 tldr 主 repo 存在问题需要 client 跟进时，如何管理和推动开发者一起向同一个方向走。
- 命令偏向泛化。也就是说，可能命令多了以后，数量上说虽然是好的，但是维护管理这么多的命令也是一个重大的任务。 可能就会出现多而不精这样的现象。
我的 tldr.py
tldr.py 实际上是 tldr 的一个命令行程序，帮助你快速查看命令的常用用法，也是官方推荐的 python client。[2]
开发缘由
最开始我不知道怎么瞎逛就看到了这个，当时的 client 也不多，而原来的 python-client 的状态并不是特别好，没有测试，readme 也十分简单，也是好久都没有维护了，于是我决定就自己写一个。
特点介绍
- use local file, fast.
- support custom the output color.
- support fetch the latest tldr pages.
- support rebuild the index.
这里主要说说使用原 git repo 的特点，这个特点基本决定了 tldr.py 的主要软件设计。
较为早期，client 可能是直接发请求来或者 tldr 的 man page，虽然能保证得到的是最新的版本，但随之而来一个明显的缺陷就是——耗时间。 使用 git repo 的优点有：
- 使用 git 进行版本管理，因为它本来就是一个有效的 git repo；
- 灵活：某个命令的 man page 你认为有更好的用法，直接修改就可以；想添加自己总结的命令，也可以在对应的目录下添加；
- 更新方便，不再写其他的代码，把更新工作交给 git，一般 git pull 一下就可以；
经验总结
- issue 回复废时间。英文捉鸡的我有时候回复 issue 就是憋不出来字，所以相比写代码的时间，维护它也是很废时间的；
- 实现简单可维护的功能，不要做鸡肋的。比如在 issue#9 中，有人提出 "Support XDG base directory specification"， 我承认当时就懵圈了，因为我根本不知道这是什么玩意，了解以后，讨论了好久也想不出简单可行的办法。后来终于想出了增加环境变量的对策， 事实上不仅解决了问题，测试也好写多了。再比如说 issue#11 中关于定位 man page 的位置的功能，我的想法是直接返回地址。 有人建议运行命令可以直接打开文件，那么其实后者实现以后如何测试也是个问题，而直接返回地址不仅方便测试，而且完全可以使用 tldr locate tar | xargs gedit 这样的组合达到打开文件的目的，编辑器也可以选择自己喜欢的。
最后的话
最后，如果对 tldr.py 有什么意见建议，欢迎向我来提 _(:3JZ
| [1] | 之前我是在 V2EX 发了个广告，现在决定自己再写一篇博文 _(:3 |
| [2] | http://tldr-pages.github.io/ 截至本文发表时，它依旧还是 |
