Skip site navigation (1)Skip section navigation (2)
Date:      Tue, 13 Nov 2012 21:14:55 +0100
From:      Marc Fonvieille <blackend@FreeBSD.org>
To:        Warren Block <wblock@wonkity.com>
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:  <20121113201455.GA1460@emphyrio.blackend.org>
In-Reply-To: <alpine.BSF.2.00.1211020730100.36572@wonkity.com>
References:  <201210310241.q9V2f3rx030600@svn.freebsd.org> <20121102091029.GA1463@emphyrio.blackend.org> <alpine.BSF.2.00.1211020730100.36572@wonkity.com>

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

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

-- 
Marc



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