Date: Wed, 27 Sep 2006 18:57:17 -0400 From: Tom Rhodes <trhodes@FreeBSD.org> To: danger@rulez.sk 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 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>
next in thread | previous in thread | raw e-mail | index | archive | help
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 <brueffer@FreeBSD.org>: > > > 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20060927185717.69661a1c.trhodes>