Date: Mon, 11 Dec 2006 18:33:38 -0700 (MST) From: "M. Warner Losh" <imp@bsdimp.com> To: scottl@samsco.org Cc: current@freebsd.org, nick@van-laarhoven.org Subject: Re: mk48txx Message-ID: <20061211.183338.1120057412.imp@bsdimp.com> In-Reply-To: <457E034A.7080103@samsco.org> References: <20061210.231137.-1749707382.imp@bsdimp.com> <20061212005753.GJ86517@alchemy.franken.de> <457E034A.7080103@samsco.org>
next in thread | previous in thread | raw e-mail | index | archive | help
In message: <457E034A.7080103@samsco.org>
Scott Long <scottl@samsco.org> writes:
: 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.
I'm happy to review things as well. I have very little free time
these days due to the baby, the merger, and the mad rush to get
product out ASAP.
I think you overgeneralize about the defects in bus_space. It tells
you the basics so you can figure it out yourself. Could it be better?
Sure. Is it better than nothing like we had before? Absolutely.
Warner
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20061211.183338.1120057412.imp>