svn commit: r39872 - head/en_US.ISO8859-1/books/handbook/config

[Warren Block]

On Tue, 13 Nov 2012, Marc Fonvieille wrote:

> On Fri, Nov 02, 2012 at 07:55:06AM -0600, Warren Block wrote:
>> On Fri, 2 Nov 2012, Marc Fonvieille wrote:
>>
>>>> -    <para>The <filename>rc.conf</filename> file can then be
>>>> +    <para><filename>rc.conf</filename>can then be
>>>
>>> (a whitespace is missing before the "can")
>>
>> Whoops, so it is.  I'll fix that.
>>
>>> Regarding this change, you are just reverting what was decided years
>>> ago to avoid having a sentence beginning without a capital letter.  The
>>> same applies to the manual pages with "The .Nm utility/whatever..." thing.
>>> Respecting this principle has been a huge work...
>>
>> My apologies, I was not aware of that; could you point me to the
>> discussion?
>>
>
> If memories are good freebsd-doc archives and CVS commits should keep
> a track of that (and many manual pages).

I was hoping for something more specific, a discussion that would help 
me understand the reasoning and why it is not documented.

>>>>        distributed to every system using <command>rsync</command> or a
>>>> -      similar program, while the <filename>rc.conf.local</filename>
>>>> -      file remains unique.</para>
>>>> +      similar program, while <filename>rc.conf.local</filename>
>>>> +      remains unique.</para>
>>>>
>>>>      <para>Upgrading the system using &man.sysinstall.8; or
>>>> -      <command>make world</command> will not overwrite the
>>>> -      <filename>rc.conf</filename> file, so system configuration
>>>> +      <command>make world</command> will not overwrite
>>>> +      <filename>rc.conf</filename>, so system configuration
>>>>        information will not be lost.</para>
>>> [...]
>>>
>>> These changes are necessary?  Till now it's what we used to do and we
>>> never got any complaints.
>>
>> The FDP style guide says to avoid redundant phrases, giving filenames as
>> one specific example:
>>
>> http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/writing-style.html
>>
>>    Avoid redundant phrases
>>
>>    Try not to use redundant phrases.  In particular, "the command", "the
>>    file", and "man command" are probably redundant.
>>
>>    These two examples show this for commands.  The second example is
>>    preferred.
>>
>>    Use the command cvsup to update your sources.
>>
>>    Use cvsup to update your sources.
>>
>>    These two examples show this for filenames.  The second example is
>>    preferred.
>>
>>    ... in the filename /etc/rc.local...
>>
>>    ... in /etc/rc.local...
>>
>> Sometimes it is useful to point out that a filename refers to a file (as
>> opposed to a directory, say), but most of the time it is redundant, just
>> adding more words with no additional meaning.
>
> Hmm I'm not sure to really see what is redundant in for example "add
> this parameter in the rc.conf file", it's even often used in many
> languages but I'm not an en_US expert...

The filename renders differently, indicating that it is a file.  Even in 
ASCII, "edit rc.conf" is more clear than "edit the rc.conf file"

An analogy:

   "the rc.conf file" = if (n != 0)
   "rc.conf"          = if (n)

> It's not clearly stated in the FDP: "probably redundant".  And I feel 
> no one could come and say "it's not correct, you write like a 7 years 
> old kid", so we may avoid "thousand" lines of changes for something 
> like that.

It's not wrong, it's just redundant, repetitive, superfluous.  And it's 
not always redundant, just most of the time.  That's what the FDP 
statement is saying: if you need to tell the reader that the filename is 
a file instead of something else, *then* use the word "file". 
Otherwise, leave it to the markup.

My last commit for these, the most I've ever changed, was about 34 
lines.