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

[Stefan Monnier]

> OK, thanks for the clarification.

> I don't see how that substantially alters my point (or even most of what I
> wrote): more should be said about the hook _symbol_ `MODE-hook' in the doc.
> Users should be informed how they can take advantage of this feature.

The main point I saw was:

> > That seems clear: there is a hook and it is run at the end of entering
> > and exiting the mode.  What's not clear from this doc is whether
> > `define-minor-mode' creates a variable named `MODE-hook'.

And my explanation says that the part that's not clear is related to hooks
in general, not to define-minor-mode's hooks in particular.

> My concern is not really whether or not these hooks exist. My concern is
> that they are provided for by `define-minor-mode' but the behavior related
> to them is not sufficiently documented.  IOW, important functionality
> provided by `define-minor-mode' is not revealed by the doc.

Like what?

Other comment on your previous message:

> > The code defining `define-minor-mode' does bind hook variables
> > `MODE-hook', `MODE-on-hook', and `MODE-off-hook'.  A comment explains
> > that `*-on-*' and `*-off-*' are only for backward compatibility.
> > The function created by the macro runs these hooks not at its end, but
> > before the minor-mode keymap is defined and the minor mode is added to
> > minor-mode-alist - but that's a detail.

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".  Both of those
actions are done at the top-level when the minor-mode function is defined
rather than when it's called, so they should both happen before the hook
is run (even though they indeed appear afterwards in the code).

> >  - no hook vars are created by `define-minor-mode'

3 hooks are defined (the concept of a "hook var" should be avoided since
it's misleading). You can manipulate them with `add-hook' and `remove-hook'
like all other hooks and they are run with `run-hooks'.

> >  - if you create them, they should be named `MODE-hook', `MODE-on-hook',
> > and `MODE-off-hook' (or perhaps we should not mention the latter two?)

*You* don't create them.  They exist already.  And yes, mone-on-hook and
mode-off-hook should not be mentioned.

> >  - if defined, the hooks are run near the end of the minor-mode function,
> > just before the minor-mode map is defined

They're run just like major mode hooks: at the end of the minor mode function.

> > The doc for `define-minor-mode' could also remind people that it is
> > sufficient to use `(add-hook 'MODE-hook...)' to define such a hook.

add-hook modifies it: it doesn't define it.  And saying "it's sufficient to
use add-hook" is misleading: add-hook is the *only* way to manipulate
hooks.  `add-to-list' and `setq' are *wrong*.


        Stefan