From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#16491: 24.3.50; ?REGRESSION: `defadvice' doc removed from Elisp manual Date: Wed, 22 Jan 2014 14:42:37 -0800 (PST) Message-ID: <434fa5f1-6052-4551-bf82-c7362b06b796@default> References: <20140122221111.GA3185@acm.acm> <52E04418.9020509@dancol.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1390430599 18895 80.91.229.3 (22 Jan 2014 22:43:19 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Wed, 22 Jan 2014 22:43:19 +0000 (UTC) Cc: 16491@debbugs.gnu.org To: Daniel Colascione , Alan Mackenzie , Stefan Monnier Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Wed Jan 22 23:43:24 2014 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1W66W3-0003fU-PR for geb-bug-gnu-emacs@m.gmane.org; Wed, 22 Jan 2014 23:43:24 +0100 Original-Received: from localhost ([::1]:37885 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1W66W3-0002hZ-Ed for geb-bug-gnu-emacs@m.gmane.org; Wed, 22 Jan 2014 17:43:23 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:41724) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1W66Vs-0002gR-21 for bug-gnu-emacs@gnu.org; Wed, 22 Jan 2014 17:43:20 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1W66Vi-0005c7-Jy for bug-gnu-emacs@gnu.org; Wed, 22 Jan 2014 17:43:11 -0500 Original-Received: from debbugs.gnu.org ([140.186.70.43]:47024) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1W66Vi-0005c3-Gk for bug-gnu-emacs@gnu.org; Wed, 22 Jan 2014 17:43:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1W66Vi-000609-1G for bug-gnu-emacs@gnu.org; Wed, 22 Jan 2014 17:43:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 22 Jan 2014 22:43:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 16491 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 16491-submit@debbugs.gnu.org id=B16491.139043057223051 (code B ref 16491); Wed, 22 Jan 2014 22:43:01 +0000 Original-Received: (at 16491) by debbugs.gnu.org; 22 Jan 2014 22:42:52 +0000 Original-Received: from localhost ([127.0.0.1]:32810 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1W66VX-0005zj-Tx for submit@debbugs.gnu.org; Wed, 22 Jan 2014 17:42:52 -0500 Original-Received: from aserp1040.oracle.com ([141.146.126.69]:49053) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1W66VW-0005zb-K8 for 16491@debbugs.gnu.org; Wed, 22 Jan 2014 17:42:51 -0500 Original-Received: from acsinet22.oracle.com (acsinet22.oracle.com [141.146.126.238]) by aserp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id s0MMgdiK009000 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Wed, 22 Jan 2014 22:42:39 GMT Original-Received: from aserz7022.oracle.com (aserz7022.oracle.com [141.146.126.231]) by acsinet22.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id s0MMgcf9008846 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Wed, 22 Jan 2014 22:42:38 GMT Original-Received: from abhmp0012.oracle.com (abhmp0012.oracle.com [141.146.116.18]) by aserz7022.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id s0MMgcAL008841; Wed, 22 Jan 2014 22:42:38 GMT In-Reply-To: <52E04418.9020509@dancol.org> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.8 (707110) [OL 12.0.6680.5000 (x86)] X-Source-IP: acsinet22.oracle.com [141.146.126.238] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 140.186.70.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:83904 Archived-At: > >> No, we don't document everything, and since documenting is advertising > >> we only document those things which we want people to use. >=20 > Moving the documentation to a "deprecated" section --- or even a > separate elisp manual for deprecated functionality --- woudl be a good > compromise. Those were already suggested and rejected. It should not be too difficult, and would be really helpful to users, to extract the existing advice doc as a separate manual, and to link to (and from) it from (and to) the new advice section in the Elisp manual. > > How about documenting the things those people want to use? I, for one, > > need defadvice (in CC Mode), and the message coming out is that the > > upcoming Emacs might not be an optimal development platform the way the > > current Emacs is. > > > > Also, how are we encouraging people to convert defadvice to the new > > replacement functions if they can't easily access the former's > > documentation? That was my main point: deprecation involves pointing the way forward, and a direction implies a vector: FROM here TO there. In *detail*, not just "`defadvice' is gone now; `add-function' was added to replace it." Deprecation should always either explicitly identify a specific replacement or explicitly state that there is no replacement - for *each* thingie deprecated and for each of its features/functionalities. IOW, either (1) say what, in the new replaces what in the old - e.g., use (new) B instead of (deprecated) A or else (2) state that there is nothing in the new that replaces X of the old (a loss of functionality, which might or might not be important). Why? Because during deprecation you are *still supporting* the old, and as Alan emphasized, you are indicating how to move toward the new, which serves as encouragement to do so. The point of deprecation is to help users move forward. > What if we did it the other way around and provided a downlevel- and > XEmacs-compatible add-function implementation written in terms of old > defadvice? That would be fine too - it would ensure backward compatibility, but I do not see that happening, do you? The attitude seems to be to simply turn a blind eye toward what has long existed (and still exists, BTW).