Mixing content and whitespace changes [Was: Re: cvs commit: www/en internet.sgml]

[Marc Fonvieille]

On Mon, Apr 21, 2008 at 01:49:17PM +0200, Gábor Kövesdán wrote:
> Marc Fonvieille escribió:
>> On Mon, Apr 14, 2008 at 06:50:50PM +0000, Johann Kois wrote:
>>   
>>> jkois       2008-04-14 18:50:50 UTC
>>> 
>>>   FreeBSD doc repository
>>> 
>>>   Modified files:
>>>     en                   internet.sgml   Log:
>>>   PR: www/121562
>>> 
>>>   Some updates to  www/en/internet.sgml.
>>> 
>>>     
>> 
>> Content changes mixed with whitespace changes.
>> It'll cause unnecessary pain to a translator to find what has been
>> really changed :(
>>   
> Yes, I've also needed to face with such issues recently when I was working 
> on the Spanish website. It's not just the mixing, but some old pages are so 
> badly indented that it is a real pain to pair the translated parts to their 
> English correspondings. Although we do not surge fixing and forcing these 
> rules very strictly, some level of order is necessary to keep these files 
> easily readable for the translators and for the future editors, as well. It 
> is a real pain to work with badly indented files. I propose the following 
> procedure to avoid these difficulties:
> 
> 1, If you are going to apply whitespace fixes or have difficulties with the 
> translation, fix the whitespace in the English version of the file firts. 
> Sweep the whole file and leave it completely clean and well-indented and 
> commit this with a note to the translators that this change is just 
> cosmetical.
> 2, Apply content changes to the English version and commit.
> 3, If you are translating, now catch up with the content and fix the 
> whitespaces and indentation if it is not fixed already and commit those 
> together. As each translation takes the English version as a starting 
> point, you don't need to count with another translators, so you can apply 
> the changes together.
>

Nothing really new :)
Most of time it's useless to fix every file regarding indentation,
whitespace, etc, every time one of these "issues" is added.  A good rule
would be fixing a file when it starts to be really difficult to read
(which is a good reason to do the whitespace sweep fix).

It's impossible to make 20 commits without a fault (whitespace,
forgotten tag, typo, etc.) we are not robots.  But it's possible to be
careful when the patch comes from the external world, I mean from a
lambda submitter non-docset expert, cause most of time there will be
some issues.  Checking external diffs will reduce the addition of new
"mess".

-- 
Marc