Quoting Christian Brueffer <[EMAIL PROTECTED]>:
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.
_______________________________________________
cvs-all@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/cvs-all
To unsubscribe, send any mail to "[EMAIL PROTECTED]"
