From owner-freebsd-current@FreeBSD.ORG Tue Dec 12 01:28:34 2006 Return-Path: X-Original-To: current@freebsd.org Delivered-To: freebsd-current@FreeBSD.ORG Received: from mx1.FreeBSD.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id D57B916A403 for ; Tue, 12 Dec 2006 01:28:34 +0000 (UTC) (envelope-from scottl@samsco.org) Received: from pooker.samsco.org (pooker.samsco.org [168.103.85.57]) by mx1.FreeBSD.org (Postfix) with ESMTP id A188243E5B for ; Tue, 12 Dec 2006 01:17:05 +0000 (GMT) (envelope-from scottl@samsco.org) Received: from [192.168.254.11] (phobos.samsco.home [192.168.254.11]) (authenticated bits=0) by pooker.samsco.org (8.13.4/8.13.4) with ESMTP id kBC1I5q9093337; Mon, 11 Dec 2006 18:18:11 -0700 (MST) (envelope-from scottl@samsco.org) Message-ID: <457E034A.7080103@samsco.org> Date: Mon, 11 Dec 2006 18:18:02 -0700 From: Scott Long User-Agent: Mozilla/5.0 (Macintosh; U; Intel Mac OS X; en-US; rv:1.8.0.7) Gecko/20060910 SeaMonkey/1.0.5 MIME-Version: 1.0 To: Marius Strobl References: <20061209185539.GA34399@alchemy.franken.de> <20061209201438.B42195@localhost> <20061209210629.GG86517@alchemy.franken.de> <20061210.231137.-1749707382.imp@bsdimp.com> <20061212005753.GJ86517@alchemy.franken.de> In-Reply-To: <20061212005753.GJ86517@alchemy.franken.de> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit X-Spam-Status: No, score=-1.4 required=3.8 tests=ALL_TRUSTED autolearn=failed version=3.1.1 X-Spam-Checker-Version: SpamAssassin 3.1.1 (2006-03-10) on pooker.samsco.org Cc: nick@van-laarhoven.org, "M. Warner Losh" , current@freebsd.org Subject: Re: mk48txx X-BeenThere: freebsd-current@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Discussions about the use of FreeBSD-current List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 12 Dec 2006 01:28:34 -0000 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 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