Re: mk48txx

Marius Strobl wrote:
> 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
> 

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