Date:        Wed, 19 Jul 2000 03:16:24 -0500 (CDT)
    From:        Richard Rauch <rkr@rkr.kcnet.com>
    Message-ID:  <Pine.NEB.4.21.0007190138020.29440-100000@rkr.kcnet.com>

I disagree with this part of your message...

  | Some kind of linking mechanism would be nice, though.  See also's don't
  | really cut it:  [...]

Man pages should be concise, precise, and complete documentation of any
single system feature (except where being complete would take hundreds
of pages - there external doc should fill in the details, and the man
page should give an overview).

If you have to go view some other page to get the specific details of a
particular system feature, then the man page is broken.  See Also references
give other related, or background information that can be useful for
general understanding, or which provide documentation on something that
is likely to be useful in conjunction with the subject of the current page.

To put this into the context of the errno value discussion - anything that
is specific to a particular sys call needs to be fully documented in the
man page for that sys call.  On the other hand, anything which is just
general common error information, not specific to the sys call being
documented should not be mentioned (or at least, need not be mentioned).
A "see also" should refer to intro(2) where general information about all
system calls is to be found, including a complete list of all the possible
errors.

Under no circumstances should reading a man page be even suggesting that
readers should perhaps go read some other man page or doc in order to
complete the information about the thing being documented (with the
sole exception of referring to some complete system doc where the complete
doc would be too much for the man page - like for programming languages,
editors, etc).

On the other hand ...

  | Perhaps instead of trying to force the man pages to support _all_ system
  | documentation, we could revive the PSD/USD/etc. documents [...]

That I agree with completely - as much as possible, we should have
architecture, and other docs, and be making those available (eg: someone
should ask Kirk for permission to include his softdeps paper, ...)

kre