From owner-freebsd-current@FreeBSD.ORG Tue Dec 12 01:57:19 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 EB15A16A529 for ; Tue, 12 Dec 2006 01:57:19 +0000 (UTC) (envelope-from marius@alchemy.franken.de) Received: from alchemy.franken.de (alchemy.franken.de [194.94.249.214]) by mx1.FreeBSD.org (Postfix) with ESMTP id 9740043E0F for ; Tue, 12 Dec 2006 01:55:13 +0000 (GMT) (envelope-from marius@alchemy.franken.de) Received: from alchemy.franken.de (localhost [127.0.0.1]) by alchemy.franken.de (8.13.8/8.13.8/ALCHEMY.FRANKEN.DE) with ESMTP id kBC1uRje068715; Tue, 12 Dec 2006 02:56:27 +0100 (CET) (envelope-from marius@alchemy.franken.de) Received: (from marius@localhost) by alchemy.franken.de (8.13.8/8.13.8/Submit) id kBC1uRCt068714; Tue, 12 Dec 2006 02:56:27 +0100 (CET) (envelope-from marius) Date: Tue, 12 Dec 2006 02:56:27 +0100 From: Marius Strobl To: Scott Long Message-ID: <20061212015627.GL86517@alchemy.franken.de> 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> <457E034A.7080103@samsco.org> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <457E034A.7080103@samsco.org> User-Agent: Mutt/1.4.2.2i 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:57:20 -0000 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@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. 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