Enhancing Man Pages with Practical Examples: A Look at tcpdump and dig

Introduction

Man pages are often the go-to reference for command-line tools, but they can be intimidating for new or infrequent users. The inclusion of clear, practical examples can bridge that gap, making these resources far more accessible. Recently, two popular networking tools—tcpdump and dig—received significant updates to their man pages, adding or improving example sections. This article explores the reasoning behind those changes, the process, and the lessons learned.

The Motivation Behind Man Page Improvements

Man pages are often the most authoritative source of information for a tool, but they can be dry or difficult to navigate. The author of the improvements wanted to address this by providing the most basic, commonly needed examples. For someone who uses tcpdump or dig only occasionally (or for the first time), a set of practical examples can save hours of searching online.

The goal was straightforward: give users exactly what they need to start using the tool effectively. This approach resonates with many maintainers and users, as it directly answers the question, “How do I do this common task?” without requiring a deep understanding of every flag and option.

Adding Basic Examples for Beginners

For the dig man page, examples were added from scratch. For tcpdump, existing examples were updated and expanded. The focus was on the most fundamental use cases, such as capturing packets on a specific interface, filtering traffic, or saving captures to a file. The idea was to create a “quick start” guide within the man page itself.

The Impact of Including Real-World Scenarios

One of the most valuable insights from this work came from the review process. For instance, when working on tcpdump examples, the maintainers suggested adding the -v flag when saving packets with -w out.pcap. This prints a live summary of captured packet counts—a feature the author never knew existed. Such hidden gems often emerge when maintainers review examples, making the documentation richer and more accurate.

Lessons Learned from the Review Process

Collaboration with project maintainers was a key part of the effort. Thanks to contributions from experts like Denis Ovsienko, Guy Harris, and Ondřej Surý, the examples were refined and verified for correctness. This peer review is crucial—man pages can achieve nearly 100% accuracy when properly vetted, something not always possible with blog posts or Stack Overflow answers.

The experience also revealed that even basic questions like “What are the most commonly used tcpdump flags?” can lead to discoveries when discussed with maintainers. Their deep knowledge uncovers features that a typical user might never stumble upon.

The Value of Accurate Documentation

While it’s easy to turn to a blog post or a friend for help, those sources can be outdated or wrong. Official man pages, when well-maintained, offer a trustworthy alternative. The author noted that Django’s documentation is a great example of how official resources can be both engaging and correct. This project aims to bring that same quality to tcpdump and dig.

Overcoming Formatting Challenges: From Markdown to Roff

One significant hurdle was the man page format itself. The tcpdump project uses the roff language, which can be cumbersome to write directly. Rather than learning roff, the author created a simple custom script to convert Markdown to roff. This used conventions already present in the existing man page, ensuring consistency.

Why not use a tool like Pandoc? While Pandoc can transform Markdown into many formats, its roff output was quite different from the man page’s existing style. Writing a tailored script allowed control over the output, preserving formatting like bold, italics, and lists exactly as needed. The script is available for others to use or adapt.

Building a Markdown-to-Roff Converter

The script was kept very basic, focusing on the most common elements: headings, paragraphs, code blocks, and lists. This approach simplified the conversion process and avoided the overhead of a full-fledged tool. The result was a streamlined workflow that let the author concentrate on content rather than syntax.

The Future of Documentation

This initiative has shown that man pages don’t have to be unpleasant to read. With thoughtful examples and community collaboration, they can be as effective as the best blog posts—while also being more reliable. The author feels optimistic that this model can be applied to other tools, improving the documentation landscape for everyone.

For those interested in contributing, the takeaway is clear: start with examples. They are the easiest part to write, the most impactful for users, and the most likely to attract helpful feedback from maintainers.

See also: Introduction | Motivation | Examples | Formatting