Earlier quoted context omitted.
The traditional structure of man pages (Synopsis, Description, Options, and maybe Examples at the end) is just Bad. No documentation expert would write doc this way, not even as a reference, say nothing of a tutorial. The synopsis typically lists a bunch of command-line variations with literally no context, not even a line of commentary to tell the difference between the variations. Then comes a description, which is…
Man is like javadocs: useless unless you already know what you are doing, and then usually a wordy paraphrase of the method signature :( Even as a reference manual, man is bad though. If I'm looking for option "-e" of the test command, why can't I do $ man test -e -e file True if file exists (regardless of type). That seems more efficient, more unix-friendly and not too much to ask. I get this is an historical tool t…
I've found javadocs enormously helpful when I was learning Java 20 years ago. But then again, I also like man pages and use them a lot.
If I'm looking for option "-e" of the test command, here's what I would do:
$ man test
Of course, you could also just define a bash function for the functionality you're after like so:
mano() {
man "$1" | grep -A1 -- "$2"
}
$ mano test -e
