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: Sat, 4 Feb 2017 18:11:11 -0800 (PST) Message-ID: References: <8e81acfe-ecaa-4fac-9484-24541b232ba1@default> <87k29cq68h.fsf@users.sourceforge.net> <4218ccf3-da3c-43e3-9901-183e4ec81f71@default> <87efzjrhi7.fsf@users.sourceforge.net> <1578ae0e-be68-47b0-a834-69da76fed9cd@default> <87zii6por2.fsf@users.sourceforge.net> <874m09pt6t.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 1486260738 19548 195.159.176.226 (5 Feb 2017 02:12:18 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sun, 5 Feb 2017 02:12:18 +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 Sun Feb 05 03:12:14 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 1caCJK-0004WD-7H for geb-bug-gnu-emacs@m.gmane.org; Sun, 05 Feb 2017 03:12:14 +0100 Original-Received: from localhost ([::1]:41530 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1caCJH-0007Vb-PE for geb-bug-gnu-emacs@m.gmane.org; Sat, 04 Feb 2017 21:12:11 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:39553) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1caCJB-0007VV-Qk for bug-gnu-emacs@gnu.org; Sat, 04 Feb 2017 21:12:07 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1caCJ8-00045u-KL for bug-gnu-emacs@gnu.org; Sat, 04 Feb 2017 21:12:05 -0500 Original-Received: from debbugs.gnu.org ([208.118.235.43]:58210) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1caCJ8-00045a-G8 for bug-gnu-emacs@gnu.org; Sat, 04 Feb 2017 21:12:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1caCJ8-0008Gh-53 for bug-gnu-emacs@gnu.org; Sat, 04 Feb 2017 21:12: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: Sun, 05 Feb 2017 02:12:02 +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.148626068331738 (code B ref 25581); Sun, 05 Feb 2017 02:12:02 +0000 Original-Received: (at 25581) by debbugs.gnu.org; 5 Feb 2017 02:11:23 +0000 Original-Received: from localhost ([127.0.0.1]:56409 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1caCIV-0008Fq-Gn for submit@debbugs.gnu.org; Sat, 04 Feb 2017 21:11:23 -0500 Original-Received: from userp1040.oracle.com ([156.151.31.81]:28378) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1caCIT-0008Fd-Aj for 25581@debbugs.gnu.org; Sat, 04 Feb 2017 21:11:21 -0500 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 v152BEVV015799 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Sun, 5 Feb 2017 02:11:15 GMT Original-Received: from aserv0121.oracle.com (aserv0121.oracle.com [141.146.126.235]) by aserv0022.oracle.com (8.14.4/8.14.4) with ESMTP id v152BEss014371 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Sun, 5 Feb 2017 02:11:14 GMT Original-Received: from abhmp0003.oracle.com (abhmp0003.oracle.com [141.146.116.9]) by aserv0121.oracle.com (8.13.8/8.13.8) with ESMTP id v152BBKC002492; Sun, 5 Feb 2017 02:11:12 GMT In-Reply-To: <874m09pt6t.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: aserv0022.oracle.com [141.146.126.234] 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:128975 Archived-At: It's hard for me to read this style of `diff' output, so I may have missed some of the real changes. I think I'm generally OK with your proposed changes, but I made a few comments below. > - A @dfn{hook} is a variable where you can store a function or functions > -to be called on a particular occasion by an existing program. Emacs > -provides hooks for the sake of customization. Most often, hooks are set > -up in the init file (@pxref{Init File}), but Lisp programs can set them > also. > + A @dfn{hook} is a variable where you can store a function or > +functions (@pxref{What Is a Function}) to be called on a particular > +occasion by an existing program. Emacs provides hooks for the sake of > +customization. Most often, hooks are set up in the init file > +(@pxref{Init File}), but Lisp programs can set them also. > @xref{Standard Hooks}, for a list of some standard hook variables. OK. I think the only real change there is to xref {What Is a Function}. (Right?) > -You can use @code{add-hook} to add a function to an abnormal > -hook, but you must write the function to follow the hook's > -calling convention. I think this statement was removed. Don't you think that we should say that you can use `add-hook' with an abnormal (or a normal) hook? Why would we want to remove this? A reader could think that `add-hook' is only for normal hooks, and so might resort to, say, `add-to-list' for an abnormal hook. > +If the name of the variable ends in @samp{-predicate} or > +@samp{-function} (singular) then its value must be a function, not a Is this the (new) policy, adding the suffix `-predicate'? In my previous comments I was sticking to the old policy, and pointing out that `isearch-filter-predicate', now that it is being advised here and there with `add-function', is being used as a hook, and so it should be named accordingly, as `*-function'. I'm not sure it is a good idea to add more possible suffixes for hooks. But someone who decides things should decide this. If it is decided to add suffix `-predicate' for hooks, then OK. There's something else that is a bit disconcerting - not with what you wrote, but what you wrote brings up another issue: This text talks about a naming convention, saying that IF a variable's name matches one of these patterns THEN it is a hook (or it is likely to be a hook). But the addition of nadvice.el and subsequent encouragement of advising functions with it applies to all functions. It in effect makes every function-valued variable into a hook. Can or should users expect that such variables will by convention have such a conventional suffix? Dunno. > + Since hooks (both multi and single function) are variables, their (Should be "both multi- and single-function" or "both multi-function and single-function".) > +values can be modified with @code{setq} or temporarily with > +@code{let}. Yes, but I'd say something like this (using "set" and "bind" instead of "modified"): Since a hook is a variable you can set or bind it to a different value (using `setq' or `let', for example). This applies to any hook, regardless of its value. If you want to point out that this is true for both multi-function and single-function hooks, OK, but it's not strictly necessary. The point is about variables, not their values, and I think the last sentence I added is enough to cover this. (I said earlier that it's good to point out that you can use `setq' and `let' to set or bind a hook whose name ends in `-function'. It's the wording "multi-function" and "single-function" that I think is not good to use - see below.) > +However, it is often useful to add or remove a particular > +function from a hook while preserving any other functions it might > +have. For multi function hooks, the recommended way of doing this is > +with @code{add-hook} and @code{remove-hook} (@pxref{Setting Hooks}). > +Most normal hook variables are initially void; @code{add-hook} knows > +how to deal with this. You can add hooks either globally or "You can add hooks" is wrong. Something like `add-hook' adds a function to a hook (a variable). It does not add a hook to anything. > +buffer-locally with @code{add-hook}. I would split the paragraph here, before talking about hooks whose values can only be a single-function. > +For hooks which hold only a single function, This is clearer: "For a hook whose value must be a single function..." As I said in an earlier mail, just calling such hooks "single-function" can be misleading. They are hooks whose value MUST (always) be a single function. The label "single-function hook" can be misunderstood as a list-valued hook whose value is currently a singleton list (holds a single function). Unless we give such hooks a special name (I don't think "single-function" is clear), this is another argument for sticking with the old naming convention (not adding suffix `-predicate'). In that case they can be referred to as hooks whose name ends in `-function'. If we add `-predicate' then the clearest way to refer to them (unless we give them a new name) is "a hook whose name ends in `-function' or `-predicate', which is a mouthful, especially if repeated. I think it might be clear enough to say what I said above: "a hook whose value must be a single function". It is that the variable value MUST BE a function, not that the hook HOLDS a single function (e.g. currently). > +@code{add-hook} is not appropriate, but you can use > +@code{add-function} (@pxref{Advising Functions}) to combine new > +functions with the hook. I would say "but you can advise the function that is the hook value using functions such as `add-function' (@pxref{Advising Functions})." The hook is a variable. It is its value that is advised. The hook (a variable) is not combined with functions. And `add-function' is only one way to advise the hook value. > Note that some single function hooks may be > +@code{nil} which @code{add-function} cannot deal with, so you must > +check for that before calling @code{add-function}. This disagrees with my understanding. (But again, "single-function hook" is misleading.) We are talking here about a hook whose value MUST ALWAYS BE a function (advised or not). Its value cannot be `nil'. IOW, I don't think we should talk about "single-function hooks", and explain that such a hook's single value might be `nil' or a function... I think we should talk about hooks whose value MUST BE a function. And for those critters, you can always use `add-function' etc. Now, since you can apply `add-function' to any function, it can happen that someone defines a variable - of whatever name - whose value can be a (single) function or nil (or a number or a symbol or a character or...). In a general sense, since the value CAN be a function, someone could call such a variable a "hook", if s?he wants. But that is, I think, NOT what we are talking about in this doc. We are talking here about naming conventions for variables whose values are either (1) a function whose name ends in `-function' (or `-predicate'?) and whose value MUST BE a function or (2) a list of functions (normal & abnormal hooks, for which you can use `add-hook'). A variable whose value can be something other than a list of functions or a single function, and whose name does not follow the documented convention, can have its value modified in any number of ways, including (depending on the current value) with `add-hook' or `add-function', but it is not a hook in the sense specified in this node.