RE: doc of defining minor modes

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

    >     > What's unpredicable? Can someone please provide a concrete
    >     > example of the problem? I'm not getting it. The doc and
    >     > comments made here so far constitute only vague warnings
    >     > - what is the problem?
    >
    >     That a minor mode might just get turned on without the
    >     user wanting it.  Possibly because the user did something
    >     as simple as browsing customization groups.
    >
    > Can you please explain how that would happen? How can a minor-mode get
    > turned on if the mode variable already has a value?

    Why should it have a value when the library gets loaded due to
    customize?

Regardless of how the library is loaded, either:

1) the user has a setting for the mode variable in .emacs, and that is
evaluated before the library is loaded, or

2) the user has such a setting in .emacs, but the library is somehow loaded
before the setting takes effect, or

3) the user has no such setting in .emacs.

In #3, the library is loaded and the default value chosen by the library
writer is used - the mode is turned on or left off, as the writer deemed
appropriate. The user has expressed no preference. No problem.

In #1, the library :init-value has no effect (since it specifies only a
default value); the user setting is respected. The user can specify any
preferred value (nil, t) for the mode variable in .emacs, and loading the
library with :init-value will not change that value. No problem.

In #2, there is the potential for a problem, but:

a) The later user setting in .emacs turns the mode off again. No problem.

b) If turning the mode back off (in .emacs) would not, for some reason
(why?), be sufficient, then we have a different (and bigger) problem that
will not be solved by telling the library writer not to use :init-value t.
For, if a user wants the mode turned _on_, and uses (setq my-mode t) in
.emacs, but the library has :init-value nil (following the recommendation),
and it for some reason overrides the user setting, then the user's choice
would be ignored in that (on) case as well.

IOW, if the library :init-value overrides a user setting, then no
recommendation for :init-value is appropriate. In that case, whatever the
:init-value, the user setting could be ignored. Again, this (#2b) is the
unlikely case where the mode being on only briefly while loading .emacs
would for some reason reek havoc. In that case, no recommendation solves the
problem.

In sum, either there is no problem at all or there is an (unexplained,
unlikely) problem that no recommendation about :init-value could possibly
solve.

    > If it does not already have a value when the library is loaded, then
    > the library can set the (default) value to on or off, as
    > appropriate.

    It is not appropriate to turn on minor modes without the user asking
    for it. That's what the recommendation is all about.

Is it appropriate to set the mode to off initially, if the user wants it on?
The point of :init-value was to specify only a _default_ value, to be used
only if the user expressed no preference beforehand. Now I think I hear that
Customize, menus, et al might load the library before the user can even
express a choice, and that that load might somehow override a user setting
in .emacs. If that is the case, then :init-value is not a default value at
all. And in that case, things are broken beyond what a simple recommendation
can heal. In that case, there should be no :init-value at all, because it
can trample user settings.

    > If on is inappropriate for some particular library for some reason,
    > then its :init-value should be nil.
    >
    > Please provide a specific scenario of the problem you see - I'm not
    > getting this.

    Then you should perhaps read the respective discussion in the
    archives.  It is not like this has not been talked through already.
    It is tiresome if people start finished discussions and decisions all
    over again without bothering to get up to scratch first.

I asked several times for a specific scenario. If this has already been
beaten to death by others, then all you need to do is point me to the
thread.

And, more importantly, since we cannot expect users to read your old
discussions, the doc should be updated to provide specific reasons for the
recommendation, and clarify it.