From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: John Paul Wallington Newsgroups: gmane.emacs.devel Subject: Re: mentioning variable aliases in `describe-variable' Date: Fri, 12 Jul 2002 01:30:03 +0100 Sender: emacs-devel-admin@gnu.org Message-ID: References: <200207111925.g6BJPuO03928@rum.cs.yale.edu> NNTP-Posting-Host: localhost.gmane.org X-Trace: main.gmane.org 1026433539 12405 127.0.0.1 (12 Jul 2002 00:25:39 GMT) X-Complaints-To: usenet@main.gmane.org NNTP-Posting-Date: Fri, 12 Jul 2002 00:25:39 +0000 (UTC) Cc: emacs-devel@gnu.org Return-path: Original-Received: from quimby.gnus.org ([80.91.224.244]) by main.gmane.org with esmtp (Exim 3.33 #1 (Debian)) id 17SoFf-0003Dy-00 for ; Fri, 12 Jul 2002 02:25:39 +0200 Original-Received: from fencepost.gnu.org ([199.232.76.164]) by quimby.gnus.org with esmtp (Exim 3.12 #1 (Debian)) id 17SoPI-0000Wg-00 for ; Fri, 12 Jul 2002 02:35:36 +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 17SoGD-0000sq-00; Thu, 11 Jul 2002 20:26:13 -0400 Original-Received: from mail4.svr.pol.co.uk ([195.92.193.211]) by fencepost.gnu.org with esmtp (Exim 3.35 #1 (Debian)) id 17SoFB-0000o9-00 for ; Thu, 11 Jul 2002 20:25:09 -0400 Original-Received: from modem-838.grommet.dialup.pol.co.uk ([62.25.159.70] helo=bundalo.shootybangbang.com) by mail4.svr.pol.co.uk with esmtp (Exim 3.35 #1) id 17SoF8-0001gm-00; Fri, 12 Jul 2002 01:25:06 +0100 Original-Received: from jpw by bundalo.shootybangbang.com with local (Exim 3.32 #1 (Debian)) id 17SoJv-0001fs-00; Fri, 12 Jul 2002 01:30:03 +0100 Original-To: monnier+gnu/emacs@rum.cs.yale.edu In-Reply-To: <200207111925.g6BJPuO03928@rum.cs.yale.edu> (monnier+gnu/emacs@rum.cs.yale.edu) Errors-To: emacs-devel-admin@gnu.org X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.0.11 Precedence: bulk List-Help: List-Post: List-Subscribe: , List-Id: Emacs development discussions. List-Unsubscribe: , List-Archive: Xref: main.gmane.org gmane.emacs.devel:5676 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:5676 > > > I think it would be nice to mention when a variable is an alias in > > `describe-variable'. What do people think ? > > Go for it, although I'd personally put the info near the > first line (as is done for function aliases) rather than near > the bottom. I like your suggestion. How about this: *** help-fns.el 27 Jun 2002 16:10:23 -0000 1.12 --- help-fns.el 12 Jul 2002 00:10:52 -0000 *************** *** 426,431 **** --- 426,439 ---- (save-excursion (forward-line -1) (insert "Automatically becomes buffer-local when set in any fashion.\n")))) + ;; mention if it's an alias + (let ((alias (condition-case nil + (indirect-variable variable) + (error variable)))) + (unless (eq alias variable) + (princ (format "This variable is an alias for `%s'." alias)) + (terpri) + (terpri))) (princ "Documentation:") (terpri) (let ((obsolete (get variable 'byte-obsolete-variable))) It could go underneath the Documentation heading, and it could omit an alias explictly mentioned in the obsolescence note. Which is what I did initially; I was keen on it for twenty minutes or so but rejected it because alias nature isn't really documentation and `describe-variable' should spell things out rather than silently omit information. I thought I would include it so that someone could reassure me it is wrong :-) *** help-fns.el 27 Jun 2002 16:10:23 -0000 1.12 --- help-fns.el 11 Jul 2002 23:34:02 -0000 *************** *** 435,444 **** (princ "; ") (terpri) (princ (if (stringp (car obsolete)) (car obsolete) (format "use `%s' instead." (car obsolete)))) ! (terpri))) (let ((doc (documentation-property variable 'variable-documentation))) (princ (or doc "Not documented as a variable."))) ! ;; Make a link to customize if this variable can be customized. ;; Note, it is not reliable to test only for a custom-type property ;; because those are only present after the var's definition --- 435,453 ---- (princ "; ") (terpri) (princ (if (stringp (car obsolete)) (car obsolete) (format "use `%s' instead." (car obsolete)))) ! (terpri)) ! ;; mention if it's an alias, unless the variable it is an alias ! ;; for is already mentioned in the obsolescence note ! (let ((alias (condition-case nil ! (indirect-variable variable) ! (error variable)))) ! (unless (or (eq alias variable) ! (eq alias (car obsolete))) ! (princ (format "This variable is an alias for `%s'." alias)) ! (terpri)))) (let ((doc (documentation-property variable 'variable-documentation))) (princ (or doc "Not documented as a variable."))) ! ;; Make a link to customize if this variable can be customized. ;; Note, it is not reliable to test only for a custom-type property ;; because those are only present after the var's definition -- John Paul Wallington