From mboxrd@z Thu Jan  1 00:00:00 1970
Path: main.gmane.org!not-for-mail
From: "Stefan Monnier" <monnier+gnu/emacs@rum.cs.yale.edu>
Newsgroups: gmane.emacs.devel
Subject: Re: mentioning variable aliases in `describe-variable'
Date: Fri, 12 Jul 2002 11:25:48 -0400
Sender: emacs-devel-admin@gnu.org
Message-ID: <200207121525.g6CFPnv07635@rum.cs.yale.edu>
References: <E17SDzj-0000sL-00@bundalo.shootybangbang.com> <200207111925.g6BJPuO03928@rum.cs.yale.edu> <20020712091229.2E79.LEKTU@terra.es> <E17SvHH-0001yM-00@bundalo.shootybangbang.com>  <buohej5s7dc.fsf@mcspd15.ucom.lsi.nec.co.jp>
NNTP-Posting-Host: localhost.gmane.org
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
X-Trace: main.gmane.org 1026487548 11528 127.0.0.1 (12 Jul 2002 15:25:48 GMT)
X-Complaints-To: usenet@main.gmane.org
NNTP-Posting-Date: Fri, 12 Jul 2002 15:25:48 +0000 (UTC)
Cc: John Paul Wallington <jpw@shootybangbang.com>, lektu@terra.es,
   monnier+gnu/emacs@rum.cs.yale.edu, emacs-devel@gnu.org
Return-path: <emacs-devel-admin@gnu.org>
Original-Received: from quimby.gnus.org ([80.91.224.244])
	by main.gmane.org with esmtp (Exim 3.33 #1 (Debian))
	id 17T2Il-0002zp-00
	for <emacs-devel@main.gmane.org>; Fri, 12 Jul 2002 17:25:47 +0200
Original-Received: from fencepost.gnu.org ([199.232.76.164])
	by quimby.gnus.org with esmtp (Exim 3.12 #1 (Debian))
	id 17T2Sh-0003v5-00
	for <emacs-devel@quimby.gnus.org>; Fri, 12 Jul 2002 17:36:03 +0200
Original-Received: from localhost ([127.0.0.1] helo=fencepost.gnu.org)
	by fencepost.gnu.org with esmtp (Exim 3.35 #1 (Debian))
	id 17T2JP-0001Xy-00; Fri, 12 Jul 2002 11:26:27 -0400
Original-Received: from rum.cs.yale.edu ([128.36.229.169])
	by fencepost.gnu.org with esmtp (Exim 3.35 #1 (Debian))
	id 17T2It-0001VT-00
	for <emacs-devel@gnu.org>; Fri, 12 Jul 2002 11:25:55 -0400
Original-Received: (from monnier@localhost)
	by rum.cs.yale.edu (8.11.6/8.11.6) id g6CFPnv07635;
	Fri, 12 Jul 2002 11:25:49 -0400
X-Mailer: exmh version 2.4 06/23/2000 with nmh-1.0.4
Original-To: Miles Bader <miles@lsi.nec.co.jp>
Errors-To: emacs-devel-admin@gnu.org
X-BeenThere: emacs-devel@gnu.org
X-Mailman-Version: 2.0.11
Precedence: bulk
List-Help: <mailto:emacs-devel-request@gnu.org?subject=help>
List-Post: <mailto:emacs-devel@gnu.org>
List-Subscribe: <http://mail.gnu.org/mailman/listinfo/emacs-devel>,
	<mailto:emacs-devel-request@gnu.org?subject=subscribe>
List-Id: Emacs development discussions. <emacs-devel.gnu.org>
List-Unsubscribe: <http://mail.gnu.org/mailman/listinfo/emacs-devel>,
	<mailto:emacs-devel-request@gnu.org?subject=unsubscribe>
List-Archive: <http://mail.gnu.org/pipermail/emacs-devel/>
Xref: main.gmane.org gmane.emacs.devel:5711
X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:5711

> John Paul Wallington <jpw@shootybangbang.com> writes:
> > > And speaking of that: why does `describe-variable' put that useless
> > > "Documentation:" header? `describe-function' does not do it, i.e.:
> > 
> > I think for variables with big values, like `global-map', it makes sense.
> 
> Why?  If you mean `because it matches the Value: label used below', I'm
> not sure why it matters.

Maybe because John forgot that when the value is "large" it's moved to
after the documentation ?

> I agree with Juanma; `Documentation:' is just an ugly and useless wart.

Agreed.  While we're at it, I don't like the fact that the
"defined in `foo'" is at the end.  Putting it at the beginning (as is
done for functions) is much better IMO.
I think the general rule-of-thumb is that one-line info should be at the
beginning and large/variable-sized info (such as the doc) should be
kept for the "tail" end.


	Stefan