From owner-svn-doc-all@FreeBSD.ORG Fri Nov 2 13:55:07 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 74BD4562; Fri, 2 Nov 2012 13:55:07 +0000 (UTC) (envelope-from wblock@wonkity.com) Received: from wonkity.com (wonkity.com [67.158.26.137]) by mx1.freebsd.org (Postfix) with ESMTP id 100408FC0A; Fri, 2 Nov 2012 13:55:06 +0000 (UTC) Received: from wonkity.com (localhost [127.0.0.1]) by wonkity.com (8.14.5/8.14.5) with ESMTP id qA2Dt6vR036848; Fri, 2 Nov 2012 07:55:06 -0600 (MDT) (envelope-from wblock@wonkity.com) Received: from localhost (wblock@localhost) by wonkity.com (8.14.5/8.14.5/Submit) with ESMTP id qA2Dt6Ui036845; Fri, 2 Nov 2012 07:55:06 -0600 (MDT) (envelope-from wblock@wonkity.com) Date: Fri, 2 Nov 2012 07:55:06 -0600 (MDT) From: Warren Block To: Marc Fonvieille Subject: Re: svn commit: r39872 - head/en_US.ISO8859-1/books/handbook/config In-Reply-To: <20121102091029.GA1463@emphyrio.blackend.org> Message-ID: References: <201210310241.q9V2f3rx030600@svn.freebsd.org> <20121102091029.GA1463@emphyrio.blackend.org> User-Agent: Alpine 2.00 (BSF 1167 2008-08-23) MIME-Version: 1.0 Content-Type: TEXT/PLAIN; format=flowed; charset=US-ASCII X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.2.7 (wonkity.com [127.0.0.1]); Fri, 02 Nov 2012 07:55:06 -0600 (MDT) 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: Fri, 02 Nov 2012 13:55:07 -0000 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? >> 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.