How to Enhance Man Pages with Practical Examples: A Guide for Tcpdump and Dig

By ✦ min read

Introduction

Man pages are powerful, but often lack clear examples. This guide shows you how to add beginner-friendly examples to official man pages for tools like tcpdump and dig, based on real-world experience. You'll learn to gather accurate information, write effective examples, and navigate documentation formatting challenges.

What You Need

• Basic command-line knowledge – familiarity with terminal operations
• A text editor – e.g., Vim, Nano, or VS Code
• Access to the tool’s source repository – e.g., Git clone of tcpdump or dig (BIND)
• Understanding of man page structure – sections like NAME, SYNOPSIS, DESCRIPTION, EXAMPLES
• Optional: Markdown-to-roff converter – or write directly in roff language

Step-by-Step Guide

Step 1: Study Existing Man Pages and Identify Gaps

Read the current man page for your target tool. Note what’s missing: common flags, typical use cases, or beginner questions. For tcpdump, users often ask “How do I capture traffic on a specific port?” For dig, “How do I query a specific DNS record type?” These become your example candidates.

Step 2: Research Accurate Information

Man pages must be correct. Consult official documentation, the tool’s source code, or maintainers. In the original project, the author learned from maintainers like Denis Ovsienko and Guy Harris. Verify each flag’s behavior – for instance, tcpdump -w out.pcap -v prints a live packet count summary, a useful tip.

Step 3: Choose Basic, Real-World Examples

Focus on beginners and infrequent users. Keep examples simple: one flag, one output. For dig, a basic example might be dig example.com and explaining the answer section. For tcpdump, tcpdump -i eth0 to list interfaces. Each example should solve a single problem.

Step 4: Write in a Clear, Narrative Style

Use plain English. Explain what each command does and what the output means. Avoid jargon. For instance: “The -v flag increases verbosity, showing you how many packets have been captured so far – useful when saving to a file.”

Step 5: Format Examples in Man Page Style

Man pages use roff language, which can be tricky. If you prefer Markdown, you can write examples in a simple Markdown file and convert it. The author created a basic Markdown-to-roff script rather than using Pandoc, because Pandoc’s output differed from the existing formatting. Alternatively, learn roff basics – place examples in a .EX / .EE block.

Step 6: Integrate Examples into the Correct Section

Add a new EXAMPLES section (or append to an existing one). Follow the tool’s man page structure. Use internal anchor links (e.g., ) for cross-references. If the page already has examples, update them with better explanations.

Step 7: Submit for Review

Open a pull request or send a patch to the project maintainers. Expect feedback on accuracy, clarity, and style. The original examples for tcpdump and dig went through review, which improved them significantly. Be open to suggestions – maintainers often know hidden features.

Step 8: Test the Examples Yourself

Run each command exactly as written. Check that the output matches your description. If a flag behaves differently on your system, note the difference or adjust the example. Testing ensures reliability.

Step 9: Document Any Formatting Hacks

If you used a custom converter, include a comment in the source. For the tcpdump project, the author noted the Markdown-to-roff approach. Future maintainers will appreciate knowing why the formatting is unusual.

Step 10: Celebrate the Improvement

Your examples will help thousands of users. The original project received positive feedback and motivated the author to improve more man pages. A well-written man page reduces the need for Stack Overflow or blog posts – and it’s always correct.

Tips and Conclusion

• Start small – even one good example is better than none.
• Use the same language as the rest of the man page – consistency helps readers.
• Link examples to common flags – e.g., in tcpdump, pair -w with -v.
• Ask for feedback early – maintainers appreciate your initiative.
• Don’t fear roff – focus on content; formatting can be learned.

Enhancing man pages with examples is a rewarding contribution that makes powerful tools accessible to everyone. By following these steps, you can transform dry documentation into a clear, helpful resource. For more inspiration, read the original article on improving tcpdump and dig man pages.