GNU bug report logs - #11342
24.1.50; HOOK variable name in `add-hook' etc. confusing

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 11342 in the body.
You can then email your comments to 11342 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Michael Heerdegen <michael_heerdegen <at> web.de>
To: bug-gnu-emacs <at> gnu.org
Subject: 24.1.50; HOOK variable name in `add-hook' etc. confusing
Date: Thu, 26 Apr 2012 00:45:26 +0200

Hi,

this is just a tiny detail, but confusing for newbies:

Turn on eldoc mode in any elisp buffer.  If you move point into an
`add-hook' or `remove-hook' form, you get e.g. the message

  remove-hook: (HOOK FUNCTION &optional LOCAL)

You could misinterpret that and think that the first argument must be
a value representing a hook.  But actually it must be a _symbol_
holding a hook.

So, I want to make the suggestion to replace the variable `hook' in
the definition of `remove-hook' by `hook-var', and to do the same for
`add-hook' and `run-hooks'.  Then, the eldoc message would be

  remove-hook: (HOOK-VAR FUNCTION &optional LOCAL)

which is more clear.


Thanks,

Michael.


In GNU Emacs 24.1.50.1 (i486-pc-linux-gnu, GTK+ Version 3.4.1)
 of 2012-04-23 on zelenka, modified by Debian
 (emacs-snapshot package, version 2:20120423-1)
Windowing system distributor `The X.Org Foundation', version 11.0.11104000
Configured using:
 `configure '--build' 'i486-linux-gnu' '--host' 'i486-linux-gnu'
 '--prefix=/usr' '--sharedstatedir=/var/lib' '--libexecdir=/usr/lib'
 '--localstatedir=/var' '--infodir=/usr/share/info'
 '--mandir=/usr/share/man' '--with-pop=yes'
 '--enable-locallisppath=/etc/emacs-snapshot:/etc/emacs:/usr/local/share/emacs/24.1.50/site-lisp:/usr/local/share/emacs/site-lisp:/usr/share/emacs/24.1.50/site-lisp:/usr/share/emacs/site-lisp'
 '--without-compress-info' '--with-crt-dir=/usr/lib/i386-linux-gnu/'
 '--with-x=yes' '--with-x-toolkit=gtk3' '--with-imagemagick=yes'
 'build_alias=i486-linux-gnu' 'host_alias=i486-linux-gnu'
 'CFLAGS=-DDEBIAN -DSITELOAD_PURESIZE_EXTRA=5000 -g -O2''

Message #8 received at 11342 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: michael_heerdegen <at> web.de
Cc: 11342 <at> debbugs.gnu.org
Subject: Re: bug#11342: 24.1.50;
	HOOK variable name in `add-hook' etc. confusing
Date: Wed, 25 Apr 2012 21:15:10 -0400

> You could misinterpret that and think that the first argument must be
> a value representing a hook.  But actually it must be a _symbol_
> holding a hook.

Hooks are represented by a value which is a symbol (and which in turn
carries the various functions added to it globally and in each buffer).
The symbol's value (usually a list) is *not* the hook value but only one
part of it.


        Stefan

Message #11 received at 11342 <at> debbugs.gnu.org (full text, mbox):

From: Michael Heerdegen <michael_heerdegen <at> web.de>
To: 11342 <at> debbugs.gnu.org
Cc: monnier <at> iro.umontreal.ca
Subject: Re: bug#11342: 24.1.50;
	HOOK variable name in `add-hook' etc. confusing
Date: Thu, 26 Apr 2012 04:07:33 +0200

Stefan Monnier <monnier <at> iro.umontreal.ca> writes:

> > You could misinterpret that and think that the first argument must
> > be a value representing a hook.  But actually it must be a _symbol_
> > holding a hook.
>
> Hooks are represented by a value which is a symbol (and which in turn
> carries the various functions added to it globally and in each buffer).
> The symbol's value (usually a list) is *not* the hook value but only one
> part of it.

Thanks for the clarification, I didn't realize that, obviously.

The manual sometimes calls these values being symbols "hook", and
sometimes "hook variable".

Ok, so, these arguments of `add-hook' and `remove-hook' must be
variables (symbols) representing a hook.

My proposal to rename the `hook' argument to `hook-var' would still be
reasonable.  Sure, there is no error in the current naming.  But it
would not be false, and clearer than now for people that didn't yet
realize this part of the nomenclature, like me.

Please decide yourself - I just have the feeling that many people
stumble at that point and don't know if they must use a quote before the
hook variable or not.

OTOH, if there are good reasons to reject my proposal, please close this
report.


Thanks,

Michael

Message #14 received at 11342 <at> debbugs.gnu.org (full text, mbox):

From: Andreas Schwab <schwab <at> linux-m68k.org>
To: Michael Heerdegen <michael_heerdegen <at> web.de>
Cc: 11342 <at> debbugs.gnu.org
Subject: Re: bug#11342: 24.1.50;
	HOOK variable name in `add-hook' etc. confusing
Date: Thu, 26 Apr 2012 10:03:36 +0200

Michael Heerdegen <michael_heerdegen <at> web.de> writes:

> The manual sometimes calls these values being symbols "hook", and
> sometimes "hook variable".

* (elisp) Hooks::

    A "hook" is a variable where you can store a function or functions to
    be called on a particular occasion by an existing program.

Andreas.

-- 
Andreas Schwab, schwab <at> linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Message #17 received at 11342 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Andreas Schwab <schwab <at> linux-m68k.org>
Cc: Michael Heerdegen <michael_heerdegen <at> web.de>, 11342 <at> debbugs.gnu.org
Subject: Re: bug#11342: 24.1.50;
	HOOK variable name in `add-hook' etc. confusing
Date: Thu, 26 Apr 2012 08:47:47 -0400

>> The manual sometimes calls these values being symbols "hook", and
>> sometimes "hook variable".
> * (elisp) Hooks::
>     A "hook" is a variable where you can store a function or functions to
>     be called on a particular occasion by an existing program.

Actually, we need to rework some of that, because it can't be just "any
variable": it has to be a dynamically-scoped variable, or rather it has
to be a symbol.


        Stefan

Message #20 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Michael Heerdegen <michael_heerdegen <at> web.de>
To: bug-gnu-emacs <at> gnu.org
Subject: Re: bug#11342: 24.1.50;
	HOOK variable name in `add-hook' etc. confusing
Date: Thu, 26 Apr 2012 23:31:48 +0200

Andreas Schwab <schwab <at> linux-m68k.org> writes:

> > The manual sometimes calls these values being symbols "hook", and
> > sometimes "hook variable".
>
> * (elisp) Hooks::
>
>     A "hook" is a variable where you can store a function or functions to
>     be called on a particular occasion by an existing program.

File: elisp,  Node: Setting Hooks

 -- Function: add-hook hook function &optional append local
     This function is the handy way to add function FUNCTION to hook
     variable HOOK.

 -- Function: remove-hook hook function &optional local
     This function removes FUNCTION from the hook variable HOOK.


Michael

Message #25 received at 11342-done <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: michael_heerdegen <at> web.de
Cc: 11342-done <at> debbugs.gnu.org
Subject: Re: bug#11342: 24.1.50;
	HOOK variable name in `add-hook' etc. confusing
Date: Tue, 15 May 2012 10:46:54 -0400

>   remove-hook: (HOOK FUNCTION &optional LOCAL)
> You could misinterpret that and think that the first argument must be
> a value representing a hook.  But actually it must be a _symbol_
> holding a hook.

Actually, the docstring says "HOOK should be a symbol", so the problem
is only that you base your decision on the eldoc info, which is
necessarily too limited to be trusted to give that kind of detail.

I find that changing the argument name makes the code and docstring too
verbose for my taste, so I don't think it's worth the trouble.


        Stefan

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.