Because learning from unexplained examples is useless.

On the other hand, cocking up an unfamiliar phrase in a spoken language doesn't usually result in accidentally killing the listener.

I haven't yet had a computer ask for clarification when I used tar or dd in an uncommon and destructive way.

You don't "have to" use the examples, you can read them as get a feel, and read the captions to find the one that does what you want...

Which is faster and probably safer than scanning the documentation for individual flags and hopping you got the nuances right...

See, the two cases aren't:

(1) Thoroughly study man page -> (2) Become expert at the command's options (3) try command secure in your mastery of it

vs

(2) Check tldr examples -> (2) try command

They're rather:

(1) Open man page, (2) scan and skim the man page and the dozens of irrelevant flags, caveats, and obscure options, until you find some flags that look to do what you want, (3) half-read them, (4) try command

vs

(2) Check tldr examples, (2) find an example that does what you want (which is usually one of the covered use cases) (3) try the command using the example syntax

I guess you could consider https://github.com/tldr-pages/tldr.

I personally wouldn't touch that, but that's related to my allergies to JS ecosystem and predisposition to panic attacks when I see stuff like that https://github.com/tldr-pages/tldr/blob/master/package-lock.....

I've switched to tealdeer: same database, rust implementation.

https://github.com/dbrgn/tealdeer

I'm generally satisfied by ZSH inline options summary, but I'm happy to see a sane instantiation of this, it clearly fits a need. Thanks for the pointer (and sorry for the troll :/).

"ZSH inline options summary"?

TIA if you could explain; is it native zsh or a plugin?

There's also tealdeer in rust.