Julia EvansMar 10
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
Show threaddzwdz

@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

Mar 10 at 9:16pmWeb
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