From owner-cvs-all@FreeBSD.ORG Wed Sep 27 22:57:31 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 3C09316A403; Wed, 27 Sep 2006 22:57:31 +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 774ED43D93; Wed, 27 Sep 2006 22:57:27 +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 k8RMvPSH025285 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NOT); Wed, 27 Sep 2006 18:57:26 -0400 (EDT) (envelope-from trhodes@FreeBSD.org) Date: Wed, 27 Sep 2006 18:57:17 -0400 From: Tom Rhodes To: danger@rulez.sk Message-Id: <20060927185717.69661a1c.trhodes@FreeBSD.org> In-Reply-To: <20060927102234.dsupin91usswg4s0@mail.rulez.sk> References: <200609261959.k8QJxqkh068350@repoman.freebsd.org> <20060926202339.GA2039@haakonia.hitnet.RWTH-Aachen.DE> <20060927102234.dsupin91usswg4s0@mail.rulez.sk> 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: [Back it out] was: 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 22:57:31 -0000 On Wed, 27 Sep 2006 10:22:34 +0200 danger@rulez.sk wrote: Daniel, Please just back this commit out. While I don't disagree with the commit, I do see at least one back out request. In the project, we back out after a request if we are unable to change the requester's mind. Leaving it in is just not how we do things around here and I would prefer not to become the very person who annoys the hell out of me. We'll put our heads together and see if there is a better way of wording it so everyone is happy. Besides, I need to prepare for a conference - leaving tonight - so I need to stop being difficult around here and prepare to be difficult elsewhere. Thanks, -- Tom Rhodes > Quoting Christian Brueffer : > > > 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). > > We want to aviod to use words like "you", "your" and so on. I have > talked about it with Ruslan and my mentors. > > >> | -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". > > I think it's certainly clear to users that they can either enable > support for something in kernel _or_ load it as a module which would > bring that support without need of kernel recompilation. > > > > >> | .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. > > Yes, I know about this issue as it was pointed by Ruslan a few hours > after I have committed it (note, that I had an approval from my > mentors). Tom is native and he told that while it does not really > sounds correct, it is correct English, but depends on the context as > you have said. I have mailed my mentors and Ruslan with re-worded > sentence that should fix that. > > > > > 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. > > > > It is standard that should be fixed :-) and I'm about to do that; I > wanted to commit the change to the example.4 first and after that > start with changes to the affected section 4 manual pages. > > But if there are more people that think that this change is wrong, I'm > not going to argue about that or being upset or something, I will > revert the change and go ahead and start working on something else. > > > - Christian > > -- > Best regards, > Daniel > > > > -------------------------------------------------------- > This message was sent from rulez.sk webamil using Horde. > > > -- Tom Rhodes