tcpdump 和 dig 手册页示例
你好！我上个月关于手册页的随想中最大的收获是，手册页中的示例非常棒，因此我着手为我最喜欢的两个工具的手册页添加（或改进）示例。
成果如下：
- dig 手册页（现已包含示例）
- tcpdump 手册页示例（这是对之前示例的更新）
目标：包含最基础的示例
这里的目标其实很简单，就是为那些不常使用 tcpdump 或 dig（甚至从未使用过！）以及记不住其用法的用户，提供最基础的工具使用示例。
到目前为止，说“嘿，我想为初学者和不常使用这些工具的用户写一个示例章节”这一说法效果非常好。它很容易解释，从我听到的用户对手册页的期望来看也很有道理，而且维护者们似乎也觉得很有说服力。
感谢 Denis Ovsienko（丹尼斯·奥夫先科）、Guy Harris（盖伊·哈里斯）、Ondřej Surý（翁德热伊·苏里）以及所有审阅了文档修改的人，这是一次很好的经历，也让我更有动力在手册页上做更多工作。
为什么要改进手册页？
我现在之所以有兴趣直接改进工具的官方文档，是因为：
- 手册页实际上可以做到信息接近 100% 准确！通过审阅流程来确保信息的真实性非常有价值。
- 即使是“最常用的 tcpdump 选项有哪些”这类基础问题，维护者往往也知道一些我不知道的实用功能！例如，在为这些 tcpdump 示例做贡献的过程中，我了解到如果使用
tcpdump -w out.pcap将数据包保存到文件，传入-v来实时打印已捕获数据包数量的摘要会很有用。这真的很实用，我之前并不知道，而且我觉得靠自己可能永远都不会注意到它。
说起来有点奇怪，因为说实话我一直默认文档会很难读，所以通常会直接跳过，转而去看博客文章、Stack Overflow 评论或去问朋友。但现在我感到很乐观，觉得文档也许不必那么糟糕？也许它可以和一篇非常出色的博客文章一样好，同时还具备完全正确的优势？我最近一直在用 Django 的文档，它真的很棒！拭目以待吧。
关于避免直接编写手册页标记语言
tcpdump 项目的手册页是用 roff 语言编写的，这种语言有点难用，而我真的不想去学它。
我的处理方式是编写了一个非常基础的 markdown-to-roff 脚本，将 Markdown 转换为 roff，遵循手册页已有的类似约定。我本来也可以直接用 pandoc，但 pandoc 生成的输出看起来差别很大，所以我想还是自己写个脚本更好。谁知道呢。
我觉得很酷的一点是，能够直接利用现有 Markdown 库解析 Markdown AST 的能力，然后自己实现代码生成方法，以一种在这个场景下看起来合理的方式来格式化内容。
手册页很复杂
在了解到 BSD 系统（以及一些 Linux 系统，我想还有 Mac OS）用于格式化手册页的 mandoc 项目后，我陷入了对 roff 历史、它自 20 世纪 70 年代以来的演变以及如今是谁在维护它的深入探索。不过今天就不多说了，也许以后再谈。
总体来看，BSD 和 Linux 在文档工作方式上似乎存在技术和文化上的分歧，我还没有完全理解，但我一直对 BSD 世界里正在发生的事情感到好奇。