Adding Practical Examples to tcpdump and dig Man Pages: Low-Barrier, High-Value Open Source Contributions

Background: Why Man Pages Need Better Examples

Prominent tech blogger Julia Evans reached a key conclusion during last month's discussion on man pages: examples in man pages are extremely important. Based on this insight, she set out to improve the examples sections in the official man pages for two of the most commonly used networking tools — tcpdump and dig.

tcpdump is the classic command-line packet capture tool for Unix/Linux systems, developed by Van Jacobson and others at Lawrence Berkeley National Laboratory in 1988. It relies on the libpcap library for cross-platform packet capture. libpcap uses raw sockets or dedicated interfaces provided by the OS kernel (such as Linux's AF_PACKET sockets or BSD's BPF — Berkeley Packet Filter) to enable promiscuous mode monitoring on network interfaces. BPF was originally designed by Steven McCanne and Van Jacobson in 1992, and its core innovation was pushing filtering logic down into kernel space, avoiding the need to copy all packets to user space for filtering — dramatically reducing performance overhead. eBPF (extended BPF) in the modern Linux kernel evolved from this foundation and has become a critical piece of infrastructure for cloud-native observability and network programming.

dig (Domain Information Groper) is a DNS query diagnostic tool bundled with the BIND software package, maintained by ISC (Internet Systems Consortium), and serves as the modern replacement for nslookup. nslookup was widely criticized for its interactive mode design and some behaviors that didn't conform to RFC standards, and the BIND development team once recommended deprecating it. dig's advantage lies in displaying complete responses in raw DNS message format, including the QUESTION SECTION, ANSWER SECTION, AUTHORITY SECTION, and ADDITIONAL SECTION, along with metadata such as query time and server address. This is crucial for troubleshooting complex issues like DNSSEC validation failures, TTL anomalies, and broken authoritative server delegation chains. In recent years, tools like drill and dog have gained attention as dig alternatives, but thanks to its widespread deployment in production environments and extensive documentation, dig remains the de facto standard tool of choice for network engineers debugging DNS issues. Both tools are heavily used in the daily work of system administrators and network engineers, yet their man pages have historically been known for high information density and a scarcity of examples.

The goal of this work was very clear: to provide the most basic usage examples for users who don't frequently use these tools (or have never used them at all). This positioning — "writing examples for beginners and infrequent users" — proved very effective when communicating with maintainers. It was easy to explain and easy to get buy-in for.

The Value of Improving Official Documentation

Accuracy Is the Core Advantage of Official Documentation

Julia highlighted several key reasons for improving official man pages rather than just writing blog posts:

1. Man pages can achieve near 100% information accuracy. After going through the maintainer review process, the reliability of the information far exceeds that of typical blog posts or Stack Overflow answers.

2. Maintainers know features you don't. While writing the tcpdump examples, Julia learned a practical tip: when using tcpdump -w out.pcap to save packets to a file, you can add the -v flag to display a real-time summary of the number of captured packets. This is incredibly useful, but without this collaboration, she might never have noticed it.

Documentation Doesn't Have to Be Hard to Read

Julia admitted that she used to assume documentation would be difficult to read, and would typically skip it in favor of blog posts, Stack Overflow, or just asking friends. But now she's starting to take an optimistic view: documentation can be as readable as an excellent blog post, while also having the advantage of being accurate. She cited Django's documentation as a positive example — it really is well-written documentation.

Technical Approach: An Engineering Decision to Bypass roff

The roff Dilemma

The tcpdump project's man pages are written in roff. roff is one of the oldest document formatting systems in Unix history, tracing back to the runoff program on MIT's CTSS system in 1964. roff (short for "run-off") evolved into nroff and troff under the Bell Labs Unix team — the former targeting terminal output, the latter targeting typesetting. Notably, troff was used in the 1970s to typeset the first edition of the Unix manual, and was later even used by Bell Labs to typeset legal documents submitted to the patent office — an important factor in Unix obtaining commercial licensing. Brian Kernighan (the K in K&R) made significant contributions to troff, developing the device-independent version ditroff. The GNU project later developed groff as an open-source implementation, which remains the default rendering engine for the man command on Linux systems today. roff syntax revolves around macro commands that start with a dot — for example, .TH defines the title, .SH defines a section, and .PP starts a paragraph. For developers accustomed to modern markup languages, the learning curve is steep. Although roff seems arcane to modern developers, its dominance in technical documentation lasted half a century. Core infrastructure documentation like Linux kernel docs and GNU toolchain manuals are still maintained in roff format to this day — the existence of this technical debt is precisely why contributors like Julia need to find workarounds. Julia explicitly stated she didn't want to learn this language.

A Custom Markdown-to-roff Script

Her solution was to write a very basic Markdown-to-roff conversion script using formatting conventions similar to the existing man pages. While pandoc can do similar conversions, its output differed significantly from the existing format, so she chose to implement her own.

Technically, she leveraged an existing Markdown library's ability to parse Markdown into an AST (Abstract Syntax Tree), then implemented her own code generation methods to format the output appropriately. An AST is a core data structure in the compiler and parser domain, representing the hierarchical structure of source text as tree nodes, decoupled from any specific text format. Parsing documents into an AST and then generating the target format is the mainstream architectural choice in modern documentation toolchains. Taking the Markdown ecosystem as an example, parsers like unified.js (JavaScript), pulldown-cmark (Rust), and mistletoe (Python) all provide standardized AST output interfaces, allowing the same source document to be rendered into HTML, PDF, man pages, EPUB, and other formats without duplicating parsing logic. The robustness of this architecture is evident in its correct handling of nested structures — for instance, asterisks inside code blocks should not be parsed as emphasis markers, and simple regex-based approaches are prone to errors in such edge cases. In document conversion scenarios, parsing Markdown into an AST before generating the target format is far more robust than direct regex substitution, because the AST preserves the semantic structure of the document (paragraphs, lists, code blocks, etc.) rather than just string patterns. Julia's approach essentially implements a code generator backend targeting roff output, which is conceptually identical to how a compiler compiles the same AST into machine code for different target platforms. Her choice to reuse an existing Markdown library's parsing capabilities while only implementing the code generation backend is a textbook example of "not reinventing the wheel."