Enhancing Man Pages with Practical Examples: The tcpdump and dig Story

Introduction

Have you ever turned to a man page for help, only to be overwhelmed by dense technical jargon? The author of a recent blog post felt exactly that way—and decided to do something about it. After reflecting on how examples within man pages can make all the difference for infrequent or new users, they set out to add (or improve) example sections to two beloved networking tools: tcpdump and dig. The result? Updated man pages that now feature clear, beginner-friendly examples alongside the traditional reference material.

Enhancing Man Pages with Practical Examples: The tcpdump and dig Story

The Goal: Beginner-Friendly Examples

The primary objective was straightforward: provide the most basic, actionable examples for people who use tcpdump or dig rarely—or perhaps have never used them at all. The author wanted to answer the universal question, “How do I even start?” without requiring hours of study.

By framing the work as “writing examples for beginners and infrequent users,” the approach resonated well with tool maintainers and users alike. It’s an easy mission to explain, aligns with user feedback about what they truly want from documentation, and motivated maintainers to support the effort. The result: a set of examples that are both accurate and immediately useful.

Why Improve Official Documentation?

While third-party blog posts and Stack Overflow answers are often easier to digest, they can become outdated or contain errors. The author recognized that official man pages have unique advantages:

Near-perfect accuracy after a rigorous review process by the tool’s developers.
Maintainer insights that even experienced users may miss.

Accuracy Through Peer Review

When you contribute to a man page, every fact is checked by people who know the tool inside out. This review process ensures that the examples are not only helpful but also correct—something that blog posts can’t always guarantee.

Unexpected Discoveries

Working on the tcpdump examples, the author learned something surprising: when capturing packets to a file using tcpdump -w out.pcap, adding the -v flag prints a live summary of how many packets have been captured so far. This is extremely useful for long captures, yet it’s not something most tutorials mention. Such gems come directly from maintainers who know the subtle nuances of their tools.

Overcoming the roff Language Barrier

The tcpdump man page is written in the roff language, a formatting system that can be challenging to learn and use. Rather than mastering roff, the author took a pragmatic approach: they created a simple Markdown-to-roff conversion script. This script allowed them to write examples in familiar Markdown and automatically transform them into the required roff syntax, using conventions already present in the man page.

While tools like pandoc could theoretically perform this conversion, the output was too different from the existing conventions. Writing a custom script ensured consistency and saved significant time. The author admits it might not be the most elegant solution, but it got the job done—and the result is a better man page.

Conclusion: Documentation Doesn’t Have to Be Bad

The experience left the author feeling optimistic about the state of technical documentation. If official man pages can be as engaging and accurate as the best blog posts, why settle for less? The updated dig and tcpdump man pages prove that examples can make a real difference.

Special thanks go to Denis Ovsienko, Guy Harris, Ondřej Surý, and all the reviewers who helped refine the changes. Their feedback turned a good idea into a polished improvement for the community.

If you’ve ever shied away from man pages because they seemed unapproachable, give these updated versions a try. And if you’re a tool maintainer, consider adding an examples section—your users will thank you.

Tags: