From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.devel Subject: RE: 1) (elisp) `Advising Named Functions', 2) search filtering example Date: Mon, 17 Oct 2016 10:05:34 -0700 (PDT) Message-ID: <6c7a705c-c810-49ec-a70c-376ba150205e@default> References: <5a44a850-e4fc-4c9f-a266-c74766810ba1@default> <1807679d-1125-4afe-81b7-b8d8e78aa2c6@default> <9f1cf1a7-6f05-449a-a4a2-c013cf326e9c@default> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: blaine.gmane.org 1476724024 30460 195.159.176.226 (17 Oct 2016 17:07:04 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Mon, 17 Oct 2016 17:07:04 +0000 (UTC) Cc: emacs-devel To: Noam Postavsky Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Oct 17 19:06:59 2016 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1bwBMw-0004Cc-Ec for ged-emacs-devel@m.gmane.org; Mon, 17 Oct 2016 19:06:34 +0200 Original-Received: from localhost ([::1]:34546 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bwBMy-0001t8-Bx for ged-emacs-devel@m.gmane.org; Mon, 17 Oct 2016 13:06:36 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:45138) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bwBM8-0001ib-DM for emacs-devel@gnu.org; Mon, 17 Oct 2016 13:05:45 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bwBM4-0007XL-06 for emacs-devel@gnu.org; Mon, 17 Oct 2016 13:05:44 -0400 Original-Received: from userp1040.oracle.com ([156.151.31.81]:17719) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1bwBM3-0007Wt-M3 for emacs-devel@gnu.org; Mon, 17 Oct 2016 13:05:39 -0400 Original-Received: from aserv0022.oracle.com (aserv0022.oracle.com [141.146.126.234]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id u9HH5bD8032559 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Mon, 17 Oct 2016 17:05:38 GMT Original-Received: from aserv0121.oracle.com (aserv0121.oracle.com [141.146.126.235]) by aserv0022.oracle.com (8.14.4/8.13.8) with ESMTP id u9HH5bDN013632 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Mon, 17 Oct 2016 17:05:37 GMT Original-Received: from abhmp0004.oracle.com (abhmp0004.oracle.com [141.146.116.10]) by aserv0121.oracle.com (8.13.8/8.13.8) with ESMTP id u9HH5ZE1015992; Mon, 17 Oct 2016 17:05:36 GMT In-Reply-To: X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 12.0.6753.5000 (x86)] X-Source-IP: aserv0022.oracle.com [141.146.126.234] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] X-Received-From: 156.151.31.81 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:208371 Archived-At: > > I think that is wrong also. `add-hook' _can_ be used to modify a > > _single function hook_. And the doc of `add-hook' tells you so, > > in its last line - `C-h f add-hook': > > > > ... > > If HOOK's value is a single function, it is changed to a list of > > functions. >=20 > If you do this, then you will break the callers, which expect the > value of this variable to be a single function. Tell that to the doc string for `add-hook', which has said what it says in this regard for a very long time. What has changed (what is new) is that this was added to node `Hooks': If the variable=E2=80=99s name ends in =E2=80=98-function=E2=80=99, then = its value is just a single function, not a list of functions. =E2=80=98add-hook=E2=80= =99 cannot be used to modify such a _single function hook_, and you have to use =E2=80=98add-function=E2=80=99 instead (*note Advising Functi= ons::). And that is clearly false ("cannot be used" - it _can_ be so used). This is what that doc used to say (e.g. Emacs 23.4): By convention, abnormal hook names end in `-functions' or `-hooks'. If the variable's name ends in `-function', then its value is just a single function, not a list of functions. There has thus also (apparently) been a change in policy here. Whereas, before, this doc just let you know about the _naming convention_ for a hook whose value is a single function, the changed doc says (incorrectly) that you cannot use `add-hook' with it. I think that callers of such a hook should _use it as a hook_, and not necessarily expect that the value is a single function. Callers of a hook can, and should, I think, use one of the `run-hook*' functions. And there too you will note that the doc _explicitly_ talks about the non-list, single function case. `C-h f run-hooks': If a hook symbol has a non-nil value, that value may be a function or a list of functions to be called to run the hook. If the value is a function, it is called with no arguments. If it is a list, the elements are called, in order, with no arguments. `C-h f run-hook-with-args': The value of HOOK may be nil, a function, or a list of functions. Call each function in order with arguments ARGS. (It used to say this: If HOOK has a non-nil value, that value may be a function or a list of functions to be called to run the hook. If the value is a function, it is called with the given arguments and its return value is returned. If it is a list of functions, those functions are called, in order, with the given arguments ARGS.) `C-h f run-hook-with-args-until-failure': The value of HOOK may be nil, a function, or a list of functions. Call each function in order with arguments ARGS, stopping at the first one that returns nil, and return nil. `C-h f run-hook-with-args-until-success': similar. So do we have changes in policy wrt using hooks, or not? (If yes, why?) Which doc needs to be fixed?