Date: Mon, 11 Dec 2006 18:18:02 -0700 From: Scott Long <scottl@samsco.org> To: Marius Strobl <marius@alchemy.franken.de> Cc: nick@van-laarhoven.org, "M. Warner Losh" <imp@bsdimp.com>, current@freebsd.org Subject: Re: mk48txx Message-ID: <457E034A.7080103@samsco.org> In-Reply-To: <20061212005753.GJ86517@alchemy.franken.de> References: <20061209185539.GA34399@alchemy.franken.de> <20061209201438.B42195@localhost> <20061209210629.GG86517@alchemy.franken.de> <20061210.231137.-1749707382.imp@bsdimp.com> <20061212005753.GJ86517@alchemy.franken.de>
next in thread | previous in thread | raw e-mail | index | archive | help
Marius Strobl wrote: > 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 > Hate to say it, but these things don't fix themselves. If you're hoping to shame Warner into fixing it, I think that his free time is quite spoken for. Mine is too, though I'd be happy to review corrections to it for technical and grammar correctness. Scott
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?457E034A.7080103>