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

["Drew Adams" <drew.adams@oracle.com>]

Does `define-minor-mode' define a hook variable? If so, at what point is it
run? These things are not documented clearly, IMO. There is only an oblique
reference to a hook variable.

The doc string of `define-minor-mode' says this:

 "body contains code that will be executed each time the mode is
(dis)activated.
 It will be executed after any toggling but before running the hook variable
 `mode-HOOK'."

(That should presumably be "MODE-hook", BTW, and "disactivate" should be
"deactivate".)

The Emacs-Lisp manual doc on `define-minor-mode' says this:

 "The command named MODE first performs the standard actions such as
 setting the variable named MODE and then executes the BODY forms,
 if any.  It finishes by running the mode hook variable `MODE-hook'."

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

I find no variable named `MODE-hook' in Emacs, where MODE is a minor mode
name. Apparently, what is meant is that *if* someone creates a hook variable
named `MODE-hook', then it will be run.

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.

IIUC -

No global hook vars are defined by `define-minor-mode'. If such variables
happen to be defined, then their values are run as hooks. If this
understanding is correct, then I think it should be reflected in the doc.
The doc (string and manual) should say explicitly that:

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

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

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

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.

Since such a hook is likely to be used by an end user (in .emacs), as well
as by a programmer, perhaps it should also be mentioned in the Emacs manual,
node Minor Modes or node Hooks. Node Hooks mentions major-mode hooks, but
not minor-mode hooks.