From owner-svn-doc-head@FreeBSD.ORG Wed Nov 14 15:24:00 2012 Return-Path: Delivered-To: svn-doc-head@FreeBSD.org Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id B46CA313; Wed, 14 Nov 2012 15:24:00 +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 75E748FC16; Wed, 14 Nov 2012 15:24:00 +0000 (UTC) Received: from wonkity.com (localhost [127.0.0.1]) by wonkity.com (8.14.5/8.14.5) with ESMTP id qAEFNsRP053887; Wed, 14 Nov 2012 08:23:54 -0700 (MST) (envelope-from wblock@wonkity.com) Received: from localhost (wblock@localhost) by wonkity.com (8.14.5/8.14.5/Submit) with ESMTP id qAEFNsLf053884; Wed, 14 Nov 2012 08:23:54 -0700 (MST) (envelope-from wblock@wonkity.com) Date: Wed, 14 Nov 2012 08:23:54 -0700 (MST) From: Warren Block To: Marc Fonvieille Subject: Re: svn commit: r39872 - head/en_US.ISO8859-1/books/handbook/config In-Reply-To: <20121113201455.GA1460@emphyrio.blackend.org> Message-ID: References: <201210310241.q9V2f3rx030600@svn.freebsd.org> <20121102091029.GA1463@emphyrio.blackend.org> <20121113201455.GA1460@emphyrio.blackend.org> User-Agent: Alpine 2.00 (BSF 1167 2008-08-23) MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.2.7 (wonkity.com [127.0.0.1]); Wed, 14 Nov 2012 08:23:54 -0700 (MST) Cc: svn-doc-head@FreeBSD.org, svn-doc-all@FreeBSD.org, doc-committers@FreeBSD.org, Warren Block X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 14 Nov 2012 15:24:01 -0000 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: >> >>>> - 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). 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 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... 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.