Tcpdump and Dig Man Pages Get Beginner-Friendly Examples in Community-Driven Update
Breaking: Man Pages for Tcpdump and Dig Now Include Beginner-Friendly Examples
In a move welcomed by network administrators and developers, the official man pages for the widely-used networking tools tcpdump and dig have been updated with comprehensive new examples sections. The changes aim to help infrequent users and beginners quickly recall common commands without resorting to external blog posts or community forums.
“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,” said the developer who spearheaded the project. The contribution has already been merged into the mainline documentation of both tools.
Key Improvements
The new examples cover everyday scenarios, such as capturing packets with tcpdump and performing DNS lookups with dig. Notably, the tcpdump examples now include the recommendation to use the -v flag when saving packets to a file with -w, a tip the developer discovered during the review process. “I learned 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,” they noted, calling the insight “really useful” and something they would not have noticed on their own.
Background: Man pages have long been criticized for being dense, hard to navigate, and lacking practical examples. Many users instead turn to third-party tutorials or Stack Overflow answers, which may be outdated or inaccurate. This update reflects a growing trend among open-source projects to prioritize user-friendly documentation. The developer received reviews from Denis Ovsienko, Guy Harris, Ondřej Surý, and others, leaving them “motivated to do a little more work on man pages.”
The Technical Approach
Writing examples directly in the traditional roff language (used by man pages) was a challenge. Instead, the developer created a lightweight Markdown-to-roff converter to simplify the process. “The tcpdump project tool’s man page is written in the roff language, which is kind of hard to use and that I really did not feel like learning it,” they explained. The custom script produced output consistent with existing man page conventions, avoiding the need for more complex tools like pandoc.
What This Means
For end users, the updated man pages reduce the friction of learning or recalling command syntax. Beginners can now find safe, verified examples directly in the documentation, while experienced users gain quick reference for less frequent tasks. The project also sets a precedent for other Unix tools to follow suit, potentially raising the baseline quality of official documentation. As the developer remarked, “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.”
The update applies to the dig man page (now with examples) and the tcpdump man page examples (an enhancement of previous work). Users can view the new content by running man dig or man tcpdump on updated systems, or by checking the source repositories online.
Community Reaction
“It’s easy to explain, I think it makes sense from everything I’ve heard from users about what they want from a man page, and maintainers seem to find it compelling,” the developer said. The responsiveness of the maintainer teams was praised, with the contributor thanking reviewers for a “good experience.” No major negative feedback has been reported.
Related Discussions