Comment by dfabulich

A lot of us are "newbies" of "tar", "find", "[" and many others after years and years using *nix. According to the anti-usability mindset, this means that the users are wrong and ought to be changed, and not an hint that we should rethink how we write and consume documentation.

Edit: the wording was angrier than it needed to be. A concrete example of a better documentation tool : https://kapeli.com/dash

Good projects should have tutorials and complete references online in addition to man pages.

A well written manual page requires no additional tutorials, for they will be included in the text’s corpus.

Writing good documentation for one’s software is almost more important than writing the software itself; don’t force the user to have to run around the internet; be comprehensive in the manual.

Why should good documentation not be bundled with the product?

I share your reactions, with the exception that examples first or last seems irrelevant when using a man page—Sometimes it’s better first because you simply need a reminder how to use the command, and other times you need to read more of the description to catch the warnings before you use the command for the first or infrequent time. But if you follow the General best practice to read the whole of some documentation before you use a command, then this too seems irrelevant.

That said, if you’re writing, reviewing, and editing documentation, the traditional structure is hierarchical and consistent—-which is good.

> 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.

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.

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.