From: npostavs@users.sourceforge.net
To: Drew Adams <drew.adams@oracle.com>
Cc: 25581@debbugs.gnu.org
Subject: bug#25581: 25.1; Incorrect statement in (elisp) `Hooks'
Date: Sat, 04 Feb 2017 16:00:42 -0500 [thread overview]
Message-ID: <874m09pt6t.fsf@users.sourceforge.net> (raw)
In-Reply-To: <a956f679-33f8-481c-8d23-c9ad8caba7d1@default> (Drew Adams's message of "Wed, 1 Feb 2017 09:01:44 -0800 (PST)")
Drew Adams <drew.adams@oracle.com> 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.
next prev parent reply other threads:[~2017-02-04 21:00 UTC|newest]
Thread overview: 24+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-01-30 16:51 bug#25581: 25.1; Incorrect statement in (elisp) `Hooks' Drew Adams
2017-01-31 3:05 ` npostavs
2017-01-31 3:36 ` Mark Oteiza
2017-01-31 4:06 ` Drew Adams
2017-01-31 3:55 ` Drew Adams
2017-01-31 4:16 ` npostavs
2017-01-31 16:02 ` Drew Adams
2017-02-01 3:35 ` npostavs
2017-02-01 17:01 ` Drew Adams
2017-02-04 21:00 ` npostavs [this message]
2017-02-05 2:11 ` Drew Adams
2017-02-10 1:42 ` npostavs
2017-02-10 3:00 ` Drew Adams
2020-10-11 2:26 ` Lars Ingebrigtsen
2020-10-11 14:12 ` Drew Adams
2020-08-24 15:22 ` Lars Ingebrigtsen
2020-08-24 15:54 ` Stefan Kangas
2020-08-24 15:58 ` Lars Ingebrigtsen
2020-08-24 16:20 ` Drew Adams
2020-08-24 16:13 ` Drew Adams
2020-08-24 16:18 ` Drew Adams
2020-08-26 1:50 ` Richard Stallman
2020-08-26 18:27 ` Drew Adams
2020-08-24 16:01 ` Drew Adams
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=874m09pt6t.fsf@users.sourceforge.net \
--to=npostavs@users.sourceforge.net \
--cc=25581@debbugs.gnu.org \
--cc=drew.adams@oracle.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).