Enhancing Man Pages with Practical Examples: A Guide for tcpdump and dig

Overview

Man pages are the traditional way to document command-line tools, but they often suffer from being dense and hard to navigate. Adding well-crafted examples can transform them into accessible, quick-reference guides—especially for beginners and infrequent users. This tutorial draws from the real-world experience of improving the tcpdump and dig man pages by adding example sections. You’ll learn how to identify what examples to include, how to write them in the roff language (or convert from Markdown), and how to collaborate with maintainers to ensure accuracy. By the end, you’ll be able to enhance any man page with clear, practical examples that users actually want.

Prerequisites

• Familiarity with command-line tools and basic Unix concepts.
• Access to the tool’s source repository or man page source file (often .1 or .txt).
• Basic understanding of roff (the formatting language for man pages) or willingness to use a Markdown-to-roff converter.
• A testing environment to preview man pages (e.g., man ./tcpdump.1).

Step-by-Step Instructions

Define the Scope of Examples

The first step is to decide what the examples should cover. The goal is the absolute most basic use cases—the commands that a person might type when they vaguely recall the tool but need a quick refresher. For tcpdump, that includes capturing packets on an interface, saving to a file, and filtering by protocol. For dig, it means querying a domain for A records, MX records, or reverse lookups. Avoid advanced scenarios that overwhelm novices; you can always add them later.

Consult Maintainers

Engage with the project’s maintainers early in the process. They know the tool inside out and can suggest features that even experienced users might miss. For example, while working on tcpdump, the author learned that using -v together with -w out.pcap prints a live count of captured packets—a simple but incredibly useful tip. Maintainers also ensure your examples are factually correct and follow the project’s conventions.

Write Examples in roff (or Markdown)

Man pages are traditionally written in the roff language. If you’re comfortable with roff, add a section like .SH EXAMPLES and use .TP for each example. Here’s a snippet for dig:

.SH EXAMPLES
.TP
.B dig example.com
Performs a default lookup for A records of example.com.
.TP
.B dig -x 8.8.8.8
Does a reverse DNS lookup for the IP address 8.8.8.8.

If roff feels intimidating, you can write in Markdown and convert it. The author created a simple markdown-to-roff script that transforms basic Markdown (headings, lists, code blocks) into roff directives. While Pandoc can do this too, its output may not match the existing man page style—so a custom script might be preferable. Here’s a minimal Python example that converts Markdown to roff for a single ## heading and a ``` code block:

def md_to_roff(line):
    if line.startswith('## '):
        return '.SH ' + line[3:].upper()
    elif line.startswith('```'):
        return '.PP\n.nf'
    else:
        return line

Adjust the script to match your project’s roff conventions (e.g., using .TP for bulleted lists).

Submit and Review

Once you have a draft, submit it as a patch or pull request to the tool’s repository. Be prepared for a review cycle where maintainers and community members examine every line. The original author received feedback from Denis Ovsienko, Guy Harris, and Ondřej Surý, which improved the examples significantly. This collaborative process ensures the documentation is both accurate and useful—qualities that are often missing in blog posts or Stack Overflow answers.

Common Mistakes

• Writing overly complex examples: Remember the intended audience—beginners and infrequent users. Keep examples short and focused on a single task.
• Neglecting to update related sections: If your examples introduce a new option (like -v), ensure the OPTIONS or DESCRIPTION sections also cover it. Consistency is key.
• Ignoring roff formatting pitfalls: Man pages have strict formatting rules. For instance, using "." at the start of a line (even in code) can cause errors. Always preview your changes with man -l file.1.
• Assuming prior knowledge: Don’t rely on jargon like “capture filter expression” without explanation. A brief phrase like “captures only TCP traffic” is enough.
• Skipping maintainer feedback: Even if you’re a power user, maintainers often know hidden features and edge cases. Their review prevents inaccuracies that could mislead users.

Summary

Adding examples to man pages doesn’t have to be a chore. By focusing on basic, beginner-friendly commands, collaborating with project maintainers, and choosing the right format (roff or Markdown-converted), you can create documentation that rivals the best blog posts in clarity—while remaining 100% correct. The experience of updating the tcpdump and dig man pages shows that this approach works: users get quick answers, and maintainers appreciate the contribution. You can do the same for any tool you care about. Start small, engage the community, and watch your man pages become a go-to resource.