svn commit: r39908 - head/en_US.ISO8859-1/books/handbook/disks

[Warren Block]

On Fri, 2 Nov 2012, Eitan Adler wrote:

> On 2 November 2012 00:13, Warren Block <wblock at freebsd.org> wrote:
>> Author: wblock
>> Date: Fri Nov  2 04:13:41 2012
>> New Revision: 39908
>> URL: http://svn.freebsd.org/changeset/doc/39908
>>
>> Log:
>>   Whitespace-only fixes.  Translators, please ignore.
>
> These sort of changes also wipe out 'svn blame' history making it
> harder to figure when and why a line was written.

Offhand, I can't think of a way around that.  But see below.

> I thought we normally only make whitespace changes to areas of the
> document we changed?

Not exactly.  If you change content, sure, change whitespace in those 
areas, as that will not make it any worse for translators.

The problem is that you usually can't fix all the whitespace that is 
affected.  Often, a second commit just to fix those additional issues is 
needed, and whatever the reason, that second commit sometimes does not 
happen.

Entropy builds up, and as the years pass, the formatting becomes 
terrible, and it starts to get difficult to make changes or see what is 
going on.  As Glen points out, existing sections are used as templates 
or examples for new additions, compounding errors.

The FDP has formatting rules, but many people are not aware of them.

The right thing is for committers to make content changes along with any 
embedded whitespace as normal, then commit those changes.  Afterwards, 
if any changes resulted in broken whitespace, a second whitespace-only 
commit should be made to fix those problems.  textproc/igor's -z and -Z 
help a lot with this.

In the meantime, we have documents with decades-old whitespace problems.
After a large whitespace-only fix to a file, the steps above should keep 
it in good, usable format.  That has worked with the Porter's Handbook, 
which was a good example of years of accumulated whitespace problems.