[Back it out] was: Re: cvs commit: src/share/examples/mdoc example.4
trhodes at FreeBSD.org
Wed Sep 27 15:57:31 PDT 2006
On Wed, 27 Sep 2006 10:22:34 +0200
danger at rulez.sk wrote:
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.
> Quoting Christian Brueffer <brueffer at 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,
> This message was sent from rulez.sk webamil using Horde.
More information about the cvs-src