[Back it out] was: Re: cvs commit: src/share/examples/mdoc example.4

[Tom Rhodes]

On Wed, 27 Sep 2006 10:22:34 +0200
danger at 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 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,
> Daniel
> 
> 
> 
> --------------------------------------------------------
> This message was sent from rulez.sk webamil using Horde.
> 
> 
> 


-- 
Tom Rhodes