From owner-svn-doc-all@FreeBSD.ORG Fri Nov 2 14:25:57 2012 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id C36A296E; Fri, 2 Nov 2012 14:25:57 +0000 (UTC) (envelope-from wblock@wonkity.com) Received: from wonkity.com (wonkity.com [67.158.26.137]) by mx1.freebsd.org (Postfix) with ESMTP id 334178FC1A; Fri, 2 Nov 2012 14:25:57 +0000 (UTC) Received: from wonkity.com (localhost [127.0.0.1]) by wonkity.com (8.14.5/8.14.5) with ESMTP id qA2EPuNL037293; Fri, 2 Nov 2012 08:25:56 -0600 (MDT) (envelope-from wblock@wonkity.com) Received: from localhost (wblock@localhost) by wonkity.com (8.14.5/8.14.5/Submit) with ESMTP id qA2EPunt037290; Fri, 2 Nov 2012 08:25:56 -0600 (MDT) (envelope-from wblock@wonkity.com) Date: Fri, 2 Nov 2012 08:25:56 -0600 (MDT) From: Warren Block To: Eitan Adler Subject: Re: svn commit: r39908 - head/en_US.ISO8859-1/books/handbook/disks In-Reply-To: Message-ID: References: <201211020413.qA24DfDZ040748@svn.freebsd.org> User-Agent: Alpine 2.00 (BSF 1167 2008-08-23) MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.2.7 (wonkity.com [127.0.0.1]); Fri, 02 Nov 2012 08:25:56 -0600 (MDT) Cc: svn-doc-head@freebsd.org, svn-doc-all@freebsd.org, doc-committers@freebsd.org, Warren Block X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 02 Nov 2012 14:25:57 -0000 On Fri, 2 Nov 2012, Eitan Adler wrote: > On 2 November 2012 00:13, Warren Block 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.