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

Introduction

Man pages are a cornerstone of Unix-like systems, yet they often suffer from dense formatting and a lack of practical guidance. Recent work on the man pages for two essential network tools—tcpdump and dig—demonstrates how adding clear, beginner-friendly examples can transform these reference documents into genuinely useful resources. This article explores the motivation behind this effort, the process of gathering and verifying examples, and a clever workaround for avoiding the esoteric roff typesetting language.

Why Improve the Man Pages?

Documentation often gets a bad reputation—it’s seen as outdated, hard to read, or simply ignored in favor of blog posts or Stack Overflow answers. However, man pages have a unique advantage: they can be nearly 100% accurate, especially when subjected to a thorough review process. The drive to enhance the tcpdump and dig man pages stemmed from three observations:

• Accuracy matters: Going through a formal review ensures that every flag, syntax, and example is correct.
• Hidden gems surface during discussions with maintainers. For example, while crafting tcpdump examples, the author learned that using -v with -w out.pcap prints a live summary of captured packets—a feature many infrequent users might miss.
• Infrequent users need a ramp: Even basic questions like “what are the most commonly used tcpdump flags?” can be addressed directly in the man page itself.

The Goal: Basic, Practical Examples

The primary aim was to provide the absolute most basic examples for people who use tcpdump or dig rarely—or for the first time—and don’t remember how to invoke them. The approach was simple: “I want to write an examples section for beginners and infrequent users.” This straightforward pitch resonated with project maintainers, who found it compelling and easy to understand. By focusing on use cases like capturing packets or querying DNS records, the examples become immediately applicable.

The Review Process: A Collaborative Effort

The updated man pages were not created in isolation. Special thanks go to Denis Ovsienko, Guy Harris, Ondřej Surý, and other reviewers who contributed feedback. Their involvement ensured the examples were not only correct but also represented best practices. The author described the experience as positive and motivating, sparking further interest in improving man pages.

Avoiding the Man Page Language (roff)

The tcpdump man page is written in the roff language, which can be challenging to work with. Rather than learning a complex typesetting system, the author created a custom Markdown-to-roff conversion script using simple conventions already present in the man page. While tools like pandoc exist, their output differed significantly, making a tailored script a better fit. This pragmatic approach allowed the focus to remain on content quality rather than formatting syntax.

The Markdown-to-roff Solution

The script was designed to be lightweight, converting basic Markdown elements (headings, lists, code blocks) into roff commands. It leveraged patterns already used in the existing documentation, minimizing disruption. Although the script is not perfect, it served its purpose: making the editing process accessible and efficient.

Conclusion: A New Hope for Documentation

The work on the tcpdump and dig man pages shows that official documentation can be as approachable as a well-written blog post—without sacrificing accuracy. By prioritizing examples, engaging maintainers, and creatively sidestepping technical hurdles, we can make man pages truly useful for everyone. As the author noted, “Maybe documentation doesn’t have to be bad.” With continued efforts like these, the future of man pages looks bright.