Skip site navigation (1)Skip section navigation (2)
Date:      Fri, 2 Nov 2012 07:55:06 -0600 (MDT)
From:      Warren Block <wblock@wonkity.com>
To:        Marc Fonvieille <blackend@FreeBSD.org>
Cc:        svn-doc-head@FreeBSD.org, svn-doc-all@FreeBSD.org, doc-committers@FreeBSD.org, Warren Block <wblock@FreeBSD.org>
Subject:   Re: svn commit: r39872 - head/en_US.ISO8859-1/books/handbook/config
Message-ID:  <alpine.BSF.2.00.1211020730100.36572@wonkity.com>
In-Reply-To: <20121102091029.GA1463@emphyrio.blackend.org>
References:  <201210310241.q9V2f3rx030600@svn.freebsd.org> <20121102091029.GA1463@emphyrio.blackend.org>

next in thread | previous in thread | raw e-mail | index | archive | help
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?

>>        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.



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?alpine.BSF.2.00.1211020730100.36572>