Date: Wed, 14 Nov 2012 08:23:54 -0700 (MST) 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.1211140722240.53496@wonkity.com> In-Reply-To: <20121113201455.GA1460@emphyrio.blackend.org> References: <201210310241.q9V2f3rx030600@svn.freebsd.org> <20121102091029.GA1463@emphyrio.blackend.org> <alpine.BSF.2.00.1211020730100.36572@wonkity.com> <20121113201455.GA1460@emphyrio.blackend.org>
index | next in thread | previous in thread | raw e-mail
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: >> >>>> - <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). 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 <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... 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.home | help
Want to link to this message? Use this
URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?alpine.BSF.2.00.1211140722240.53496>