Man Page Overhaul: tcpdump and dig Now Feature Beginner-Friendly Examples

Man Page Overhaul: tcpdump and dig Now Feature Beginner-Friendly Examples

The official documentation for two core network diagnostic tools—tcpdump and dig—has been revamped with brand-new, beginner-focused example sections. The updates, contributed by a developer and reviewed by the respective project maintainers, aim to make these man pages more accessible to infrequent or first-time users.

The goal was really just to give the absolute most basic examples of how to use the tool, for people who use tcpdump or dig infrequently (or have never used it before!) and don’t remember how it works, the contributor explained. The developer, who prefers to remain anonymous, has also worked on improving examples in other man pages.

Background

Man pages have long been criticized as dense and hard to navigate. While they often contain accurate information, finding practical usage examples can be challenging, especially for newcomers. The contributor took on this project after previous musings on the value of examples in man pages.

To avoid the steep learning curve of the roff typesetting language used by many man pages, the developer wrote a custom Markdown-to-roff conversion script. This allowed the examples to be written in a simpler format while still producing valid man page output.

What This Means

With these updates, users can now access official, vetted examples directly from the man pages. For tcpdump, common usage patterns—such as saving packets to a file with -w—are now accompanied by the recommendation to use the -v flag for a live packet count summary. For dig, basic query examples help users perform DNS lookups without memorizing all command-line options.

The contributor noted that the review process uncovered features they had never known about: I learned by working on these tcpdump examples that if you’re saving packets to a file with tcpdump -w out.pcap, it’s useful to pass -v to print a live summary of how many packets have been captured so far. That’s really useful, I didn’t know it, and I don’t think I ever would have noticed it on my own.

These improvements signal a shift towards making official documentation as approachable and accurate as high-quality blog posts, while removing the risk of outdated or incorrect information. The contributor expressed optimism: Maybe the documentation doesn’t have to be bad? Maybe it could be just as good as reading a really great blog post, but with the benefit of also being actually correct?

How the Update Was Done

The tcpdump man page is written in the roff language, which the contributor found challenging. Instead of learning roff, the developer built a lightweight Markdown-to-roff converter. The script follows existing man page conventions, ensuring the new examples integrate seamlessly. While alternative tools like Pandoc were considered, their output differed significantly, leading to the custom solution.

The contributor acknowledged the help of reviewers Denis Ovsienko, Guy Harris, Ondřej Surý, and others, stating that the collaborative process left them motivated to do a little more work on man pages.

Impact on the Community

For network administrators, system engineers, and anyone learning packet analysis or DNS troubleshooting, these updates reduce friction. Instead of scouring the web for correct command syntax, users can now rely on the man pages themselves as a primary source of guidance. The contributor hopes that improved documentation will encourage more people to use these powerful tools rather than fear their complexity.

As open-source projects evolve, the focus on usability—not just feature development—gains importance. This small but targeted update is a step toward bridging the gap between raw reference material and practical, user-friendly documentation.