Breaking: Man Pages for tcpdump and dig Updated with Real-World Examples
January XX, 2025 — The official man pages for two essential network diagnostic tools—tcpdump and dig—have been significantly overhauled to include practical examples, aiming to lower the barrier for newcomers and occasional users.
The update introduces dedicated example sections for both tools, providing step-by-step commands that illustrate common usage scenarios. “The goal was to give the absolute most basic examples for people who use tcpdump or dig infrequently, or have never used them before,” a project contributor told TechWire. “It’s easy to explain and maintainers found it compelling.”
Background: Why Man Pages Needed a Refresh
Man pages—short for manual pages—are the traditional documentation format for Unix-like operating systems. While comprehensive, they have long been criticized for being dense, technical, and lacking real-world usage examples. Many users turn to blog posts, Stack Overflow, or informal guides instead.
The push to improve man pages began when a developer argued that examples are “really great” and started adding them to two of their favourite tools. The tcpdump example section is an update to an earlier version, while the dig man page now includes examples for the first time. The work was reviewed by maintainers including Denis Ovsienko, Guy Harris, and Ondřej Surý, ensuring accuracy. “Going through a review process to make sure the information is actually true has a lot of value,” the contributor added.
What This Means for Users
For network administrators, developers, and students, the new examples reduce reliance on third-party sources. Official documentation can now compete with the clarity and immediacy of a well-written blog post, but with the added benefit of being verified by the project maintainers.
The update also reveals lesser-known features. For instance, the tcpdump example section highlights that using -v with the -w flag prints a live packet count—a tip the contributor says they “never would have noticed on their own.”
Technical Details: Overcoming the roff Barrier
Man pages for tcpdump are written in the roff language, which the contributor found “kind of hard to use.” Instead of learning roff, they wrote a simple Markdown-to-roff converter script, adapting conventions already used in the man page. The script ensures the examples are maintainable and readable without mastering obscure formatting.
“I did think it was cool,” the contributor remarked, acknowledging that while tools like pandoc exist, the custom script produced output closer to the existing style.
Outlook: A Blueprint for Better Documentation
The positive reception and smooth review process have left the contributor motivated to continue improving man pages. “Right now I’m feeling optimistic—maybe documentation doesn’t have to be bad,” they said. “Maybe it could be just as good as reading a really great blog post, but with the benefit of being actually correct.”
They point to the Django documentation as a model for high-quality, accessible official docs. With this update, tcpdump and dig join a growing movement to make man pages user-friendly.