From owner-freebsd-doc@FreeBSD.ORG Mon Apr 21 12:58:46 2008 Return-Path: Delivered-To: doc@FreeBSD.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 398D4106566B; Mon, 21 Apr 2008 12:58:46 +0000 (UTC) (envelope-from marc@blackend.org) Received: from abigail.blackend.org (ns0.blackend.org [82.227.222.164]) by mx1.freebsd.org (Postfix) with ESMTP id 9DD588FC2F; Mon, 21 Apr 2008 12:58:44 +0000 (UTC) (envelope-from marc@blackend.org) Received: from gothic.blackend.org (gothic.blackend.org [192.168.1.203]) by abigail.blackend.org (8.13.4/8.13.3) with ESMTP id m3LCwfn7085049; Mon, 21 Apr 2008 14:58:42 +0200 (CEST) (envelope-from marc@abigail.blackend.org) Received: from gothic.blackend.org (localhost [127.0.0.1]) by gothic.blackend.org (8.14.2/8.14.1) with ESMTP id m3LCwf4Q001519; Mon, 21 Apr 2008 14:58:41 +0200 (CEST) (envelope-from marc@gothic.blackend.org) Received: (from marc@localhost) by gothic.blackend.org (8.14.2/8.14.1/Submit) id m3LCwfTI001518; Mon, 21 Apr 2008 14:58:41 +0200 (CEST) (envelope-from marc) Date: Mon, 21 Apr 2008 14:58:41 +0200 From: Marc Fonvieille To: =?iso-8859-1?Q?G=E1bor_K=F6vesd=E1n?= Message-ID: <20080421125841.GA1054@gothic.blackend.org> References: <200804141850.m3EIooid045445@repoman.freebsd.org> <20080414191306.GB1050@gothic.blackend.org> <480C7F3D.9010308@FreeBSD.org> MIME-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: <480C7F3D.9010308@FreeBSD.org> X-Useless-Header: blackend.org X-Operating-System: FreeBSD 7.0-STABLE User-Agent: Mutt/1.5.16 (2007-06-09) Cc: Johann Kois , doc@FreeBSD.org Subject: Re: Mixing content and whitespace changes [Was: Re: cvs commit: www/en internet.sgml] X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 21 Apr 2008 12:58:46 -0000 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