questions about define-minor-mode

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

1. `define-minor-mode' defines a defcustom if the mode is declared global, but
it does not otherwise.

Why not? I'm sure there is a good reason, but it's not clear to me. Why
shouldn't a user be able to customize the (default) value for a non-global minor
mode?

I understand that if the user changes the value in some buffer then that would
change the option's value, but that's not a big deal, in itself. What would be
ideal, I'd think, would be for the option to control only the default value (at
least when not global), and thus have any value changes not affect the option
value (i.e. the default value).


2. Also, the Elisp manual documentation for this (node `Defining Minor Modes')
is a bit unclear. Although it states clearly that the custom variable is created
only if you use `global', the following paragraph appears at the end of the
macro description, and not within the description's `:global' subsection: 

  Any other keyword arguments are passed directly to the
 `defcustom' generated for the variable MODE.

It would be clearer if it were pointed out here (again) that this variable is a
defcustom only if the mode is global. Or if this sentence were moved to the
`:global' subsection.


3. The explanation of "initial value must (!) be `nil'" is not clear to me at
all. I don't understand either the "exceptional" conditions under which non-nil
is permitted (!) or the reasoning behind this rule.


4. FWIW, I recently defined a minor mode for use with Info. It makes sense that
the mode be turned on by default, by anyone who would be using my code, but it
also makes sense to let users easily override this default behavior - e.g. via
Customize.

In order to do that, I ended up changing the mode to be global. Yes, that might
be a silly hack, since this minor mode makes sense only for Info (although you
don't need it to be different for different Info buffers, but for purposes of
illustration, suppose that you do). 

But it is also harmless to make it global since it has an effect only for Info
mode. The reason I made it global, however, was just so that users would have an
option to customize, in case they did want to turn it off by default for some
reason. An option is easier for many users to deal with than adding Lisp code to
.emacs.

I mention this example to indicate better my confusion wrt why (a) only `global'
creates an option and (b) why the init value "must" be nil.


Coincidentally, I got an email today from a user of another of my minor modes,
this one legitimately (!) global. He proposed to send me a patch to add a
defcustom for the minor mode. In the file header I had only mentioned putting
`(foo-mode 1)' in .emacs as a way to turn it on (the init value is nil), and he
thought it would be good to also let users use Customize. 

I replied to him that there is in fact already a custom variable for this (since
it's a global mode), and I updated the file header to make this clearer. The
point is that even for users (and this person is apparently in charge of
maintaining 3rd-party Emacs libraries for Debian) it is not necessarily clear
that customization is possible, even for global modes.

Also, I don't see any mention of Customize in the Emacs manual node `Minor
Modes' (which is the first node in the `Customization' section of the manual).
No mention that global modes have associated user options, which you can
customize.

Why not always define a defcustom for a minor mode, and advertise to users the
use of Customize for minor modes? What am I missing?