From owner-cvs-src@FreeBSD.ORG Wed Sep 27 08:22:46 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 0A05D16A407; Wed, 27 Sep 2006 08:22:46 +0000 (UTC) (envelope-from danger@rulez.sk) Received: from mail.rulez.sk (DaEmoN.RuLeZ.sK [84.16.32.226]) by mx1.FreeBSD.org (Postfix) with ESMTP id E401143D53; Wed, 27 Sep 2006 08:22:43 +0000 (GMT) (envelope-from danger@rulez.sk) Received: from localhost (localhost [127.0.0.1]) by mail.rulez.sk (Postfix) with ESMTP id 883FF1CD1A; Wed, 27 Sep 2006 10:22:42 +0200 (CEST) X-Virus-Scanned: by amavisd-new at mail.rulez.sk X-Spam-Score: -1.745 X-Spam-Level: X-Spam-Status: No, score=-1.745 tagged_above=-999 required=5 tests=[ALL_TRUSTED=-1.8, AWL=1.693, BAYES_00=-2.599, NO_REAL_NAME=0.961] Received: by mail.rulez.sk (Postfix, from userid 80) id E56A21CC6D; Wed, 27 Sep 2006 10:22:34 +0200 (CEST) Received: from cpuxp-d08.cpu.elf.stuba.sk (cpuxp-d08.cpu.elf.stuba.sk [147.175.100.85]) by mail.rulez.sk (Horde MIME library) with HTTP; Wed, 27 Sep 2006 10:22:34 +0200 Message-ID: <20060927102234.dsupin91usswg4s0@mail.rulez.sk> Date: Wed, 27 Sep 2006 10:22:34 +0200 From: danger@rulez.sk To: Christian Brueffer References: <200609261959.k8QJxqkh068350@repoman.freebsd.org> <20060926202339.GA2039@haakonia.hitnet.RWTH-Aachen.DE> In-Reply-To: <20060926202339.GA2039@haakonia.hitnet.RWTH-Aachen.DE> MIME-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1; DelSp="Yes"; format="flowed" Content-Disposition: inline Content-Transfer-Encoding: quoted-printable User-Agent: Internet Messaging Program (IMP) H3 (4.1.1) Cc: cvs-src@FreeBSD.org, Daniel Gerzo , src-committers@FreeBSD.org, cvs-all@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:22:46 -0000 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 wh= ere > 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 =20 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 =20 support for something in kernel _or_ load it as a module which would =20 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=3D"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 =20 after I have committed it (note, that I had an approval from my =20 mentors). Tom is native and he told that while it does not really =20 sounds correct, it is correct English, but depends on the context as =20 you have said. I have mailed my mentors and Ruslan with re-worded =20 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 =20 wanted to commit the change to the example.4 first and after that =20 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 =20 not going to argue about that or being upset or something, I will =20 revert the change and go ahead and start working on something else. > - Christian --=20 Best regards, Daniel -------------------------------------------------------- This message was sent from rulez.sk webamil using Horde.