tcpdump and dig Man Pages Updated with Beginner-Friendly Examples

Breaking: Network Troubleshooting Tools Get Documentation Overhaul

The official man pages for network diagnostic tools tcpdump and dig have been updated with dedicated examples sections. The changes, contributed by a developer in collaboration with project maintainers, aim to help infrequent users and beginners quickly get started without external tutorials.

“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,” the contributor said. The updates received positive reviews from maintainers including Denis Ovsienko, Guy Harris, and Ondřej Surý.

Background

Man pages are the traditional Unix documentation format, but are often criticized for being dense and hard to navigate. The developer noted that many users skip them in favor of blog posts or Stack Overflow. This project aimed to prove that official documentation can be both accurate and approachable.

“I always kind of assume documentation is going to be hard to read… but right now I’m feeling optimistic, like maybe the documentation doesn’t have to be bad,” they said. The effort drew inspiration from the Django documentation, which is widely praised for its clarity.

What This Means

Infrequent users of tcpdump and dig will now find concise, correct examples without wading through man page verbosity. The examples cover common flags and usage patterns, reducing the need for external searches.

During the update, the developer learned useful details such as combining tcpdump -w out.pcap with -v to print a live packet count summary. “That’s really useful, I didn’t know it, and I don’t think I ever would have noticed it on my own,” they said. The review process also uncovered other maintainer-cherished features.

Technical Challenges

The tcpdump man page is written in the roff language, which the developer found difficult to work with. To avoid learning roff, they wrote a basic Markdown-to-roff script that converts simpler Markdown syntax into the required format. While tools like pandoc exist, the output didn’t match man page conventions.

“I handled this by writing a very basic markdown-to-roff script… It could maybe have just used pandoc, but the output seemed pretty different,” they explained. The script is now part of the project’s documentation workflow.

Impact on Future Documentation

The success of this approach may inspire similar updates to other man pages. With maintainer involvement, documentation accuracy can approach 100%. The developer expressed motivation to continue improving man pages, hoping they become as reliable as the best online guides.

“Going through a review process to make sure that the information is actually true has a lot of value,” they concluded. The updates are already available in the latest releases of tcpdump and dig.