From owner-cvs-all@FreeBSD.ORG Wed Sep 27 08:15:49 2006 Return-Path: X-Original-To: cvs-all@FreeBSD.org Delivered-To: cvs-all@FreeBSD.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 3619316A417; Wed, 27 Sep 2006 08:15:49 +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 8134A43D6A; Wed, 27 Sep 2006 08:15:40 +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 k8R8FYWK020094 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NOT); Wed, 27 Sep 2006 04:15:37 -0400 (EDT) (envelope-from trhodes@FreeBSD.org) Date: Wed, 27 Sep 2006 04:15:26 -0400 From: Tom Rhodes To: Ceri Davies Message-Id: <20060927041526.6b33a348.trhodes@FreeBSD.org> In-Reply-To: <20060927075314.GQ54669@submonkey.net> References: <200609261959.k8QJxqkh068350@repoman.freebsd.org> <20060926202339.GA2039@haakonia.hitnet.RWTH-Aachen.DE> <20060927034124.2c57b517.trhodes@FreeBSD.org> <20060927075314.GQ54669@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-all@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: CVS commit messages for the entire tree List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 27 Sep 2006 08:15:49 -0000 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. ;) Seriously though, why handle one case any differently than another? We should be fair here, and the above version will work for anything ... although, to be exact, we should probably use: "place the following line(s) in the kernel configuration file:" > > > > > | .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. -- Tom Rhodes