RE: doc on define-minor-mode hook variable(s)

[Drew Adams]

    > important functionality provided by `define-minor-mode' is not
    > revealed by the doc.

    Like what?

Looking at this with my new understanding (thank you) that there are no hook
variables involved, only symbols, I see now that this doc is not incomplete.
Since there are no hook variables involved, there is no need to mention that
the macro doesn't create them and that if you create them then their values
will be run.

The doc could perhaps elaborate a bit on `MODE-hook', however. It might help
to mention that 1) symbol `MODE-hook' is created (interned) by the macro; 2)
it is created as an empty hook; and 3) you can define it (oops - modify it)
using `add-hook'. But I understand that that's always true, so it doesn't
say much: one can always do (add-hook 'foo 'bar) whether or not `foo' was
previously interned. I'm not sure which added info might help.

I think the main thing is to clearly explain what you explained: how hooks
work. That is not specific to `define-minor-mode'. The place to explain it,
in both the Emacs-Lisp manual and the Emacs manual, is in node Hooks. In my
copy of the manuals (perhaps not up to date), what you explained is not
presented, AFAICS. The Elisp manual Hooks node starts like this: "A "hook"
is a variable...". The Emacs manual Hooks node starts by saying "A hook is a
Lisp variable...".

In the past, hook variables were used, and the new notion that a hook need
not be associated with a variable should be explained in the doc. It is not
enough to explain how hooks work now; it should explicitly be pointed out
(at least in AntiNews) that variables need no longer be involved (are no
longer involved).

BTW, the manual info on `define-minor-mode' should also be corrected to not
refer to "the mode hook _variable_ `MODE-hook'" (if that has not already
been done since the CVS snapshot I have).

This seems disturbing: "the only way to figure out whether a hook exists or
not is by actually placing something on it and checking whether/when it gets
triggered." If a variable holds a hook symbol's value, then one can use `C-h
v', which is a lot simpler for users.

IIUC, in Lisp you can use (symbol-value 'my-hook) to see whether or not
there are any candidates for removal by `remove-hook'. I'm avoiding saying
"to see whether or not the hook is defined", since you objected to that. You
used "hook exists", but that seems inaccurate also, since whether or not a
symbol exists has nothing to do with whether or not its symbol-value is a
list of functions usable as a hook. I'd be tempted to speak in terms of the
hook being empty or not. Whatever - just let us know what the correct
terminology is.

Should there be a command that lets a user know whether or not a hook is
empty - that is, a command that does simply (symbol-value 'the-hook)? Users
need to be able to determine this sometimes, and `C-h v' will no longer work
if there is no associated variable. I kept trying `C-h v' after reading the
`define-minor-mode' doc string, thinking that a variable (perhaps with value
nil) was defined.

    It is not true that those hooks are run "before the minor-mode keymap is
    defined and the minor mode is added to minor-mode-alist".

My bad; you're right.

Thanks for clarifying hooks for me. Now, unless it's already been done,
let's do the same for the manuals and doc strings.