Re: mk48txx

On Sun, Dec 10, 2006 at 11:11:37PM -0700, M. Warner Losh wrote:
> In message: <20061209210629.GG86517_at_alchemy.franken.de>
>             Marius Strobl <marius_at_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