Date:        Sun, 14 Oct 2001 18:05:45 -0400 (EDT)
    From:        woods@weird.com (Greg A. Woods)
    Message-ID:  <20011014220545.EDA5AEF@proven.weird.com>

  | If that's true then it's quite likely NetBSD will run on systems where
  | read(2) could return EINVAL because there was more than SSIZE_MAX bytes
  | to return....  if not right away then in the near future...  :-)

Whether this will ever happen or not isn't important - that the manual page
says it might happen is important, because clearly this kind of thing is
possible sometimes (the best test will probably what happens with Intel's
64 bit processor, if it ever appears, which I assume will continue to be
able to run 8088 binaries... and so on which NetBSD's i386 userland might
continue to be appropriate - or running sparc binaries on sparc64 systems).

But you still haven't given any (to me) credible reason why you need the
man pages to say exactly how the system works today.   I can't think of
any rational requirement for that at all.

Stds docs tell what a posix (or ansi c, or whatever, as relevant) system
will do - that's what you need for writing truly portable code.

The NetBSD (or any other system) man pages should document what any NetBSD
system will do, that is, mostly (one hopes) the same as the standards docs,
but with lots of the missing parts (read(2) ...) added, and the "left to
the implementation to define" parts defined as well, as much as they can be.
This is essentially the NetBSD standard - the interface that only changes
after much debate as to the usefulness of the change, compared to its costs.

Both of those have their obvious uses.   I'm still looking for any sane use
of the "my system will do this today, even if it will be different tommorow"
type of documentation.   For curiosity (or those interested in making changes),
there's the source, it provides all the detail that you're ever going to need.
What other rational use is there?

kre