Network Diagnostics Tools tcpdump and dig Get Revamped Man Pages with Beginner Examples
Breaking: Major Update to tcpdump and dig Documentation
In a move that promises to make network troubleshooting more accessible, the official man pages for tcpdump and dig have received comprehensive updates featuring beginner-friendly examples. The changes, contributed by a community of maintainers, aim to reduce the learning curve for infrequent 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,” said a project contributor familiar with the revision.
Why This Matters
Man pages have long been criticized for being dense and hard to navigate. By embedding practical examples directly into the official documentation, the project hopes to make these critical tools as approachable as a well-written blog post — but with citable correctness.
Background: The Push for Better Man Pages
The initiative began after the same contributor realized that “examples in man pages are really great” and decided to improve them for two of their favorite tools. The resulting patches touched both the dig and tcpdump man pages, with the latter receiving an updated examples section.
Maintainers Denis Ovsienko, Guy Harris, and Ondřej Surý reviewed the documentation changes. The contributor noted the experience was “good and left me motivated to do a little more work on man pages.”
What Was Added: Beginner-Centric Examples
The new examples cover the most fundamental use cases. For tcpdump, one key addition is the -v flag: when saving packets with -w out.pcap, adding -v prints a live summary of how many packets have been captured.
“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. That’s really useful, I didn’t know it, and I don’t think I ever would have noticed it on my own,” the contributor shared.
The Technical Approach: Avoiding the Roff Language
Writing man pages typically requires knowledge of the roff formatting language, which the contributor admitted is “kind of hard to use.” Instead of learning it, they wrote a basic Markdown-to-roff conversion script that follows the man page's existing conventions.
“I could maybe have just used pandoc, but the output pandoc produced seemed pretty different, so I thought it might be better to write my own script instead. Who knows,” they remarked.
What This Means for Users
For network administrators and developers who rely on tcpdump and dig for debugging, the updated man pages lower the barrier to entry. New users can now find working command examples without resorting to third-party tutorials. Experienced users may also discover lesser-known flags, like the -v sinkhole trick.
The contributor expressed optimism about the future of official documentation: “I always kind of assume documentation is going to be hard to read, and I usually just skip it and read a blog post or Stack Overflow comment or ask a friend instead. But right now I’m feeling optimistic, like 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.”
Markdown-to-Roff Tool
The custom script, while simple, demonstrates a pragmatic approach to man page maintenance. It allows contributors to write in Markdown and then convert to roff, potentially making future updates faster.
Looking Ahead
The project encourages further contributions to expand examples across other sections of the man pages. With the success of these updates, other tools may follow suit, making the man command a friendlier resource for everyone.
— END —