From owner-cvs-all@FreeBSD.ORG Wed Sep 27 07:41:33 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 5B03716A51A; Wed, 27 Sep 2006 07:41:33 +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 7829643D53; Wed, 27 Sep 2006 07:41:32 +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 k8R7fU1K019843 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NOT); Wed, 27 Sep 2006 03:41:31 -0400 (EDT) (envelope-from trhodes@FreeBSD.org) Date: Wed, 27 Sep 2006 03:41:24 -0400 From: Tom Rhodes To: Christian Brueffer Message-Id: <20060927034124.2c57b517.trhodes@FreeBSD.org> In-Reply-To: <20060926202339.GA2039@haakonia.hitnet.RWTH-Aachen.DE> References: <200609261959.k8QJxqkh068350@repoman.freebsd.org> <20060926202339.GA2039@haakonia.hitnet.RWTH-Aachen.DE> 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 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 07:41:33 -0000 On Tue, 26 Sep 2006 22:23:39 +0200 Christian Brueffer wrote: > On Tue, Sep 26, 2006 at 07:59:52PM +0000, Daniel Gerzo wrote: > > danger 2006-09-26 19:59:52 UTC > > > > FreeBSD src repository (doc committer) > > > > Modified files: > > share/examples/mdoc example.4 > > Log: > > Remove second person from the sentece and rephrase a bit. > > > > Approved by: trhodes (mentor), keramida (mentor) > > > > Revision Changes Path > > 1.26 +6 -8 src/share/examples/mdoc/example.4 > > I don't agree to these changes, see below for details (also I don't see where > exactly you removed second person usage, it's still being used in the new > version). > > > | =================================================================== > > | RCS file: /usr/local/www/cvsroot/FreeBSD/src/share/examples/mdoc/example.4,v > > | retrieving revision 1.25 > > | retrieving revision 1.26 > > | diff -u -p -r1.25 -r1.26 > > | --- src/share/examples/mdoc/example.4 2006/09/18 15:18:54 1.25 > > | +++ src/share/examples/mdoc/example.4 2006/09/26 19:59:52 1.26 > > | @@ -22,7 +22,7 @@ > > | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF > > | .\" SUCH DAMAGE. > > | .\" > > | -.\" $FreeBSD: /usr/local/www/cvsroot/FreeBSD/src/share/examples/mdoc/example.4,v 1.25 2006/09/18 15:18:54 ru Exp $ > > | +.\" $FreeBSD: /usr/local/www/cvsroot/FreeBSD/src/share/examples/mdoc/example.4,v 1.26 2006/09/26 19:59:52 danger Exp $ > > | .\" > > | .\" Note: The date here should be updated whenever a non-trivial > > | .\" change is made to the manual page. > > | @@ -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? > > > | .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. > > IMHO the SYNOPSIS section in section 4 manpages is kind of a standard > now, as it's being used in the majority of section 4 manpages. > Changes to it should not be made without _good_ reason and with a sweep > through all manpages that use it. Among other things, the purpose of > this section is to achieve consistency across section 4 manpages. The purpose of this file is to provide an example for people who are going to write section four manual pages; however, no one really "has" to follow this "lead." -- Tom Rhodes