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>
index | next in thread | previous in thread | raw e-mail
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
home |
help
Want to link to this message? Use this
URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20061211.183338.1120057412.imp>