From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.devel Subject: RE: doc and help for defvaralias Date: Mon, 3 Jul 2006 14:11:51 -0700 Message-ID: References: NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: sea.gmane.org 1151961167 16637 80.91.229.2 (3 Jul 2006 21:12:47 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Mon, 3 Jul 2006 21:12:47 +0000 (UTC) Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Jul 03 23:12:46 2006 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by ciao.gmane.org with esmtp (Exim 4.43) id 1FxViZ-0003wR-Uv for ged-emacs-devel@m.gmane.org; Mon, 03 Jul 2006 23:12:34 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1FxViZ-00007C-8t for ged-emacs-devel@m.gmane.org; Mon, 03 Jul 2006 17:12:31 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1FxViI-00006Y-Mx for emacs-devel@gnu.org; Mon, 03 Jul 2006 17:12:14 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1FxViF-0008VR-QA for emacs-devel@gnu.org; Mon, 03 Jul 2006 17:12:13 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1FxViF-0008VO-Ms for emacs-devel@gnu.org; Mon, 03 Jul 2006 17:12:11 -0400 Original-Received: from [148.87.113.118] (helo=rgminet01.oracle.com) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_3DES_EDE_CBC_SHA:24) (Exim 4.52) id 1FxVvk-0004SK-F1 for emacs-devel@gnu.org; Mon, 03 Jul 2006 17:26:09 -0400 Original-Received: from rgmsgw301.us.oracle.com (rgmsgw301.us.oracle.com [138.1.186.50]) by rgminet01.oracle.com (Switch-3.1.6/Switch-3.1.6) with ESMTP id k63LBtoa031175 for ; Mon, 3 Jul 2006 15:11:55 -0600 Original-Received: from dradamslap (dhcp-amer-whq-csvpn-gw3-141-144-82-73.vpn.oracle.com [141.144.82.73]) by rgmsgw301.us.oracle.com (Switch-3.1.7/Switch-3.1.7) with SMTP id k63LBrHB025779 (version=TLSv1/SSLv3 cipher=RC4-MD5 bits=128 verify=NO) for ; Mon, 3 Jul 2006 15:11:54 -0600 Original-To: "Emacs-Devel" X-Priority: 3 (Normal) X-MSMail-Priority: Normal X-Mailer: Microsoft Outlook IMO, Build 9.0.6604 (9.0.2911.0) In-reply-to: Importance: Normal X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2800.1807 X-Brightmail-Tracker: AAAAAQAAAAI= X-Brightmail-Tracker: AAAAAQAAAAI= X-Whitelist: TRUE X-Whitelist: TRUE 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:56438 Archived-At: > This email is about defvaralias; it is not about obsolete > variables (e.g. define-obsolete-variable-alias). > `defvaralias' does not make a variable obsolete; it just > defines an alias. I think in order to know what should be done, we have to take into account what it is used for. IIRC defvaralias was introduced specifically to deal with renaming variables and deprecating the old name, and AFAIK there hasn't been any other use of it yet. So it makes sense for C-h v to omit the "obsolete" name. 1. defvaralias hasn't even been introduced yet - Emacs 22 is not yet released. It is not correct to speak of what it is (can be, will be) for, beyond what its designer might have had in mind. Things are often used in unexpected ways, not all of which are improper. It is incorrect to identify "what it is used for" with why it "was introduced", especially since what it is used for cannot be determined yet. 2. I have used `defvaralias' to provide an alias (!) - no connection with deprecation. I have two libraries, one of which (eyedropper.el) is a rudimentary version the other (palette.el), providing only some of its functionality. The rudimentary library is for Emacs versions before Emacs 22, but that is irrelevant - one might simply be a lightweight, reduced version of the other. Some other libraries use (require) the eyedropper functionality, calling functions defined in eyedropper.el and named using prefix `eyedrop-'. Library palette.el redefines the eyedropper commands, providing them with additional bells and whistles. Because the other libraries use functions that start with `eyedrop-', library palette.el provides `eyedrop-' aliases to its fancier versions (which are defined with prefix `palette-'). If you use Emacs 22 and you have palette.el loaded, then you can use the other libraries as is and take advantage of the palette.el versions, thanks to the aliases. 3. Regardless of the possible uses to which `defvaralias' will actually be put in practice ("wet and see", as the French say en anglais), the doc string should reflect what `defvaralias' actually *does*. It is for this reason that I sent my email. Doc and help should mention that the alias and its target are value *synonyms* - see my email for the explanation, reasons, and consequences. If changing the value of one also changes the value of the other, then each should be referenced in the doc for the other. 4. There is a separate function for defining an alias that is intended to be used to deprecate an existing variable: `define-obsolete-variable-alias'. The existence of `define-obsolete-variable-alias' argues all the more strongly for agnosticism on the part of `defvaralias' wrt its possible use to alias an obsolete variable. Nothing prevents you from using `defvaralias' with such an intention (e.g. as a preliminary step before ultimately deprecating), but nothing requires `defvaralias' to be associated in any way with deprecation. On its own, it simply does not deprecate anything. If the intention of `defvaralias' is "specifically to deal with renaming variables and deprecating the old name", as you say, then why introduce `define-obsolete-variable-alias'? The `define-obsolete-variable-alias' doc string explains that it is equivalent to `defvaralias' plus `make-obsolete-variable'. That pretty much puts a hole through the argument that `defvaralias' was introduced to rename AND deprecate. It is `define-obsolete-variable-alias' that is intended for that use. Also, there is nothing in the doc string of `defvaralias' that suggests that it is intended to deprecate an obsolete name (good). The Elisp manual's introduction at node Variable Aliases does suggest that, but the description of the function itself does not. I suggest removing that misconceived suggestion from the intro, and leaving the doc of `defvaralias' 100% agnostic wrt obsolescence - it in no way deprecates a variable, so we should not suggest that it does. See my original email for more explanation.