Hey really cool! Tcpdump co-author here. If you're interested in the origin story of the tcpdump language, bpf, and pcap, I had fun putting together a talk a number of years ago... https://www.youtube.com/watch?v=XHlqIqPvKw8
For normal, day to day use, examples in documentation is absolute gold. As a practical matter, that's how we human learn to do things. Perhaps surprisingly, even AI benefits from examples.
Children don't learn to speak a language by learning all the grammar and conjugation rules first. They learn by repeating phrases they've heard before and they generalize. Usually we learn tools the same way. We see someone else using a tool, and we do what they're doing, and generalize.
That's not to say that man pages should consist only of examples. There are times when you really do need to understand how the tool processes corner cases and really understand how it works. But I expect most of us here can relate to the experience of opening the man page for a tool and being completely baffled by a wall of unfamiliar jargon. Most of the time you just want to see how to do the most normal common functions, especially when you're learning a tool the first time.
Why stop at man pages examples, should go all the way to literate programming enabled examples with the help of CUE configs language [1].
Perhaps it's overkill for power users, but most of the users will probably find it handy for the tricky find tool and friends [2].
I think other Unix/Linux users will find the literate programming approach as more useful, intuitive and less error prone ways to complement The Linux Programming Interface book [3].
[1] Cue Does It All, but Can It Literate? (22 comments)
My go-to for examples is ‘tldr’ Maybe you could add the examples there, too? Then again, if every man page had basic usage examples, maybe I wouldn’t go to ‘tldr’
12 comments
Children don't learn to speak a language by learning all the grammar and conjugation rules first. They learn by repeating phrases they've heard before and they generalize. Usually we learn tools the same way. We see someone else using a tool, and we do what they're doing, and generalize.
That's not to say that man pages should consist only of examples. There are times when you really do need to understand how the tool processes corner cases and really understand how it works. But I expect most of us here can relate to the experience of opening the man page for a tool and being completely baffled by a wall of unfamiliar jargon. Most of the time you just want to see how to do the most normal common functions, especially when you're learning a tool the first time.
Perhaps it's overkill for power users, but most of the users will probably find it handy for the tricky find tool and friends [2].
I think other Unix/Linux users will find the literate programming approach as more useful, intuitive and less error prone ways to complement The Linux Programming Interface book [3].
[1] Cue Does It All, but Can It Literate? (22 comments)
https://news.ycombinator.com/item?id=46588607
[2] find(1) — Linux manual page:
https://man7.org/linux/man-pages/man1/find.1.html
[3] The Linux Programming Interface:
https://man7.org/tlpi/