Date: Tue, 12 Dec 2006 01:57:53 +0100 From: Marius Strobl <marius@alchemy.franken.de> To: "M. Warner Losh" <imp@bsdimp.com> Cc: nick@van-laarhoven.org, current@freebsd.org Subject: Re: mk48txx Message-ID: <20061212005753.GJ86517@alchemy.franken.de> In-Reply-To: <20061210.231137.-1749707382.imp@bsdimp.com> References: <20061209185539.GA34399@alchemy.franken.de> <20061209201438.B42195@localhost> <20061209210629.GG86517@alchemy.franken.de> <20061210.231137.-1749707382.imp@bsdimp.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On Sun, Dec 10, 2006 at 11:11:37PM -0700, M. Warner Losh wrote: > In message: <20061209210629.GG86517@alchemy.franken.de> > Marius Strobl <marius@alchemy.franken.de> writes: > : > : I favor having no man page over having something incomplete > : or inadequate like f.e. esp.4 or bus_space.9 as IMO wrong > : information can confuse way more and leaves a worse impression > : than no information at all. > > bus_space.9 isn't incomplete. The problem is that it is too complete > and general, if anything. It is hard to penetrate. I mentioned bus_space.9 as an example of a man page that I'd describe as inadequate; both the sections about mapping and unmapping as well as allocating and freeing bus space are still verbatim from the NetBSD rev. 1.9 one AFAICT, which describes concepts in these sections that don't really apply to FreeBSD. Granted, on some platforms like FreeBSD/i386 one can probably succeed in doing actual reads and writes by only using the functions mentioned in bus_space.9, but it totally fails to give the slightest hint (not even a .Xr) on how to obtain the bus space tag and handle the right way in FreeBSD, so it will actually work on all platforms, which is the whole point of the bus_space interface. The current bus_space.9 actually tells that some of its sections "may or may not apply to the FreeBSD version" and "many parts of the interface are unspecified", but that's essentially telling the user that she/he has to figure it out herself/himself, which IMO defeats the purpose of having a man page in the first place. Marius
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20061212005753.GJ86517>