Man Pages for Dig and Tcpdump Get Major Overhaul: New Examples Make Network Tools Accessible to Infrequent Users

Breaking News: The official documentation for two of the most widely used network diagnostic tools—dig and tcpdump—has been updated with comprehensive example sections, making them far more usable for beginners and infrequent users.

The changes, submitted and reviewed by a team of core maintainers, add beginner-friendly usage examples directly into the traditional UNIX man pages. This marks a significant departure from the often terse, reference-only style that has long frustrated newcomers.

Key Changes

The dig man page now includes a dedicated examples section, while the tcpdump man page has its previous examples expanded and refined. Both updates were driven by a clear mission: provide the absolute most basic examples for people who use these tools sporadically.

“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 project contributor who spearheaded the changes.

Background

The motivation for the overhaul stems from a broader push to improve the quality of official UNIX documentation. Previously, both man pages lacked practical, runnable examples, forcing users to rely on blog posts, Stack Overflow, or asking friends for guidance.

“Even with basic questions like ‘what are the most commonly used tcpdump flags?’, maintainers are often aware of useful features that I’m not!” the contributor explained. For instance, during the update, they discovered that combining tcpdump -w out.pcap with -v prints a live packet count—a feature they had never noticed before.

The effort was supported by key maintainers including Denis Ovsienko, Guy Harris, and Ondřej Surý, who provided technical reviews and validation. “It was a good experience and left me motivated to do a little more work on man pages,” the contributor added.

Technical Hurdles

The tcpdump man page is written in the roff language, which the contributor found “kind of hard to use.” To avoid learning the arcane syntax, they built a custom Markdown-to-roff converter that transforms simple Markdown into the required roff format. While pandoc was considered, its output diverged significantly, prompting the bespoke script.

The approach worked well enough to submit the updates, and the contributor noted that similar conventions were already in use on parts of the man page.

What This Means

For network administrators, DevOps engineers, and students who occasionally need to troubleshoot DNS or packet captures, these updates mean they no longer have to leave the terminal to understand the tool. Example-driven man pages reduce cognitive load and make it easy to get started quickly.

The changes also signal a cultural shift: that official documentation can be as engaging and accurate as a blog post, but with the added benefit of being vetted by the tool’s maintainers. “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 contributor mused.

If this experiment proves successful, similar example-driven sections could appear in other man pages across major open-source projects, potentially transforming how users interact with UNIX tools.

— This article is based on contributions by the network tools community and the man page updates published in the official dig and tcpdump repositories.