From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: npostavs@users.sourceforge.net Newsgroups: gmane.emacs.bugs Subject: bug#25581: 25.1; Incorrect statement in (elisp) `Hooks' Date: Sat, 04 Feb 2017 16:00:42 -0500 Message-ID: <874m09pt6t.fsf@users.sourceforge.net> 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> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: blaine.gmane.org 1486242020 21925 195.159.176.226 (4 Feb 2017 21:00:20 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sat, 4 Feb 2017 21:00:20 +0000 (UTC) User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.1 (gnu/linux) Cc: 25581@debbugs.gnu.org To: Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Feb 04 22:00: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 1ca7RK-0005E1-KE for geb-bug-gnu-emacs@m.gmane.org; Sat, 04 Feb 2017 22:00:10 +0100 Original-Received: from localhost ([::1]:40849 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ca7RN-00081C-3t for geb-bug-gnu-emacs@m.gmane.org; Sat, 04 Feb 2017 16:00:13 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:48779) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ca7RH-0007zh-8H for bug-gnu-emacs@gnu.org; Sat, 04 Feb 2017 16:00:08 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ca7RD-0000Ai-DF for bug-gnu-emacs@gnu.org; Sat, 04 Feb 2017 16:00:07 -0500 Original-Received: from debbugs.gnu.org ([208.118.235.43]:58131) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1ca7RD-0000A5-8a for bug-gnu-emacs@gnu.org; Sat, 04 Feb 2017 16:00:03 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1ca7RC-0007yf-S0 for bug-gnu-emacs@gnu.org; Sat, 04 Feb 2017 16:00:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: npostavs@users.sourceforge.net Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 04 Feb 2017 21:00: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.148624198230615 (code B ref 25581); Sat, 04 Feb 2017 21:00:02 +0000 Original-Received: (at 25581) by debbugs.gnu.org; 4 Feb 2017 20:59:42 +0000 Original-Received: from localhost ([127.0.0.1]:56329 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ca7Qs-0007xj-2r for submit@debbugs.gnu.org; Sat, 04 Feb 2017 15:59:42 -0500 Original-Received: from mail-it0-f46.google.com ([209.85.214.46]:37388) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ca7Qp-0007xU-O5 for 25581@debbugs.gnu.org; Sat, 04 Feb 2017 15:59:40 -0500 Original-Received: by mail-it0-f46.google.com with SMTP id r185so34854528ita.0 for <25581@debbugs.gnu.org>; Sat, 04 Feb 2017 12:59:39 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:references:date:in-reply-to:message-id :user-agent:mime-version; bh=X3JPq2RTOOl6PWTJCzjBMGVRTvsCKrLbe13KP4xbFH8=; b=mDBY6LbpqZ1hP1pXbmN6tsIdWiQloB7hiQBmgSm+24K/Gq4pgpRMH0NXZRgQleKmTx xV4YM5BwWND0TGVfj/q9H+FgmLQncHYNLtUFPNtiPmH36OLEQyRnA047VdRCDbV5MXio fpBJr18vRVTTlzexeUPwBes+x9RlyT1UQTs99EBUGktaarEZn/pt7/937Svd6QFiI5T/ zlkHuticpD/tarKSb0Cx+OsRbhbxsdFXmAHo7vJtcLIlw22s5S1RGqSP9EiB+KiLhGze RM/BmL0CUfsL5IFEoiarEFfqDVQfWx8quzRS1VEqpKsilPJP+wGj66RRgp6LJf+4Z6qG gHQw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:references:date :in-reply-to:message-id:user-agent:mime-version; bh=X3JPq2RTOOl6PWTJCzjBMGVRTvsCKrLbe13KP4xbFH8=; b=YiT5QyzXA893XoEguvlLa/Djj/nIvFx7IkMGxUvnjJqFP2CRbtR+oHCddVvbIouuvc daoA6MxibMZ1cOJVYj0xqCeyJ1FlzFMohTofIJmK430M2mSC2CopeyRxmrcW4uH/4OtV uATHn/yGfYmLQOmKXILaHrT8WElvgJgXop+yKaeIJMVYrZGu7d7fflGDcjRhl2YQzTsz FLzOJNs4wHFTGak/ughPOZjed/A6lNc8z2u2WpzzcHyUrthIX88j306CZY0ZZfWe51Pm Fg5p7HuUa0ruOYC+wGa2KfHXWj+/4aDakjfT4LjCIFv7j/COygAw80iPB0Kd/Nw33kWI CmlQ== X-Gm-Message-State: AIkVDXJtnLSM+alafSs/oN1t6a/4ydS99b9CtROQEWolrH1luQ9njq6ZsPfgAX9tE0PX9Q== X-Received: by 10.36.25.83 with SMTP id b80mr2323598itb.98.1486241973838; Sat, 04 Feb 2017 12:59:33 -0800 (PST) Original-Received: from zony ([45.2.7.65]) by smtp.googlemail.com with ESMTPSA id r192sm1432355ita.13.2017.02.04.12.59.32 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Sat, 04 Feb 2017 12:59:33 -0800 (PST) In-Reply-To: (Drew Adams's message of "Wed, 1 Feb 2017 09:01:44 -0800 (PST)") 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:128966 Archived-At: Drew Adams writes: >> > The changes needed, I think, are (1) clarify that the requirement >> > of the value being a function applies only to `*-function' vars >> > and (2) be clear that there are multiple ways to change the value, >> > including plain old `setq' (as Mark O pointed out). >> >> Hmm, do we really need to explain that variables can be changed with >> setq (seems redundant)? > > I think we do here. Especially since we tell users that you "have > to use" `add-function' to modify "such a single function hook". > > A hook is (still) a variable. It's not super clear from the > doc that this is the case, IMO. Hmm, maybe if we rearranged things a bit. --- i/doc/lispref/modes.texi +++ w/doc/lispref/modes.texi @@ -35,10 +35,11 @@ Hooks @section Hooks @cindex hooks - 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. @cindex normal hook @@ -56,27 +57,36 @@ Hooks used in other contexts too. For example, the hook @code{suspend-hook} runs just before Emacs suspends itself (@pxref{Suspending Emacs}). - The recommended way to add a hook function to a hook is by calling -@code{add-hook} (@pxref{Setting Hooks}). The hook functions may be any -of the valid kinds of functions that @code{funcall} accepts (@pxref{What -Is a Function}). Most normal hook variables are initially void; -@code{add-hook} knows how to deal with this. You can add hooks either -globally or buffer-locally with @code{add-hook}. - @cindex abnormal hook If the hook variable's name does not end with @samp{-hook}, that indicates it is probably an @dfn{abnormal hook}. That means the hook functions are called with arguments, or their return values are used in some way. The hook's documentation says how the functions are -called. 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. By convention, abnormal hook names end in @samp{-functions}. +called. Any functions added to an abnormal hook must follow the +hook's calling convention. By convention, abnormal hook names end in +@samp{-functions}. @cindex single-function hook -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} cannot be -used to modify such a @emph{single function hook}, and you have to use -@code{add-function} instead (@pxref{Advising Functions}). +If the name of the variable ends in @samp{-predicate} or +@samp{-function} (singular) then its value must be a function, not a +list of functions. As with abnormal hooks, the expected arguments and +meaning of the return value vary across such @emph{single function +hooks}. The details are explained in each variable's docstring. + + Since hooks (both multi and single function) are variables, their +values can be modified with @code{setq} or temporarily with +@code{let}. 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 +buffer-locally with @code{add-hook}. For hooks which hold only a +single function, @code{add-hook} is not appropriate, but you can use +@code{add-function} (@pxref{Advising Functions}) to combine new +functions with the hook. 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}. @menu * Running Hooks:: How to run a hook.