Date: Wed, 27 Sep 2006 10:22:34 +0200 From: danger@rulez.sk To: Christian Brueffer <brueffer@FreeBSD.org> Cc: cvs-src@FreeBSD.org, Daniel Gerzo <danger@FreeBSD.org>, src-committers@FreeBSD.org, cvs-all@FreeBSD.org Subject: Re: cvs commit: src/share/examples/mdoc example.4 Message-ID: <20060927102234.dsupin91usswg4s0@mail.rulez.sk> In-Reply-To: <20060926202339.GA2039@haakonia.hitnet.RWTH-Aachen.DE> References: <200609261959.k8QJxqkh068350@repoman.freebsd.org> <20060926202339.GA2039@haakonia.hitnet.RWTH-Aachen.DE>
next in thread | previous in thread | raw e-mail | index | archive | help
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 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.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20060927102234.dsupin91usswg4s0>