Breaking: Man Pages Updated
In a move aimed at making network troubleshooting tools more accessible, the official man pages for tcpdump and dig have been updated with comprehensive examples. The changes, merged in recent days, are designed to help both beginners and infrequent users quickly recall essential commands.
Expert Quotes
“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 documentation contributor behind the update.
“So far saying ‘hey, I want to write an examples section for beginners and infrequent users of these tools’ has been working really well,” they added, highlighting positive feedback from the open-source community.
Background: Why Examples Matter
Improving official documentation has long been a challenge in the open-source ecosystem. Man pages often suffer from being dense, outdated, or intimidating. The contributor noted that “man pages can actually have close to 100% accurate information” and that a proper review process ensures correctness.
During the update, the contributor discovered previously unknown features. “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 explained. “I didn’t know it, and I don’t think I ever would have noticed it on my own.”
Technical Challenges and Innovations
The tcpdump man page is written in the roff language, which the contributor described as “kind of hard to use.” Rather than learning roff from scratch, they built a custom Markdown-to-roff conversion script. “I handled this by writing a very basic Markdown-to-roff script to convert Markdown to roff, using similar conventions to what the man page was already using,” they said.
Alternative tools like pandoc were considered but discarded because their output “seemed pretty different.” The contributor acknowledged the approach might not be perfect but found it effective.
What This Means for Users
For network administrators, developers, and system administrators, the updated man pages promise to reduce reliance on third-party blogs or Stack Overflow answers. 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?”
This update aligns with a broader trend of improving official documentation in the open-source world, following examples like Django’s well-regarded docs. The changes are already available in the latest releases of tcpdump and dig.
Acknowledgments
Special thanks go to Denis Ovsienko, Guy Harris, Ondřej Surý, and all reviewers who “provided valuable feedback during the docs changes.” The contributor described the experience as “good… and left me motivated to do a little more work on man pages.”
Internal Links
Learn more about tcpdump examples and dig examples in the official man pages.