[ On Thursday, October 11, 2001 at 21:20:00 (+0700), Robert Elz wrote: ]
> Subject: Re: wrap up of pipe(2) 
>
> If you were writing an application, and looking at the man page, and writing
> the code to conform, only to be told tomorrow that it has all changed, the
> man page has now been updated, and all your carefully planned code is now
> not correct, you wouldn't be very happy.

Ah, sorry, no, I most certainly would NOT!

If I want to learn how to write my code so that it will work portably on
a given set of platforms (or to a given platform standard) then I will
work with the appropriate documentation, be that the manual pages for
each platform, or the standards document for the platform standard, or
both.

I most certainly ALWAYS want the platform documentation delivered with a
given release to EXACTLY describe the implementation in that very release!

If it note any discrepancies with any standard, or any differences with
other common implementations then so much the better, but these notes
must explicitly mention that they are not describing the actual
implementation.

I've been writing and porting code between various types of systems,
including most every type of Unix variant, professionally and as a hobby,
now for many many many years (perhaps not quite as many as you yourself
have, but I suspect nearly so!), and there's NOTHING about system
documentation that frustrates me more than finding that it does not
describe the actual release-specific implementation!  I have my own
personal copies of the release specific documentation for many important
unix variants explicitly for the purpose of discovering implementation
differences!  I fully expect every new release of every system to come
with new releases of its documentation and for that new documentation to
always include descriptions of new features and changes to any previous
implementations (at least where such changes also change what must be
documented), as well as of course the regular documentation fixes too.

As almost everyone replying to this thread has said, there are ample
sources of information on general programming.  System manuals do not
need to be both implementation specific and generic guides.

The manual page will not change unless I also change the underlying
implementation I'm using.  If I change the underlying implementation
then I really Really REALLY do want its documentation to change
correspondingly.  If my application suddently somehow fails or behaves
unexpectedly then I want to be able to read in the new manual page how I
must change my application to work properly on the new system
implementation.

Any system documentation that does not exactly describe the underlying
implemenation and behaviour of the system is buggy, by definition.

> This also assumes that there is one common behaviour throughout all of
> NetBSD - and while that may very well be true now of the way pipe(2) works
> on all ports, there's no guarantee that it will stay that way.   The actual
> sys call conventions are MD - if NetBSD were to be ported to an architecture
> where returning two results from a syscall was very difficult, most likely
> the pipe(2) for that would actually pass in the address, and so EFAULT would
> be what was returned.  But I'd still expect i386/alpha/sparc ... to keep on
> generating a SEGV instead.

If that were to come to be then I would fully expect there either to be
platform specific manual pages for the call in question, or alternately
a very careful description of the platform differences, exactly as they
are currently implemented on each platform.

This is the case now for various platform specific features on NetBSD.

> For anyone who really wants to know what the implementation actually does,
> right now, for some particular architecture, there's always the source.

I can't quite believe you said that.  Of course there's always the
source, but the source is not the documentation!  Certainly in a system
which is supposedly distributed primarily as source the availablity of
the code is an important aspect to making the system more accessible and
easier to understand.  However if system documentation is to be supplied
then it must describe the way the system is implemented -- anything less
is useless as system documentation and may as well be maintained
separately and distributed separately!!!!

Why do you think it is that in *BSD the manual page sources were moved
into the same directories where the program sources are (with the
exception of the kernel)?  If I remember correctly the release notes of
the release where this first occurred stated explicitly that it was so
the documentation could be more easily and carefully maintained with,
and in conformance to, the implementation.

-- 
							Greg A. Woods

+1 416 218-0098      VE3TCP      <gwoods@acm.org>     <woods@robohack.ca>
Planix, Inc. <woods@planix.com>;   Secrets of the Weird <woods@weird.com>