cvs commit: src/share/examples/mdoc example.4

[danger at rulez.sk]

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.