你好！上个月关于手册页的一些思考让我最大的收获是，手册页里的示例非常有用，所以我为两个最喜欢的工具的手册页添加（或完善）了示例。

就是这两个：

• 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 转 roff 脚本来把 Markdown 转换成 roff，并沿用了手册页已有的一些格式约定。其实我也可以直接用 pandoc，但 pandoc 生成的结果看起来差别挺大的，所以我觉得还是自己写个脚本更好。谁知道呢。

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

手册页很复杂

受 mandoc 项目的启发——BSD 系统（以及一些 Linux 系统，还有我觉得 Mac OS 也是）用它来格式化手册页——我一头扎进去，研究了 roff 的历史、它自 70 年代以来的演变，以及如今是谁在维护它。不过今天就不多说了，也许以后再聊。

总体来看，BSD 和 Linux 在文档工作方式上似乎存在技术和文化上的分歧，我还没有完全理解，但我一直很好奇 BSD 世界里到底是什么情况。

评论区在这里。