From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Uday S Reddy Newsgroups: gmane.emacs.devel Subject: Re: Please don't use revision numbers on commit messages (and elsewhere). Date: Mon, 4 Apr 2011 10:29:19 +0100 Message-ID: <19865.36719.736000.336002@gargle.gargle.HOWL> References: <877hbfvwyo.fsf@wanadoo.es> <87sju2hoee.fsf@ambire.localdomain> <87pqp6vn3p.fsf@wanadoo.es> <874o6iicxp.fsf@ambire.localdomain> <83mxkapb2g.fsf@gnu.org> <87zkoat20x.fsf@wanadoo.es> <83liztyeed.fsf@gnu.org> <87ipuxu3hb.fsf@wanadoo.es> <87aag9tt7e.fsf@wanadoo.es> <87hbagsr1x.fsf@wanadoo.es> <871v1js48d.fsf@wanadoo.es> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Transfer-Encoding: quoted-printable X-Trace: dough.gmane.org 1301909398 5827 80.91.229.12 (4 Apr 2011 09:29:58 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Mon, 4 Apr 2011 09:29:58 +0000 (UTC) Cc: emacs-devel@gnu.org To: =?iso-8859-1?Q?=D3scar?= Fuentes Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Apr 04 11:29:54 2011 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1Q6g6c-0001KQ-8V for ged-emacs-devel@m.gmane.org; Mon, 04 Apr 2011 11:29:54 +0200 Original-Received: from localhost ([127.0.0.1]:44200 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Q6g6a-0002j6-PG for ged-emacs-devel@m.gmane.org; Mon, 04 Apr 2011 05:29:52 -0400 Original-Received: from [140.186.70.92] (port=57048 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Q6g6J-0002al-Ak for emacs-devel@gnu.org; Mon, 04 Apr 2011 05:29:41 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Q6g6D-0004fM-As for emacs-devel@gnu.org; Mon, 04 Apr 2011 05:29:34 -0400 Original-Received: from sun60.bham.ac.uk ([147.188.128.137]:43937) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Q6g6D-0004eT-6Z for emacs-devel@gnu.org; Mon, 04 Apr 2011 05:29:29 -0400 Original-Received: from [147.188.128.127] (helo=bham.ac.uk) by sun60.bham.ac.uk with esmtp (Exim 4.72) (envelope-from ) id 1Q6g69-0003t3-Og; Mon, 04 Apr 2011 10:29:25 +0100 Original-Received: from mx1.cs.bham.ac.uk ([147.188.192.53]) by bham.ac.uk (envelope-from ) with esmtps (TLSv1:DES-CBC3-SHA:168) (Exim 4.72) id 1Q6g69-0004uX-Ei using interface smart1.bham.ac.uk; Mon, 04 Apr 2011 10:29:25 +0100 Original-Received: from gromit.cs.bham.ac.uk ([147.188.193.16] helo=MARUTI.cs.bham.ac.uk) by mx1.cs.bham.ac.uk with esmtp (Exim 4.51) id 1Q6g69-00070O-GY; Mon, 04 Apr 2011 10:29:25 +0100 Original-Newsgroups: gmane.emacs.devel In-Reply-To: <871v1js48d.fsf@wanadoo.es> X-Mailer: VM 8.1.93a under 23.3.1 (i386-mingw-nt5.1.2600) X-detected-operating-system: by eggs.gnu.org: Solaris 10 (beta) X-Received-From: 147.188.128.137 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:138099 Archived-At: =D3scar Fuentes writes: > I see that as a tradeoff writer vs readers. As explained elsewhere, y= ou > write things once but they are read lots of times. It is the same cas= e > as naming functions and writing comments. That is of course a very good point. Revision notes should be easy enough to read, but *analyzing* them might involve some work. In practice, it involves a lot of work, and one addition/subtraction isn't going to make much of a difference. Going back to your original example, which is presumably fictitious: > If I'm reading the VC log on a random branch and see "Fix breakage > introduced by rXXXX" and want to look at the referenced revision, > ... the problem with such a note is that it says precious little unless you go and find the revision XXXX. Those of us that write technical articles have been taught to use the convention that the text should stand on its own without having to follow the cross-references to understand what it is saying. (I have been told that it is what is recommended by the Chicago Manual of Style, though I haven't read the manual myself.) Your example fails that test. If there is enough information in the note for the reader to decide whether it is necessary to follow the cross-reference, then readability would be preserved. The various real examples cited by Juanma seem to be mostly fine. Cheers, Uday