From owner-svn-doc-all@FreeBSD.ORG Tue Nov 13 20:15:09 2012 Return-Path: Delivered-To: svn-doc-all@FreeBSD.org Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id 32F8BDEA; Tue, 13 Nov 2012 20:15:09 +0000 (UTC) (envelope-from marc@blackend.org) Received: from smtp6-g21.free.fr (smtp6-g21.free.fr [IPv6:2a01:e0c:1:1599::15]) by mx1.freebsd.org (Postfix) with ESMTP id D55278FC0C; Tue, 13 Nov 2012 20:15:04 +0000 (UTC) Received: from emphyrio.blackend.org (unknown [88.179.1.53]) by smtp6-g21.free.fr (Postfix) with ESMTP id 7499F82259; Tue, 13 Nov 2012 21:14:57 +0100 (CET) Received: from emphyrio.blackend.org (localhost [127.0.0.1]) by emphyrio.blackend.org (8.14.5/8.14.4) with ESMTP id qADKEtCR001534; Tue, 13 Nov 2012 21:14:55 +0100 (CET) (envelope-from marc@emphyrio.blackend.org) Received: (from marc@localhost) by emphyrio.blackend.org (8.14.5/8.14.4/Submit) id qADKEtvO001533; Tue, 13 Nov 2012 21:14:55 +0100 (CET) (envelope-from marc) Date: Tue, 13 Nov 2012 21:14:55 +0100 From: Marc Fonvieille To: Warren Block Subject: Re: svn commit: r39872 - head/en_US.ISO8859-1/books/handbook/config Message-ID: <20121113201455.GA1460@emphyrio.blackend.org> References: <201210310241.q9V2f3rx030600@svn.freebsd.org> <20121102091029.GA1463@emphyrio.blackend.org> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: X-Useless-Header: blackend.org X-Operating-System: FreeBSD 8.3-STABLE User-Agent: Mutt/1.5.21 (2010-09-15) Cc: svn-doc-head@FreeBSD.org, svn-doc-all@FreeBSD.org, doc-committers@FreeBSD.org, Warren Block X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 13 Nov 2012 20:15:09 -0000 On Fri, Nov 02, 2012 at 07:55:06AM -0600, Warren Block wrote: > On Fri, 2 Nov 2012, Marc Fonvieille wrote: > > >> - The rc.conf file can then be > >> + rc.confcan 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 rsync or a > >> - similar program, while the rc.conf.local > >> - file remains unique. > >> + similar program, while rc.conf.local > >> + remains unique. > >> > >> Upgrading the system using &man.sysinstall.8; or > >> - make world will not overwrite the > >> - rc.conf file, so system configuration > >> + make world will not overwrite > >> + rc.conf, so system configuration > >> information will not be lost. > > [...] > > > > 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