Re: stat(1) manpage displays non-existant (?) option

[Robert Elz <kre%munnari.OZ.AU@localhost>]

    Date:        Sun, 3 Jan 2016 22:31:04 +0200
    From:        Rares Aioanei <schaiba%gmail.com@localhost>
    Message-ID:  <CABasXZWBD1FcfzYJ17ykMzLQGw46qo0pQQaheSTzTVFjT7O3Rg%mail.gmail.com@localhost>

  | However, the manpage not only isn't as clear,
  | but doesn't specify clearly _how_ to invoke stat as readlink.

Always start with the SYNOPSIS ...

     stat [-FLnq] [-f format | -l | -r | -s | -x] [-t timefmt] [file ...]
     readlink [-fnqsv] [file ...]

That shows that (in this case) the man page describes 2 commands, stat
and readlink, and what the options are for each.   (When one manpage
describes multiple commands, it often implies that the commands come from
the same source files, but that isn't always the case - nor is the
converse.)

Other man pages describe more (or less) related commands, or
in sections 2 & 3, functions (or in 4, devices) in a similar manner.

The DESCRIPTION section then gives info on just what all of that means,
but to avoid repetition, doesn't always specify everything separately
for every command or function.

In this case, the different interpretation of -f for readlink is called
out explicitly, but all the other options, which, when they apply, mean
the same to both commands, are described just once.

Rant (skip the rest of the message if you like):

You do get used to reading (well written, unfortunately not all are) man
pages quite quickly - they convey (or should) precise information, briefly
and concisely, so that you can quickly work out exactly what the
command (or function) and every option it has does.

They are however, not cookbooks, the intent is not, or should not be,
to tell you how to do x, that you are supposed to work out for yourself.

That's important because there are so many possible x's that giving
instructions for every one would make almost any man page unmanageable.
Giving instructions for only some only works if you happen to want to
do one of the few operations that is described.

When needed there are, or should be, other tutorial docs (or even books)
that explain and teach the more complex commands, etc.  Some intermediate
cases are handled by including an EXAMPLES section in the man page.

kre