本文翻译自 Examples for the tcpdump and dig man pages，原载于 Hacker News。

上个月我在思考 man 手册（manual pages）的时候，最大的感悟就是：man 手册里的示例真的太有用了。于是我开始为两个我最喜欢的工具的 man 手册添加（或改进）示例。

这里是成果：

• dig man page（现在有了示例！）
• tcpdump man page examples（这是对之前示例的更新）

目标：提供最基础的示例

这次的目标很简单，就是为那些不经常使用 tcpdump 或 dig（甚至从未用过！）的用户，提供最基础、最实用的使用示例。

到目前为止，我发现说”我想为初学者和不常使用这些工具的人写一个示例章节”这个理由非常有效。这个想法很容易解释，从用户反馈来看也非常符合他们的需求，而且维护者们也觉得很有意义。

感谢 Denis Ovsienko、Guy Harris、Ondřej Surý 以及所有参与文档审核的人，整个过程非常愉快，也让我更有动力继续完善 man 手册。

为什么要改进 man 手册？

我现在对改进工具的官方文档很感兴趣，原因如下：

1. Man 手册的信息准确率可以接近 100%！ 通过审核流程确保信息真正正确，这本身就有很大价值。

2. 即使是”最常用的 tcpdump 参数有哪些”这种基本问题，维护者们往往知道很多我不知道的实用功能！ 比如我在写 tcpdump 示例时学到了一个小技巧：当你用 tcpdump -w out.pcap 把数据包保存到文件时，加上 -v 参数可以实时显示已捕获的数据包数量。这真的很有用，我之前完全不知道，而且如果不是这次贡献，我可能永远都不会注意到。

说实话，这对我来说有点奇怪，因为我一直觉得文档很难读，通常直接跳过，去看博客文章、Stack Overflow 或者问朋友。但现在我很乐观——也许文档不一定非得很糟糕？也许它可以像一篇优秀的博客文章一样易读，同时还保证内容正确？

最近我在用 Django 的文档，真的很棒！让我们拭目以待吧。

关于避免直接写 roff 语言

tcpdump 项目的 man 手册是用 roff 语言写的，这种语言有点难用，我实在不想专门去学它。

我的解决方案是写了一个简单的 markdown-to-roff 转换脚本，用类似原 man 手册的约定把 Markdown 转成 roff。我本可以用 pandoc，但它生成的输出风格差异较大，所以我决定自己写一个。谁知道呢，也许以后会后悔。

不过我觉得很酷的一点是，可以直接利用现有 Markdown 库解析 Markdown AST（抽象语法树），然后实现自己的代码生成方法，按照这个场景的需求来格式化内容。

Man 手册的复杂性

我顺便还深入了解了一下 roff 的历史——它从 70 年代演变至今的过程，以及现在谁在维护它。这源于我了解到了 mandoc 项目，BSD 系统（以及一些 Linux 系统，包括 macOS）用它来格式化 man 手册。今天就不展开了，以后有机会再说。

总的来说，BSD 和 Linux 在文档方面的技术和文化差异似乎很大，我还没有完全理解，但我对 BSD 世界发生的事情越来越好奇了。

总结

这篇文章给我几点启发：

1. 文档示例的价值不可低估 —— 对于不常用的工具，一个简单的示例往往胜过千言万语的参数说明。

2. 贡献文档是很好的开源参与方式 —— 不需要精通代码，只要你会用这个工具，就能帮助改进文档。

3. 与维护者交流能学到很多 —— 即使是基本问题，维护者也可能知道很多隐藏的实用技巧。

下次当你抱怨某个工具的文档不好用的时候，不妨考虑贡献一些示例。就像作者说的，”我想为初学者写示例”这个理由通常都会被欣然接受！