Man pages are nice sometimes but oftentimes they have a lot of options and no examples. For advanced usage of some commonly used commands it's far easier to just look it up online, or perhaps with this tool. Example good man page is ps, and an example difficult to use one is gcc. Even though the gcc man page has all the options, it's very difficult to figure out which ones you need, whereas something like this (or commandlinefu) might show you the exact command you need with a description of how the different flags interact.
My pet hate is man pages where the tool has a lot of options, and in the manual the options are listed neither alphabetically nor by semantic grouping. "Hrm, what does '-l' do. I guess I'll search for it, and hit every other -l along the way..."
As someone who's written man pages, at least GNU is fucked unless you can get stuff directly into a distro bypassing upstream, the guy who runs the man pages project won't let you modify anything in case Paul Vixie returns from the dead and decided he cares about adding examples.
This is why people still commonly use deprecated options in resolv.conf, don't know ip equivalents of old ifconfig commands, and use more options in tar than are required.
I still maintain Debian has the best man pages of the Linuxes. If you ever try to man a program on a Debian system and there is no man page then it'll mention "man 7 undocumented" asks the user to file a bug report on the package. They encourage package maintainers to write man pages when the upstream package does not include them.
When I've had the misfortune of using RHEL or Centos is when I notice the quality of the Debian man pages—Redhat seems to lack Debian's drive to document upstream stuff.
The only time I've seen Debian's man pages regress is with the ImageMagick package. Its man pages used to be adequate (I believe it might have been a text conversion of the web site/detailed html docs), but now they are not (try to figure out the syntax for the -geometry option using only the man pages).
Back in the day I was impressed by the OpenStep man pages. They had pages for the kernel drivers which I really liked (ie, "man mt" or "man cu"), which showed all the IOCTLs you could call and explained how the interface worked. That might have been a BSD thing, I haven't seriously used a *BSD lately so I can't compare.
I always loved the man pages in OpenBSD because they do provide useful examples for most commands. Whether it's the OS for you... ymmv, I wouldn't choose an OS on this one feature, but I wish more man pages had built in examples.
Man pages are nice sometimes but oftentimes they have a lot of options and no examples. For advanced usage of some commonly used commands it's far easier to just look it up online, or perhaps with this tool. Example good man page is ps, and an example difficult to use one is gcc. Even though the gcc man page has all the options, it's very difficult to figure out which ones you need, whereas something like this (or commandlinefu) might show you the exact command you need with a description of how the different flags interact.
My pet hate is man pages where the tool has a lot of options, and in the manual the options are listed neither alphabetically nor by semantic grouping. "Hrm, what does '-l' do. I guess I'll search for it, and hit every other -l along the way..."
Yeah, pretty annoying, if you use less as a pager for your manpages, you can try:
but it's kind of annoying that you have to use regular expressions to find what you are looking for faster.
EDIT: it may work in more (the default pager) but I haven't tried it.
As someone who's written man pages, at least GNU is fucked unless you can get stuff directly into a distro bypassing upstream, the guy who runs the man pages project won't let you modify anything in case Paul Vixie returns from the dead and decided he cares about adding examples.
This is why people still commonly use deprecated options in resolv.conf, don't know ip equivalents of old ifconfig commands, and use more options in tar than are required.
Any suggestions?
Two suggestions, in fact.
First, you need to read more Dilbert :) http://dilbert.com/strips/comic/1995-06-24/
Second, have a look at the OpenBSD man pages if you want to know why a suspenders-and-beard-condescending-unix-user would be dismissive of this.
Hint: The EXAMPLES section in man pages solved this a few decades ago :)
I still maintain Debian has the best man pages of the Linuxes. If you ever try to man a program on a Debian system and there is no man page then it'll mention "man 7 undocumented" asks the user to file a bug report on the package. They encourage package maintainers to write man pages when the upstream package does not include them.
When I've had the misfortune of using RHEL or Centos is when I notice the quality of the Debian man pages—Redhat seems to lack Debian's drive to document upstream stuff.
The only time I've seen Debian's man pages regress is with the ImageMagick package. Its man pages used to be adequate (I believe it might have been a text conversion of the web site/detailed html docs), but now they are not (try to figure out the syntax for the -geometry option using only the man pages).
Back in the day I was impressed by the OpenStep man pages. They had pages for the kernel drivers which I really liked (ie, "man mt" or "man cu"), which showed all the IOCTLs you could call and explained how the interface worked. That might have been a BSD thing, I haven't seriously used a *BSD lately so I can't compare.
Freebsd for one. Solaris was quite good as well back in the day.
OP made a Dilbert reference. And the Dilbert strip probably referenced a long-running joke.
I always loved the man pages in OpenBSD because they do provide useful examples for most commands. Whether it's the OS for you... ymmv, I wouldn't choose an OS on this one feature, but I wish more man pages had built in examples.