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>
next in thread | previous in thread | raw e-mail | index | archive | help
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.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?alpine.BSF.2.00.1211140722240.53496>