Date: Thu, 21 Feb 2002 17:09:51 -0500 From: Michael Lucas <mwlucas@blackhelicopters.org> To: Ceri <setantae@submonkey.net> Cc: freebsd-doc@FreeBSD.ORG Subject: Re: docs/35155: [PATCH] Misc corrections to the Handbook, chapter 2 Message-ID: <20020221170951.B30225@blackhelicopters.org> In-Reply-To: <20020221115732.GA575@rhadamanth>; from setantae@submonkey.net on Thu, Feb 21, 2002 at 11:57:32AM %2B0000 References: <200202202000.g1KK08V36428@freefall.freebsd.org> <20020221115732.GA575@rhadamanth>
next in thread | previous in thread | raw e-mail | index | archive | help
On Thu, Feb 21, 2002 at 11:57:32AM +0000, Ceri wrote: > On Wed, Feb 20, 2002 at 12:00:08PM -0800, Michael Lucas wrote: > > The following reply was made to PR docs/35155; it has been noted by GNATS. > > > > From: Michael Lucas <mwlucas@blackhelicopters.org> > > To: Priit Piipuu <priit@bsd.ee> > > Cc: FreeBSD-gnats-submit@FreeBSD.ORG > > Subject: Re: docs/35155: [PATCH] Misc corrections to the Handbook, chapter 2 > > Date: Wed, 20 Feb 2002 14:50:11 -0500 > > > > Priit, > > > > Thanks for the patch. You're mixing some whitespace changes with > > content changes, however, to wit: > > > > > <para>Here is where you must set the floppy to boot into a > > > serial console. You have to make a file called > > > - <filename>boot.config</filename> containing "/boot/loader > > > - -h". All this does is pass a flag to the bootloader to > > > - boot into a serial console.</para> > > > + <filename>boot.config</filename> containing > > > + <quote>/boot/loader -h</quote>. All this does is pass a flag to > > > + the bootloader to boot into a serial console.</para> > > > > > > > The last line here is a gratuitous whitespace diff. > > Does that really qualify as a _gratuitous_ whitespace diff ? > > He's made changes to the two lines above, and then wrapped > the line since it's now really long. I'm sure your second opinion will be forthcoming soon. :-) Still, here's my explanation and rationale. I got slapped for this very thing before becoming a committer, so I'm fairly certain it's the case. The whole reason for the "gratuitous whitespace diff" rule is to reduce the workload for our translators. Many of our translation teams speak/read very poor English, and reducing whitespace changes in commits is their single biggest request. If you don't wrap this line in the same commit, the translator just has to evaluate one line for changes. With the wrap, they must evaluate three. Eliminating these whitespace diffs reduces their workload for this operation by 66%. While this is easy for us, people who don't even use our alphabet, let alone speak English natively, will have a very hard time of it. There was a whole presentation about this at BSDCon, where one of the Japanese -doc translators said, in a very polite way, "Please, please, please don't do this!" (I don't think that that presentation is on-line yet, but it should be soon.) The presenter was Japanese, and spoke very poor English, yet thought it was important enough to get up in front of us and talk through it. BSD is *big* in Japan, and this is really a simple enough way to not shaft our foreign counterparts. They're doing a job that is even more thankless and less fulfilling than what we do. You'll frequently see commits where text is changed, creating a single long line, and then a following commit is made immediately thereafter to wrap the line. This is the preferred way to handle this sort of thing. I've gone through some sections of the FAQ with the whitespace hammer, respacing chapters appropriately where accumulated changes have done some horrible things but nobody has bothered to follow up. We really should document this in the FDP, with examples. It comes up too often. ==ml -- Michael Lucas mwlucas@FreeBSD.org, mwlucas@BlackHelicopters.org my FreeBSD column: http://www.oreillynet.com/pub/q/Big_Scary_Daemons http://www.blackhelicopters.org/~mwlucas/ To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20020221170951.B30225>