Julia Evans
examples for the tcpdump and dig man pages https://jvns.ca/blog/2026/03/10/examples-for-the-tcpdump-and-dig-man-pages/
Examples for the tcpdump and dig man pages

Examples for the tcpdump and dig man pages

Julia Evans
Mar 10 at 9:04pmWeb
Show threaddzwdzMar 10

@b0rk

re: what you said about roff

If you ever contribute to a project that uses mdoc(7) rather than "bare" roff macros, I'd actually recommend giving it a shot! I know it looks very intimidating, but once some friends convinced me to give it a shot anyways, I found it surprisingly comfy!

I'm sure you've stumbled upon that already, but for other people reading this: https://manpages.bsd.lv/ is a good read.

Practical UNIX Manuals: mdoc

Show threadJulia EvansMar 11

@dzwdz it does look very intimidating! it's really hard for me to imagine preferring mdoc over something like AsciiDoc or ReStructuredText or Markdown

(i found a talk talking about how mandoc is 100x faster than using AsciiDoc which I'm sure is true but having used AsciiDoc, definitely waiting 1 second for the man page to build was not a problem for me)

Show threaddzwdzMar 11

@b0rk Ignoring its whole "semantic" shtick... I just personally find it pleasant in a way your typical markup format isn't. I'm not sure how to describe it (especially since it's been a while since I wrote a nontrivial amount of mdoc, sadly).

The line-based macros give it a certain rhythm that I like. Most of the time there's only one obvious(-ish) way to format something, and I actually enjoy that rigidity compared to Markdown and such. Obviously all that is very much a "me" thing, YMMV 

Show threadJulia EvansMar 11
@dzwdz thanks, appreciate hearing your perspective!
Show threadOliver LoweMar 12
@dzwdz @b0rk Just a few days ago lowdown v3 released. It has support to output mdoc macros from markdown input: https://kristaps.bsd.lv/lowdown/mdoc.html
Might be interesting :)
Lowdown Manpage Support

Show threadJakub NarębskiMar 11

@b0rk The source code for `dig` manpage seems to be in reStructuredText, based on the *.rst extension... which GitLab mangles rendering of, not showing anything between "where:" and "Options" in "Simple usage".

Plain text is better: https://gitlab.isc.org/isc-projects/bind9/-/blob/7c82cb0f14e530234f2e239f51e92be11285ecc7/bin/dig/dig.rst?plain=1#L63

bin/dig/dig.rst · 7c82cb0f14e530234f2e239f51e92be11285ecc7 · ISC Open Source Projects / BIND · GitLab

Welcome to the public repository for BIND 9 source code and issues. Classic, full-featured and mostly standards-compliant DNS.

GitLab
Show threadJulia EvansMar 11
@jnareb will try to find a better link to the rendered html output
Show threadJulia EvansMar 12
@jnareb Here's the right link, I updated the post https://bind9.readthedocs.io/en/stable/manpages.html#dig-dns-lookup-utility
Manual Pages — BIND 9 9.20.20 documentation

Show threadjjMar 11

@b0rk
```In general it seems like there’s a technical and cultural divide in how documentation works on BSD and on Linux that I still haven’t really understood, but I have been feeling curious about what’s going on in the BSD world.```

From the BSD side, it feels almost too simple to mention in that when you add a new flag to program X, you must also correct/add to the manpage. Of course this would not explain is there are visible differences in examples, but at least it would explain why BSD manpages are regarded highly in general, even if they are sometimes arcane or imperfect, almost all details are there somewhere. All flags are in, not just some of them.

Show threadJulia EvansMar 11
@jj I'm confused, have you seen man pages outside of the BSD world that were missing flags? I've never noticed an issue like that in any man page (though it's possible I just wasn't paying attention)
Show threadjjMar 12
@b0rk In the times when many gnu tools moved to info pages, there were many inconsistencies and missing details where "--help" output, man pages and info docs were out of sync, and often distributions would in turn miss out on things like sed(1) not going into regexps per se, but pointing to another package like perlre to explain the format of basic and extended regexps (and difference between posix regexps and the one gnu sed supports). So while the latter is a fault(?) of the distribution packaging if the SEE ALSO links are not there, it still leaves you as the user without the needed docs in man format. While on BSDs the base tools can and do refer to other installed base tools but unless you deliberately strip out things, the links would work out, and you would be able to read about re_format(7) from the base tools that do support regexps.
But just to take one example from the "ip" command that replaced "ifconfig", on Ubuntu 24.04, the synopsis lists a certain amount of commands and options. Still, the options below contain -echo which is not in the synopsis, even though the synopsis does contain "long" options already. So at some point, someone added -echo to have the kernel tell you what got applied, it got its line in the lower part of the manpage, but synopsis doesn't mention it. Also, "ip --help" doesn't list it either.
Show threadKevin LydaMar 11

@b0rk I've used roff in the past and it's always intimidating at first and then rather simple. vi actually supports it rather well - the { and } operations understand roff paragraphs.

And yes, it does seem that BSD man pages are better maintained. But you're doing a bit to fix that. I've added a "man" page in my vimwiki to write down when I'm missing man pages or things in man pages. Starting with man(7) amusingly.

We can all make it better - thanks for this article!

Show threadKevin LydaMar 11

@b0rk Also, not sure if it was clear, but man -T dig will emit a postscript version of the man page. Each section has an intro page and that would be printed at the front of the book. There were 7 "manuals" and they were generated by the man command.

In BSD, those intro pages are better maintained.

Richard Stevens used to write all his books in roff. He was kind of like a previous generation's version of you! Not just good at doing, but also teaching.