From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#25581: 25.1; Incorrect statement in (elisp) `Hooks' Date: Mon, 30 Jan 2017 19:55:23 -0800 (PST) Message-ID: <4218ccf3-da3c-43e3-9901-183e4ec81f71@default> References: <8e81acfe-ecaa-4fac-9484-24541b232ba1@default> <87k29cq68h.fsf@users.sourceforge.net> 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 1485835009 12906 195.159.176.226 (31 Jan 2017 03:56:49 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Tue, 31 Jan 2017 03:56:49 +0000 (UTC) Cc: 25581@debbugs.gnu.org To: npostavs@users.sourceforge.net Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Tue Jan 31 04:56:44 2017 Return-path: Envelope-to: geb-bug-gnu-emacs@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 1cYPYh-0003Et-NP for geb-bug-gnu-emacs@m.gmane.org; Tue, 31 Jan 2017 04:56:43 +0100 Original-Received: from localhost ([::1]:36014 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cYPYn-0005Dw-9S for geb-bug-gnu-emacs@m.gmane.org; Mon, 30 Jan 2017 22:56:49 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:56862) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cYPY5-0004aA-E2 for bug-gnu-emacs@gnu.org; Mon, 30 Jan 2017 22:56:06 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cYPY2-0003H8-7g for bug-gnu-emacs@gnu.org; Mon, 30 Jan 2017 22:56:05 -0500 Original-Received: from debbugs.gnu.org ([208.118.235.43]:53381) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1cYPY2-0003H4-44 for bug-gnu-emacs@gnu.org; Mon, 30 Jan 2017 22:56:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1cYPY1-0004CX-RE for bug-gnu-emacs@gnu.org; Mon, 30 Jan 2017 22:56:01 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 31 Jan 2017 03:56:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 25581 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 25581-submit@debbugs.gnu.org id=B25581.148583493416053 (code B ref 25581); Tue, 31 Jan 2017 03:56:01 +0000 Original-Received: (at 25581) by debbugs.gnu.org; 31 Jan 2017 03:55:34 +0000 Original-Received: from localhost ([127.0.0.1]:51580 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cYPXa-0004Ap-FN for submit@debbugs.gnu.org; Mon, 30 Jan 2017 22:55:34 -0500 Original-Received: from userp1040.oracle.com ([156.151.31.81]:19420) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cYPXZ-0004AN-17 for 25581@debbugs.gnu.org; Mon, 30 Jan 2017 22:55:33 -0500 Original-Received: from userv0021.oracle.com (userv0021.oracle.com [156.151.31.71]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id v0V3tQ6O015070 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Tue, 31 Jan 2017 03:55:26 GMT Original-Received: from userv0122.oracle.com (userv0122.oracle.com [156.151.31.75]) by userv0021.oracle.com (8.14.4/8.14.4) with ESMTP id v0V3tQGv001808 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Tue, 31 Jan 2017 03:55:26 GMT Original-Received: from abhmp0009.oracle.com (abhmp0009.oracle.com [141.146.116.15]) by userv0122.oracle.com (8.14.4/8.14.4) with ESMTP id v0V3tPSq014789; Tue, 31 Jan 2017 03:55:26 GMT In-Reply-To: <87k29cq68h.fsf@users.sourceforge.net> 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: userv0021.oracle.com [156.151.31.71] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.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" Xref: news.gmane.org gmane.emacs.bugs:128817 Archived-At: > > The second sentence here is incorrect: > > > > If the variable=E2=80=99s name ends in =E2=80=98-function=E2=80=99, th= en 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 fun= ction > > hook_, and you have to use =E2=80=98add-function=E2=80=99 instead (*no= te > > Advising Functions::). > > > > You CAN use `add-hook' to modify such a single-function hook. > > Nothing prevents you from doing so. And nothing even suggests > > that you should not. And you have always been able to do so. > > > > And this is the case whether or not the "single function hook" > > is intended to always be single-function (which intention > > AFAIK, is not enforced anywhere) or it is intended to have > > any number (including zero and one) of functions. >=20 > So something like this? >=20 > If the variable's name ends in @samp{-function}, then its value is > +just a single function, not a list of functions. @code{add-hook} > +should not be used to modify such a @emph{single function hook} ^^^^^^^^^^ > +because it would turn the value into a list. Use @code{add-function} ^^^^^^^ > +instead (@pxref{Advising Functions}). Not in my opinion. The fact that it automatically turns the value into a list is a _feature_, not something to avoid. IMHO, the fact that a single function is allowed, and you are not _required_ to instead use a list (e.g. a singleton list, which might or might not be added to or subtracted from) is not to be confused with an admonition that there is something wrong with using a list. Such an admonition would be inappropriate/misguided, IMHO. Yes, it is true that there are "single-function" hooks (hooks that happen to have only one function at the moment) and "single-function" hooks (hooks that are designed/expected to only ever have a single function, never zero or more than one). And yes, the current wording is a bit ambiguous in this regard. It is entirely possible for a given hook variable to be _intended_ to have only one function in its list value (equivalently, as its atomic value). But that intended restriction or special case is _not_ something that is declarable/definable using the hook mechanism. If that is the intention or a requirement of the code that uses that hook, then it is up to that code to enforce it. And such code should also _document_ this (exceptional) need for its hook to have only a single function. The "normal", general, and usual case is for a hook value to be a list of functions, with any number of elements, including the case of zero elements. It would be good to hear from other users about this, especially (I think) other old-time users or Emacs developers. RMS, for example. But the above is my understanding, at least, and I think it gibes with the doc and longstanding code. The recommended function for setting/modifying a hook value is `add-hook'. And all of the doc string for `add-hook' is couched in terms of the use of a list value. It is only at the very end that a statement is added that if the value is a function then it is (automatically) changed to a list of functions. It is a list of functions that is generally expected as the value. The doc string has not changed since at least Emacs 20: ---- Add to the value of HOOK the function FUNCTION. ^^^ FUNCTION is not added if already present. ^^^^^ ^^^^^^^ FUNCTION is added (if necessary) at the beginning of the hook list ^^^^^ unless the optional argument APPEND is non-nil, in which case FUNCTION is added at the end. ^^^^^ The optional fourth argument, LOCAL, if non-nil, says to modify the hook's buffer-local value rather than its default value. This makes no difference if the hook is not buffer-local. To make a hook variable buffer-local, always use `make-local-hook', not `make-local-variable'. HOOK should be a symbol, and FUNCTION may be any valid function. If HOOK is void, it is first set to nil. If HOOK's value is a single ^^^^ ^^^^^^^^^^ function, it is changed to a list of functions. ^^^^^^^^ ^^^^^^^^^^^^^^^^^ ---- Similarly, the text of (elisp) Hooks dates to Emacs 20, with almost no changes. And it clearly says that a hook (normal or abnormal) is a _list_ of functions. It adds that besides "normal" and "abnormal" hooks, whose values are lists, you can have a hook whose name ends in `-function', and in that case its "value is just a single function, not a list of functions". That special case comes after the more lengthy presentation of normal and abnormal hooks, and the general description of hooks, which speak of a list value. It is only recently that the problematic text was appended for a hook whose name is ends in `-function': "=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 Functions::)." Other than that text, the node is the same as in Emacs 20. That added text is all wrong. First, "single-function hook" is ambiguous (see above). But even if you suppose that what is really meant here is a hook whose name ends in `-function' (since the added text is in the same paragraph), it is _not_ true (AFAIK) that `add-hook' "cannot be used" for such a hook. Someone (TM) might be _wanting_ to say that Emacs now recommends that you use `add-function' instead of `add-hook' for a hook whose name ends in `-function'. But has that actually been decided? If it has, then that is what should be said, and clearly so. And in that case please help users by telling them why (e.g. advantages of advising with `add-function' versus setting the value using `add-hook'). Your proposed text suggests that even you are not clear about the reason for this proposed change (recommendation), since you suppose that it is "because it would turn the value into a list". I'm pretty sure that that is not the reason (even apart from the fact that that is a feature), and the reason is that `add-function', i.e., advising the function is deemed to have significant advantages. There is only a cross reference to node `Advising Functions', and users who follow it and read about advising will have to _guess_ how it pertains to the recommendation to use `add-function' for a hook whose name ends in `-function'. If this is now the recommendation, please make it clear to users why - why it is a better idea in this particular case to use `add-function' than it is to use `add-hook'.