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

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

[Michael Heerdegen]

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''

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

[Stefan Monnier]

> 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

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

[Michael Heerdegen]

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

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

[Andreas Schwab]

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."

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

[Stefan Monnier]

>> 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

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

[Michael Heerdegen]

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

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

[Stefan Monnier]

>   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