From owner-cvs-src@FreeBSD.ORG Wed Sep 27 08:54:26 2006 Return-Path: X-Original-To: cvs-src@FreeBSD.org Delivered-To: cvs-src@FreeBSD.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id C612F16A403; Wed, 27 Sep 2006 08:54:26 +0000 (UTC) (envelope-from trhodes@FreeBSD.org) Received: from pittgoth.com (ns1.pittgoth.com [216.38.206.188]) by mx1.FreeBSD.org (Postfix) with ESMTP id 64E9743D53; Wed, 27 Sep 2006 08:54:26 +0000 (GMT) (envelope-from trhodes@FreeBSD.org) Received: from localhost (net-ix.gw.ai.net [205.134.160.6] (may be forged)) (authenticated bits=0) by pittgoth.com (8.13.6/8.13.6) with ESMTP id k8R8sOo9020410 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NOT); Wed, 27 Sep 2006 04:54:25 -0400 (EDT) (envelope-from trhodes@FreeBSD.org) Date: Wed, 27 Sep 2006 04:54:17 -0400 From: Tom Rhodes To: Ceri Davies Message-Id: <20060927045417.639f3db1.trhodes@FreeBSD.org> In-Reply-To: <20060927084514.GR54669@submonkey.net> References: <200609261959.k8QJxqkh068350@repoman.freebsd.org> <20060926202339.GA2039@haakonia.hitnet.RWTH-Aachen.DE> <20060927034124.2c57b517.trhodes@FreeBSD.org> <20060927075314.GQ54669@submonkey.net> <20060927041526.6b33a348.trhodes@FreeBSD.org> <20060927084514.GR54669@submonkey.net> Organization: The FreeBSD Project X-Mailer: Sylpheed version 1.0.6 (GTK+ 1.2.10; i386-portbld-freebsd7.0) Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Cc: cvs-src@FreeBSD.org, danger@FreeBSD.org, src-committers@FreeBSD.org, cvs-all@FreeBSD.org, brueffer@FreeBSD.org Subject: Re: cvs commit: src/share/examples/mdoc example.4 X-BeenThere: cvs-src@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: CVS commit messages for the src tree List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 27 Sep 2006 08:54:27 -0000 On Wed, 27 Sep 2006 09:45:14 +0100 Ceri Davies wrote: > On Wed, Sep 27, 2006 at 04:15:26AM -0400, Tom Rhodes wrote: > > On Wed, 27 Sep 2006 08:53:14 +0100 > > Ceri Davies wrote: > > > > > On Wed, Sep 27, 2006 at 03:41:24AM -0400, Tom Rhodes wrote: > > > > On Tue, 26 Sep 2006 22:23:39 +0200 > > > > Christian Brueffer wrote: > > > > > > > > > | @@ -33,11 +33,9 @@ > > > > > > | .Nm example > > > > > > | .Nd "example device driver manual page" > > > > > > | .Sh SYNOPSIS > > > > > > | -To compile the > > > > > > | -.Ns Nm > > > > > > | -driver into the kernel, > > > > > > | -place the following lines in the > > > > > > | -kernel configuration file: > > > > > > | +To enable support for > > > > > > | +.Ns Nm , > > > > > > | +place the following lines in the kernel configuration file: > > > > > > > > > > The formulation used before was much more accurate WRT the distinction > > > > > we make between compiling something into the kernel and loading it as a > > > > > module. If we load something as a module we also "enable support for > > > > > it". > > > > > > > > What about in cases where other hoops must be jumped before the > > > > driver/feature/whatever is really supported? > > > > > > They can be special cased in the real manual. In the wider sense, > > > kldload is the easiest way to enable support for something, and I know > > > that I'm personally well past encouraging users to recompile the kernel > > > just to get, for example, sound working when a simple kldload does the > > > job just as well in most cases. > > > > That is of course that "something" has a module. ;) > > Well yes, which is why the previous text explicitly said "to compile .Nm > into the kernel", because that's what the example does. > > > Seriously though, why handle one case any differently than > > another? > > Compiling something into the kernel and loading a module are different, > that's why, and we should be clear about the distinction (because, as > you state, some modules don't exist). You're right we should. How about "To ... the ... ABC (or XYZ or ...)? > > > > > > > | .Bd -ragged -offset indent > > > > > > | .Cd "device example" > > > > > > | .Cd "options EXAMPLE_DEBUG" > > > > > > | @@ -45,9 +43,9 @@ kernel configuration file: > > > > > > | .Pp > > > > > > | Alternatively, to load the > > > > > > | .Ns Nm > > > > > > | -driver as a > > > > > > | -module at boot time, place the following line in > > > > > > | -.Xr loader.conf 5 : > > > > > > | +as a module at boot time, add the following line into the > > > > > > | +.Xr loader.conf 5 > > > > > > | +file: > > > > > > | .Bd -literal -offset indent > > > > > > | example_load="YES" > > > > > > | .Ed > > > > > > > > > > > > > > > > Removing "driver" here is wrong. "...to load the .Nm..." what, the .Nm > > > > > driver? The .Nm utility? It's just incorrect to rely on context here > > > > > and it makes the sentence sound really awkward. > > > > > > > > Leaving driver here is wrong. > > > > > > Not if you also leave the word "the" before .Nm. > > > > Then we should bloat it to handle "the XXX driver," "the XXX > > subsystem," "the XXX system," etc. To be honest, the sentence > > sounds better to me this way. And putting "driver" back in > > just does what Christian says it's there to prevent. We should > > not really "rely on the context" here, so I agree with Christian. > > We shouldn't believe that it will always be a "driver." > > > > In any sense, it's still just an "example." We are arguing over > > an "example" people. > > No, we're arguing over grammar. The sentence currently renders as > something like: > > Alternatively, to load the fxp(4) as a module at boot time... > > That's wrong. Getting rid of "the" works. I like "enable" in the first bit, and I'll agree "the" should go, even though your argument works in some cases but fails in others. -- Tom Rhodes