* bug#11342: 24.1.50; HOOK variable name in `add-hook' etc. confusing
@ 2012-04-25 22:45 Michael Heerdegen
2012-04-26 1:15 ` Stefan Monnier
2012-05-15 14:46 ` Stefan Monnier
0 siblings, 2 replies; 7+ messages in thread
From: Michael Heerdegen @ 2012-04-25 22:45 UTC (permalink / raw)
To: 11342
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''
^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#11342: 24.1.50; HOOK variable name in `add-hook' etc. confusing
2012-04-25 22:45 bug#11342: 24.1.50; HOOK variable name in `add-hook' etc. confusing Michael Heerdegen
@ 2012-04-26 1:15 ` Stefan Monnier
2012-04-26 2:07 ` Michael Heerdegen
2012-05-15 14:46 ` Stefan Monnier
1 sibling, 1 reply; 7+ messages in thread
From: Stefan Monnier @ 2012-04-26 1:15 UTC (permalink / raw)
To: michael_heerdegen; +Cc: 11342
> 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
^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#11342: 24.1.50; HOOK variable name in `add-hook' etc. confusing
2012-04-26 1:15 ` Stefan Monnier
@ 2012-04-26 2:07 ` Michael Heerdegen
2012-04-26 8:03 ` Andreas Schwab
0 siblings, 1 reply; 7+ messages in thread
From: Michael Heerdegen @ 2012-04-26 2:07 UTC (permalink / raw)
To: 11342
Stefan Monnier <monnier@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
^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#11342: 24.1.50; HOOK variable name in `add-hook' etc. confusing
2012-04-26 2:07 ` Michael Heerdegen
@ 2012-04-26 8:03 ` Andreas Schwab
2012-04-26 12:47 ` Stefan Monnier
2012-04-26 21:31 ` Michael Heerdegen
0 siblings, 2 replies; 7+ messages in thread
From: Andreas Schwab @ 2012-04-26 8:03 UTC (permalink / raw)
To: Michael Heerdegen; +Cc: 11342
Michael Heerdegen <michael_heerdegen@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@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756 01D3 44D5 214B 8276 4ED5
"And now for something completely different."
^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#11342: 24.1.50; HOOK variable name in `add-hook' etc. confusing
2012-04-26 8:03 ` Andreas Schwab
@ 2012-04-26 12:47 ` Stefan Monnier
2012-04-26 21:31 ` Michael Heerdegen
1 sibling, 0 replies; 7+ messages in thread
From: Stefan Monnier @ 2012-04-26 12:47 UTC (permalink / raw)
To: Andreas Schwab; +Cc: Michael Heerdegen, 11342
>> 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
^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#11342: 24.1.50; HOOK variable name in `add-hook' etc. confusing
2012-04-26 8:03 ` Andreas Schwab
2012-04-26 12:47 ` Stefan Monnier
@ 2012-04-26 21:31 ` Michael Heerdegen
1 sibling, 0 replies; 7+ messages in thread
From: Michael Heerdegen @ 2012-04-26 21:31 UTC (permalink / raw)
To: 11342
Andreas Schwab <schwab@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
^ permalink raw reply [flat|nested] 7+ messages in thread
* bug#11342: 24.1.50; HOOK variable name in `add-hook' etc. confusing
2012-04-25 22:45 bug#11342: 24.1.50; HOOK variable name in `add-hook' etc. confusing Michael Heerdegen
2012-04-26 1:15 ` Stefan Monnier
@ 2012-05-15 14:46 ` Stefan Monnier
1 sibling, 0 replies; 7+ messages in thread
From: Stefan Monnier @ 2012-05-15 14:46 UTC (permalink / raw)
To: michael_heerdegen; +Cc: 11342-done
> 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
^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2012-05-15 14:46 UTC | newest]
Thread overview: 7+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2012-04-25 22:45 bug#11342: 24.1.50; HOOK variable name in `add-hook' etc. confusing Michael Heerdegen
2012-04-26 1:15 ` Stefan Monnier
2012-04-26 2:07 ` Michael Heerdegen
2012-04-26 8:03 ` Andreas Schwab
2012-04-26 12:47 ` Stefan Monnier
2012-04-26 21:31 ` Michael Heerdegen
2012-05-15 14:46 ` Stefan Monnier
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).