> If I'm looking for option "-e" of the test command, why can't I do...

https://gist.github.com/alphapapa/3cba3ff196147ad42bac#file-...

    $ man test -e

           STRING1 != STRING2
                  the strings are not equal

           INTEGER1 -eq INTEGER2
                  INTEGER1 is equal to INTEGER2

           INTEGER1 -ge INTEGER2
                  INTEGER1 is greater than or equal to INTEGER2
    --

           INTEGER1 -ne INTEGER2
                  INTEGER1 is not equal to INTEGER2

           FILE1 -ef FILE2
                  FILE1 and FILE2 have the same device and inode numbers

           FILE1 -nt FILE2
                  FILE1 is newer (modification date) than FILE2
    --

           -d FILE
                  FILE exists and is a directory

           -e FILE
                  FILE exists

           -f FILE
                  FILE exists and is a regular file

De gustibus non est disputandum.

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

and then "/-e". Searching within a document is a commonly required skill in so many situations that I don't even think twice when applying it in man pages.

Of course, you could also just define a bash function for the functionality you're after like so:

    mano() {
        man "$1" | grep -A1 -- "$2"
    }

and then do

    $ mano test -e

or something along those lines.

That's full text search, not having directly the argument definition. If you search "-l" in "man ls", it will be only your 8th occurence.

Sure, you're right, it's not the same thing. I just gave a simple example of something that's close, but I'm not even using a bash function like that myself. If I did, though, I guess the 8th occurrence wouldn't be so bad in my book, since the results can be scanned rather quickly.

You could always make your function more clever, e.g.:

    function mano() {
        man "$1" | grep -A1 -- "$2\\b"
    }

or

    function mano() {
        man "$1" | grep -A1 -- "$2  "
    }

but most probably, you will still run into edge cases that won't work properly. For instance, only one of the two versions above still works with "test -e".

You can actually search for ' -l' (two spaces in front) and abuse the man layout engine to find the point at which the flag itself is defined. Makes the man pages a lot more useful in my opinion.

If your idea of what man is comes from using Linux, then you really haven't had a good exposure to what good documentation can be. Try Solaris or FreeBSD.

Indeed!

I agree with your point. There should be easier ways of doing some things in Unix. But since there are not (for some things, anyway, and I say this as a long-time Unix guy), sometimes, scripts can help. Here is one example by me:

m, a Unix shell utility to save cleaned-up man pages as text:

https://jugad2.blogspot.in/2017/03/m-unix-shell-utility-to-s...

This tiny script lets you generate man pages as cleaned-up text, saves them in a ~/man directory, and you can from then on, open them in your favorite text editor or even pager (less/more/pg/etc.) and view them. Created it out of real-life personal need some years ago, on a Unix system, but is still useful on Linux and other Unix-like systems today.

  man test | grep -- ‘ -e’

UNIX already has that as you can see. You just need to learn the target substrate you’re using.