Yeah, I really don't understand the aversion to examples. The sorta-standard format for man pages is... extremely confusing, even after a decade of using them.

“you should be smart enough to figure this out from here” bravado probably for some cases.

You do realize that writing good docs takes time, skill, and effort, right? Not to mention the docs you're scorning at was most likely written on someone's spare time who has no obligation to do so.

When you have some people not doing it, that's fine, they own their time. When you have have almost no one doing it, that's a cultural issue. I'm saying Linux/Unix man pages have inherent and probably very old cultural issues leading to a lack of baked-in examples.

Gnu stuff tends to be properly documented in info, not man. But yeah, loads of stuff just isn't well documented.

Stallman's sad devotion to that ancient religion... ITS has been effectively dead for how many decades now, but by god we're gonna force everybody to use a port of their online documentation system if we can!

At least we're past the bad old days when you'd open a man page and it would just be a stub saying "look at the info docs, IDIOT"

Some of the manpages for utillinux (e.g., chsh, useradd) are pretty barebones and don't include examples, but off the top of my head I can't think of a major GNU utility that doesn't have EXAMPLES sections in its manpages. GNU coreutils, find, sed, and grep all have such a section in their manuals.

What are you thinking of that is example-less?

GNU ls's manpage has no examples, but it's also a thousand words long so it hardly seems fair to characterize it as bare-bones.

All in all, I find that manpages on Linux are usually pretty good, particularly compared to systems like MacOS where many daemons and utilities seem to have no manpage at all. People are far too quick to slag manpages, which probably has something to do with the `man` utility itself being a bit archaic. Common Linux desktops could probably do a better job of advertising GUI-based manpage readers like khelpcenter.

I'd like slightly fancier system (no, not info), but being able to look things up without leaving the terminal is so underrated imo. It makes looking things up a lot faster.

POSIX ls's manpage has examples. Well, one example, of `-laRF`.

But also I can't imagine what good more examples will do anyway. `-lahR` cover the vast majority of common uses.

> -lahR` cover the vast majority of common uses.

For me, 99% of the time I use -ltrh and -ltrha. But instead of -R, I use other utilities like fzf, find, or tree. Tree is really nice for a quick overview of directory structures.

> Proper manuals have examples of use

This is what microsoft did well with powershell's help system. They have examples. Tons of them.

Why man pages do not is beyond me when most of the time, an example or two is all we need. I bet most people go to the man pages and then google for examples because the man pages weren't helpful.