I personally find the man pages very dense and poorly organized. `man grep` for example is my own personal nightmare. I think the man pages should introduce a policy of simple usage examples instead of throwing 99% of information you don't care about at you at once. Something like http://bropages.org/
I have to read the info docs before I can read the docs I wanted to read. They're also divided up into little pieces unnecessarily, so I have to think rather than scroll until my eye catches what I need.
info is up there with inkjet printers and trying to make sound work worth a damn in Linux on my list of things that have frustrated me regularly for the past 20 years.
I have a small script in my ~/bin that pipes `info --subnodes "$@"` into less. That way I don't have to remember all the keys, and the whole output is like a big man page. Although on Debian and Ubuntu the info pages are usually not available by default anyway due to the "GNU docs are non-free"-decision Debian made a few years ago.
I find that the Man pages on BSD-derived systems are generally quite exceptional, where as GNU-based systems seem to be less so. `info` seems to be their attempt at making a better `man`, but it's pretty hit-or-miss if a Linux-based project thats not from the FSF supports infopages over manpages.
But the one thing I hate about info is that they often change the "see also" near the end of a man page from a list of similar or related commands that you might want to also read, to an invitation to use the info chapter for that command. Aarrrggghhh!
man less
...
SEE ALSO
lesskey(1)
man ls
...
SEE ALSO
The full documentation for ls is maintained as a Texinfo manual.
If the info and ls programs are properly installed at your site, the command
info coreutils 'ls invocation'
should give you access to the complete manual.
Why hijack a useful section? Why not just add a "SEE INFO" section?
Seconded. When I was starting out in Solaris sysadmin, I'd read the Solaris man pages for local details, but the OpenBSD pages to see what the hell the command actually thought it was doing.
Comments
I personally find the man pages very dense and poorly organized. `man grep` for example is my own personal nightmare. I think the man pages should introduce a policy of simple usage examples instead of throwing 99% of information you don't care about at you at once. Something like http://bropages.org/
Perhaps you would find info pages more useful. For example, 'info grep'.
I hate info.
I have to read the info docs before I can read the docs I wanted to read. They're also divided up into little pieces unnecessarily, so I have to think rather than scroll until my eye catches what I need.
info is up there with inkjet printers and trying to make sound work worth a damn in Linux on my list of things that have frustrated me regularly for the past 20 years.
I have a small script in my ~/bin that pipes `info --subnodes "$@"` into less. That way I don't have to remember all the keys, and the whole output is like a big man page. Although on Debian and Ubuntu the info pages are usually not available by default anyway due to the "GNU docs are non-free"-decision Debian made a few years ago.
I find that the Man pages on BSD-derived systems are generally quite exceptional, where as GNU-based systems seem to be less so. `info` seems to be their attempt at making a better `man`, but it's pretty hit-or-miss if a Linux-based project thats not from the FSF supports infopages over manpages.
info itself is merely annoying (to me).
But the one thing I hate about info is that they often change the "see also" near the end of a man page from a list of similar or related commands that you might want to also read, to an invitation to use the info chapter for that command. Aarrrggghhh!
Why hijack a useful section? Why not just add a "SEE INFO" section?I've started using "bro", and really like it.
If you want high quality man pages go look at openBSD base, truly exceptional.
Even then, man pages nowadays are massive compared to what they were intended to be, complexity is the bane of all software.
Seconded. When I was starting out in Solaris sysadmin, I'd read the Solaris man pages for local details, but the OpenBSD pages to see what the hell the command actually thought it was doing.