Examples land in the tcpdump and dig man pages
Last month’s discussion about man pages highlighted how valuable concrete examples are, especially for tools people reach for only occasionally. Following through on that idea, the man pages for dig and tcpdump have been updated with new or improved example sections.
Both updates target the same audience: users who know the tool exists but don’t use it often enough to remember the basics. The dig man page now has examples where it previously had none, while the tcpdump examples were revamped and expanded. The goal was never to cover every edge case, but to show the most common invocations clearly and correctly.
Why official docs are worth the trouble
Maintaining tool documentation can feel less rewarding than writing a blog post or answering a Stack Overflow question. But the review process for official man pages provides something those informal channels can’t: a guarantee of accuracy, approaching 100%. When a maintainer reviews your example that tcpdump -w out.pcap saves packets to a file, it’s verified — not just plausible.
The review process has a second benefit: maintainers often surface details a user would never discover on their own. For instance, while working on the tcpdump examples, it became clear that pairing -w out.pcap with -v makes the tool print a live count of captured packets as the capture runs. That’s a small flag combination that changes the experience of a long capture, and it came straight from someone deeply familiar with the codebase.
Good documentation also doesn’t have to be a compromise. A well-crafted man page example can read as clearly as a strong technical blog post — it just happens to be vetted as correct. The Django documentation demonstrates this quality level consistently, and there’s no reason networking tools can’t aim for similar clarity.
A detour around roff
The tcpdump man page is written in roff, the text formatting language that has been around in various forms since the 1970s and isn’t exactly pleasant to author in directly. Rather than learning its full syntax, the examples were drafted in Markdown and converted using a minimal custom script built on an existing Markdown parser.
The conversion approach deserves a note: instead of winging it with regexes or finding a giant prebuilt conversion tool that produces wildly different formatting, the script parses Markdown into an AST and then implements custom emission methods. That approach produces output matching the man page’s existing style — a level of control that generic converters like pandoc would likely not provide out of the box.
Behind the scenes, the work also motivated digging into how roff is rendered today across different operating systems. BSD and macOS systems use the mandoc project for formatting, while Linux has its own approach — a documentation ecosystem split that’s rooted in BSD and Linux cultural differences around how tools are built and maintained.
