Re: mk48txx

Marius Strobl wrote:
On Sun, Dec 10, 2006 at 11:11:37PM -0700, M. Warner Losh wrote:
In message: <20061209210629.GG86517@xxxxxxxxxxxxxxxxxx>
Marius Strobl <marius@xxxxxxxxxxxxxxxxxx> 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
_______________________________________________
freebsd-current@xxxxxxxxxxx mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-current
To unsubscribe, send any mail to "freebsd-current-unsubscribe@xxxxxxxxxxx"

Relevant Pages

  • Re: mk48txx
    ... I favor having no man page over having something incomplete ... to FreeBSD. ... to shame Warner into fixing it, I think that his free time is quite ... the notes Warner added to bus_space.9 I think he feels ...
    (freebsd-current)
  • Re: mk48txx
    ... I favor having no man page over having something incomplete ... to FreeBSD. ... on some platforms like FreeBSD/i386 ... is the whole point of the bus_space interface. ...
    (freebsd-current)
  • Re: mk48txx
    ... Marius Strobl writes: ... :> Sun? ... Enlightning. ... I favor having no man page over having something incomplete ...
    (freebsd-current)
  • Re: the future of sun4v
    ... Marius Strobl wrote: ... >>>developers that unsupported code should not be in CVS. ... >>Since there are no other current SPARC CPUs that FreeBSD can run on ... >>I don't have the knowledge or available time to maintain the sun4v ...
    (freebsd-stable)
  • Re: the future of sun4v
    ... Marius Strobl wrote: ... >>>developers that unsupported code should not be in CVS. ... >>Since there are no other current SPARC CPUs that FreeBSD can run on ... >>I don't have the knowledge or available time to maintain the sun4v ...
    (freebsd-current)