Re: mk48txx

On Mon, Dec 11, 2006 at 06:18:02PM -0700, Scott Long wrote:
> 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.

No, that absolutely wasn't my intention. I originally just
wanted to express that I prefer to add good man pages from
the beginning instead of something that I can't honestly
describe as useable and appropriate myself (and judging
the notes Warner added to bus_space.9 I think he feels
similarly about that man page; if not I apologise). Note
that originally this was also about the missing man page
for the API of a driver that I did touch but not initially
add. That didn't keep me from doing a man page in the past
but my time is limited also.

Marius