doc of defining minor modes

doc of defining minor modes

[Drew Adams]

Sometime in the last year, this text was added to Elisp info node Defining
Minor Modes:

   The initial value must be `nil' except in cases where (1) the mode
   is preloaded in Emacs, or (2) it is painless for loading to enable the
   mode even though the user did not request it.  For instance, if the
   mode has no effect unless something else is enabled, and will always be
   loaded by that time, enabling it by default is harmless.  But these are
   unusual circumstances.  Normally, the initial value must be `nil'.

FWIW, I do not agree. It is sometimes useful to enable a minor mode upon
load, and there is nothing wrong with that for normal (i.e. respectful)
minor modes. If I'm missing something here, let me know - what's the harm
(vs "harmless")?

First, it makes no sense to use the word "must" with "normally", as in the
last sentence. If you list the exceptions to a "must" explicitly, then you
can have a specific "otherwise" clause, but "normally" simply means
generally, and it is incompatible with "must" here. (It may be true that
"normally" you "must" pay taxes in Italy, but, as the folklore has it, that
really means that you can pay them if you feel like it.)

Second, #2 is vague, and the example that is meant to clarify it is far too
limited - there are plenty of other, non-corner cases where "it is painless
for loading to enable the mode" - see next.

Third, I don't see why we are stating this guideline / recommendation /
prescription. Users can always set the mode value to nil in their init
files, which, for a mode that always toggles based on changes to this
variable (which is the normal, recommended case) will inhibit mode enabling
upon load.

That was the spin used previously in this doc, I believe, and I think it is
the correct recommendation. We should say something like this (the idea, if
not the wording):

  Unless the mode automatically toggles upon changes to the mode
  variable, do not enable the mode upon load. Why? Because users
  have no way to inhibit enabling in that case.

That is the only case where it is important not to enable the mode upon
load, AFAIK. The part about modes that don't respect their variable is
missing in the current guideline - it speaks of "painless" and "harmless",
but nowhere does it explain what the pain or harm is.

Instead of mentioning this potential harm (users lose control), the
guideline simply says that unless your mode is a rare case ("unusual
circumstances"), do not enable the mode upon load. That's inadequate
(missing the harm), far too restrictive, and wrong, IMO.

I personally think that perhaps most normal (respectful) minor modes should
be enabled upon load, but I wouldn't go so far as to proclaim that in the
doc. Enabling the mode by default upon load (i.e. enabling unless the
variable is nil) is "harmless", unless I'm missing something. If I am
missing something, then maybe that something needs to be added to the doc.

If I am right about this, then, in addition to fixing this text, we should
explicitly mention that if the initial value is non-nil, then you should do
this at the end of your library. Otherwise, the lighter shows the mode as
on, but it is not on:

 (when my-mode (my-mode 1))

Re: doc of defining minor modes

[Andreas Schwab]

"Drew Adams" <drew.adams@oracle.com> writes:

> FWIW, I do not agree. It is sometimes useful to enable a minor mode upon
> load, and there is nothing wrong with that for normal (i.e. respectful)
> minor modes. If I'm missing something here, let me know - what's the harm
> (vs "harmless")?

You don't want to enable the mode just by using customize (which can
trigger loading of any lisp library).

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux Products GmbH, Maxfeldstraße 5, 90409 Nürnberg, Germany
PGP key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: doc of defining minor modes

[David Kastrup]

"Drew Adams" <drew.adams@oracle.com> writes:

> Sometime in the last year, this text was added to Elisp info node Defining
> Minor Modes:
>
>    The initial value must be `nil' except in cases where (1) the mode
>    is preloaded in Emacs, or (2) it is painless for loading to enable the
>    mode even though the user did not request it.  For instance, if the
>    mode has no effect unless something else is enabled, and will always be
>    loaded by that time, enabling it by default is harmless.  But these are
>    unusual circumstances.  Normally, the initial value must be `nil'.
>
> FWIW, I do not agree. It is sometimes useful to enable a minor mode
> upon load, and there is nothing wrong with that for normal
> (i.e. respectful) minor modes. If I'm missing something here, let me
> know - what's the harm (vs "harmless")?

Customize might load a file just because a variable has been
customized from it.

> Third, I don't see why we are stating this guideline /
> recommendation / prescription. Users can always set the mode value
> to nil in their init files, which, for a mode that always toggles
> based on changes to this variable (which is the normal, recommended
> case) will inhibit mode enabling upon load.

Uh what?  Why should that happen?

> That was the spin used previously in this doc, I believe, and I
> think it is the correct recommendation. We should say something like
> this (the idea, if not the wording):
>
>   Unless the mode automatically toggles upon changes to the mode
>   variable, do not enable the mode upon load. Why? Because users
>   have no way to inhibit enabling in that case.

How do you suppose to inhibit enabling when the mode "automatically
toggles upon changes" in this case?

> That is the only case where it is important not to enable the mode
> upon load, AFAIK. The part about modes that don't respect their
> variable is missing in the current guideline - it speaks of
> "painless" and "harmless", but nowhere does it explain what the pain
> or harm is.

Files may even get autoloaded when going through a menu.

> I personally think that perhaps most normal (respectful) minor modes
> should be enabled upon load, but I wouldn't go so far as to proclaim
> that in the doc. Enabling the mode by default upon load
> (i.e. enabling unless the variable is nil) is "harmless", unless I'm
> missing something. If I am missing something, then maybe that
> something needs to be added to the doc.

Stuff connected with autoloads and customization groups triggers at
unusual moments.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

RE: doc of defining minor modes

[Drew Adams]

    > FWIW, I do not agree. It is sometimes useful to enable a
    > minor mode upon load, and there is nothing wrong with that
    > for normal (i.e. respectful) minor modes. If I'm missing
    > something here, let me know - what's the harm (vs "harmless")?

    You don't want to enable the mode just by using customize (which can
    trigger loading of any lisp library).

I don't? Why not? What example are you thinking about? If a library is
loaded by Customize, then it's loaded - so what? And how common is that? If
there is a specific corner case here that causes a problem here, then let's
identify it.

Presumably, any libraries loaded that way should not be allowed (by their
writers) to cause harm. If they would cause harm by turning on a mode, then
they should not do so upon loading. That's all.

If the default value for the library's mode should be on, then it should be
on; if it should be off, then it should be off. If the library mode is
innocuous, then I don't see what the "harm" is in having the default value
be on. The writer of a library should know whether enabling it upon load
would be harmful; if so, then the default value should be nil. That's what
we have a default value for, instead of hard-coding it to nil - no?

Please provide a scenario for a normal, respectful mode, where harm is
caused. If there is a real problem, then let's nail down what the problem is
and then document it. The current "Do not go there!" advice is unclear and
inadequate - we must say what the problem is, if there is one. The doc
should guide the use of `define-minor-mode', including its default-value
provision. A blanket admonition not to use that provision is silly and
unhelpful.

Re: doc of defining minor modes

[David Kastrup]

"Drew Adams" <drew.adams@oracle.com> writes:

>     > FWIW, I do not agree. It is sometimes useful to enable a
>     > minor mode upon load, and there is nothing wrong with that
>     > for normal (i.e. respectful) minor modes. If I'm missing
>     > something here, let me know - what's the harm (vs "harmless")?
>
>     You don't want to enable the mode just by using customize (which can
>     trigger loading of any lisp library).
>
> I don't? Why not? What example are you thinking about? If a library is
> loaded by Customize, then it's loaded - so what? And how common is that? If
> there is a specific corner case here that causes a problem here, then let's
> identify it.
>
> Presumably, any libraries loaded that way should not be allowed (by
> their writers) to cause harm. If they would cause harm by turning on
> a mode, then they should not do so upon loading. That's all.

Unpredictability is harm enough.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

RE: doc of defining minor modes

[Drew Adams]

    Customize might load a file just because a variable has been
    customized from it.

And?

    > Third, I don't see why we are stating this guideline /
    > recommendation / prescription. Users can always set the mode value
    > to nil in their init files, which, for a mode that always toggles
    > based on changes to this variable (which is the normal, recommended
    > case) will inhibit mode enabling upon load.

    Uh what?  Why should that happen?

Why shouldn't it? It works for me.

 (setq my-mode nil) ; Inhibit turning on when loaded.

By "enabling upon load" I don't mean turning the mode on systematically when
the file is loaded; I mean setting the variable value to non-nil unless it
is already defined. That's the way it works for me, at least: if the
variable is already defined, then loading the library does not set it. IOW,
I'm speaking only of the :init-value for define-minor-mode - the _default_
value if the user specifies none.

I interpreted the doc passage quoted as essentially saying that libraries
should not use ":init-value t". If I misinterpreted the passage, then what
was the real message?

    > That was the spin used previously in this doc, I believe, and I
    > think it is the correct recommendation. We should say something like
    > this (the idea, if not the wording):
    >
    >   Unless the mode automatically toggles upon changes to the mode
    >   variable, do not enable the mode upon load. Why? Because users
    >   have no way to inhibit enabling in that case.

    How do you suppose to inhibit enabling when the mode "automatically
    toggles upon changes" in this case?

By "automatically..." I mean the usual and recommended case of a minor mode
turning on and off when its variable's value changes. Inhibit default
enabling with this in your .emacs: (setq my-mode nil)

Am I missing something here?

    > That is the only case where it is important not to enable the mode
    > upon load, AFAIK. The part about modes that don't respect their
    > variable is missing in the current guideline - it speaks of
    > "painless" and "harmless", but nowhere does it explain what the pain
    > or harm is.

    Files may even get autoloaded when going through a menu.

And?

That a file gets loaded via customize of through a menu or via cosmic ray is
not the point/problem, AFAICT. The point is what that library does. If a
particular library would cause harm by enabling a minor mode by default upon
loading, then it should not do that. Otherwise, where's the beef?

The problem is not that libraries can be loaded in various under-the-covers
ways at any unforeseen time. The problem is for each library writer to
determine if enabling the mode by default upon load is appropriate. If not,
don't do that.

It would be helpful to add guidelines with examples of things that libraries
might do that would make it inappropriate to enable their mode by default
upon load. IOW, specifics please.

    > I personally think that perhaps most normal (respectful) minor modes
    > should be enabled upon load, but I wouldn't go so far as to proclaim
    > that in the doc. Enabling the mode by default upon load
    > (i.e. enabling unless the variable is nil) is "harmless", unless I'm
    > missing something. If I am missing something, then maybe that
    > something needs to be added to the doc.

    Stuff connected with autoloads and customization groups triggers at
    unusual moments.

Too vague for me. Please formulate any specific problems that should be
added to the doc, in place of a blanket "Don't do that".

RE: doc of defining minor modes

[Drew Adams]

    >     > FWIW, I do not agree. It is sometimes useful to enable a
    >     > minor mode upon load, and there is nothing wrong with that
    >     > for normal (i.e. respectful) minor modes. If I'm missing
    >     > something here, let me know - what's the harm (vs "harmless")?
    >
    >     You don't want to enable the mode just by using customize
    >     (which can trigger loading of any lisp library).
    >
    > I don't? Why not? What example are you thinking about?
    > If a library is loaded by Customize, then it's loaded
    > - so what? And how common is that? If there is a specific
    > corner case here that causes a problem here, then let's
    > identify it.
    >
    > Presumably, any libraries loaded that way should not be allowed (by
    > their writers) to cause harm. If they would cause harm by turning on
    > a mode, then they should not do so upon loading. That's all.

    Unpredictability is harm enough.

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?

Re: doc of defining minor modes

[David Kastrup]

"Drew Adams" <drew.adams@oracle.com> writes:

>     >     > FWIW, I do not agree. It is sometimes useful to enable a
>     >     > minor mode upon load, and there is nothing wrong with that
>     >     > for normal (i.e. respectful) minor modes. If I'm missing
>     >     > something here, let me know - what's the harm (vs "harmless")?
>     >
>     >     You don't want to enable the mode just by using customize
>     >     (which can trigger loading of any lisp library).
>     >
>     > I don't? Why not? What example are you thinking about?
>     > If a library is loaded by Customize, then it's loaded
>     > - so what? And how common is that? If there is a specific
>     > corner case here that causes a problem here, then let's
>     > identify it.
>     >
>     > Presumably, any libraries loaded that way should not be allowed (by
>     > their writers) to cause harm. If they would cause harm by turning on
>     > a mode, then they should not do so upon loading. That's all.
>
>     Unpredictability is harm enough.
>
> 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.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

RE: doc of defining minor modes

[Drew Adams]

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

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

Re: doc of defining minor modes

[Stefan Monnier]

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

Elisp packages may be loaded because the user specifically wants it to be
loaded, but they can also be loaded for all kinds of other
unrelated reasons.  So as a matter of principle the user-visible behavior of
Emacs should be mostly unchanged by (load <foo>).

This often means that minor modes should default to being disabled.

Not always, tho: E.g. foo-aux-mode could default to being enabled without
any harm if it only ever affects buffers in foo-mode and foo-mode can't
exist without foo-aux-mode also existing (e.g. because they're defined in the
same file of because foo.el requires `foo-aux').


        Stefan

Re: doc of defining minor modes

[David Kastrup]

"Drew Adams" <drew.adams@oracle.com> writes:

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

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

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

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

RE: doc of defining minor modes

[Drew Adams]

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

RE: doc of defining minor modes

[Drew Adams]

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

    Elisp packages may be loaded because the user specifically
    wants it to be loaded, but they can also be loaded for all
    kinds of other unrelated reasons.  So as a matter of principle
    the user-visible behavior of Emacs should be mostly unchanged
    by (load <foo>).

    This often means that minor modes should default to being disabled.

I don't see why. Regardless of why/when a file is loaded, it should be
loaded for some good reason. For many libraries, that reason includes using
a minor mode defined in the file. In those cases, if it causes no harm for
the mode to be enabled upon load (also the majority of cases, IMO), then why
shouldn't the library do that?

I expect that many, if not most, libraries defining minor modes will fit
this mould. According to what the doc says, however, and what I'm hearing
here, none of them should enable the mode (except the corner case you
describe below).

I've still seen no scenario describing the harm. All I've heard is that the
library might be loaded in any way at any time - so what? Loading the
library should not override a user setting (e.g. to inhibit turning the mode
on), no matter how or when the load occurs.

    Not always, tho: E.g. foo-aux-mode could default to being
    enabled without any harm if it only ever affects buffers
    in foo-mode and foo-mode can't exist without foo-aux-mode
    also existing (e.g. because they're defined in the
    same file of because foo.el requires `foo-aux').

This repeats what is said in the doc. I don't see it as the only, or even
the typical, case where it should be permissible to use a non-nil
:init-value.

What the doc suggests, without saying so explicitly, and likewise for the
replies I've gotten here, is that :init-value is not intended for general
use, but is reserved for the specific corner case you describe:
foo-aux-mode.

I don't agree that that is appropriate (unless I see a harmful scenario),
but if that is the decided policy then at the very least it should be stated
clearly (much more clearly than now) - tell users in so many words not to
use :init-value except for that specific corner case.

Re: doc of defining minor modes

[David Kastrup]

"Drew Adams" <drew.adams@oracle.com> writes:

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

Look, this is getting silly.  It has been pointed out about five times
to you already that a mode suddenly turning itself on without the user
requesting it _is_ a problem.  That's why the writer should deem it
appropriate to have the default be _off_ when the file gets loaded.

And it is not like this is a new debate, anyway.

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

If the user has not indicated that he wants it on, there is no reason
to assume so.

> The point of :init-value was to specify only a _default_ value, to
> be used only if the user expressed no preference beforehand.

And we are talking about this.  If your insistence about wanting to
shoot yourself in the foot is supposed to be representative, one
should probably remove the :init-value option altogether.

> Now I think I hear that Customize, menus, et al might lqoad the
> library before the user can even express a choice, and that that
> load might somehow override a user setting in .emacs.

You are wildly speculating.  We are talking about the case where there
is no 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.

You are arguing straw men.

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

It has been beaten to death even in this thread.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

RE: doc of defining minor modes

[Drew Adams]

    It has been pointed out about five times to you already that a mode
    suddenly turning itself on without the user requesting it _is_ a
    problem.

Yes, it has been claimed that there is a problem (you've done so again), but
what the problem is has not been specified - what's the "harm"? How about a
scenario that shows something bad happening by loading a file with
:init-value t? I believe you that the load might occur behind the user's
back, so you need not repeat that part again.

And, as I said, it's not because _some_ library might be able to do
something harmful with :init-value t that we should recommend that _no_
libraries use :init-value t (except for the rare corner case). What about
the majority of libraries that don't do harm if their minor mode is turned
on during load?

Unless, that is, you can point to a general problem (harm) that can occur
with _any_ library...

    And it is not like this is a new debate, anyway.

Sorry, the question is new to me. Point me to the thread, please.

    > Is it appropriate to set the mode to off initially, if the user
    > wants it on?

    If the user has not indicated that he wants it on, there is no reason
    to assume so.

Please read what I wrote. I was discussing the case where the user specified
(setq my-mode t) in .emacs. If, as I thought you were suggesting, loading
the file could somehow override user settings, then it could override an
explicit t setting as well as an explicit nil setting. That was the point
here.

    > The point of :init-value was to specify only a _default_ value, to
    > be used only if the user expressed no preference beforehand.

    And we are talking about this.  If your insistence about wanting to
    shoot yourself in the foot is supposed to be representative, one
    should probably remove the :init-value option altogether.

Your metaphor doesn't help - what are you referring to? Is it true or not
that loading a file can somehow override user mode-variable settings in
.emacs?

* If true, then that problem should be fixed. If it cannot be fixed, then
:init-value does not perform as advertised, and it should be removed.

* If not true, then I don't see the problem with the library specifying an
:init-value of either nil or t. If the user's preference is always
respected, then where's the harm?

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

    You are wildly speculating.

Sorry; I got that speculation from your vague description of "the problem".
I asked for a specific scenario leading to "harm" or "pain", and that's all
I could imagine you meant by your response that Customize might load the
file behind the user's back. Loading the file should only set the mode value
if the user has not already set it, which is not a problem (if it is, please
explain). I figured you must be trying to say that loading by Customize
somehow overrides a user setting. If not, what's the problem?

    We are talking about the case where there
    is no user setting in .emacs.

If there is no user setting, then what is the problem? If the user doesn't
have a preference whether loading turns the mode on or leaves it off, then
why not let the library writer pick a default behavior (which is what
:init-value is supposedly for)?

That is the same for any default value. If a user doesn't have a preference
whether `debug-on-error' is t or nil at startup, then the default value is
used. What is the specific problem that you see regarding the default value
for a mode variable? That problem description must be general enough to
justify imposing the restriction on all uses of `define-minor-mode' (except
for the rare corner case).

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

    It has been beaten to death even in this thread.

Please point to the thread. Argument by authority or reference only works if
an authority or reference is pointed to.

If the decision was that programmers should never use :init-value t except
in the rare corner case described, then the doc should say so explicitly and
more clearly than it does now. It should describe the corner case better and
state in so many words that one should _not_ use :init-value _except_ for
that specific corner case. That is only suggested now, in a vague and
unclear manner.

As I said, this text was added recently (in the last year). I don't see a
reason for it. If this recommendation is kept, and you want people to
understand and respect it, then it should be clarified and justified
(explain why) in the doc.

Re: doc of defining minor modes

[David Kastrup]

"Drew Adams" <drew.adams@oracle.com> writes:

>     It has been pointed out about five times to you already that a mode
>     suddenly turning itself on without the user requesting it _is_ a
>     problem.
>
> Yes, it has been claimed that there is a problem (you've done so
> again), but what the problem is has not been specified - what's the
> "harm"?

That a mode suddenly turns itself on without the user requesting it.
Emacs is not supposed to behave erratically.  It is not supposed to be
turning on all sorts of minor modes on its whim just because the user
made the mistake of, say, executing

M-x customize-browse RET

> And, as I said, it's not because _some_ library might be able to do
> something harmful with :init-value t that we should recommend that
> _no_ libraries use :init-value t (except for the rare corner
> case). What about the majority of libraries that don't do harm if
> their minor mode is turned on during load?

Turning on a minor mode is supposed to make a difference, and there
should not be a difference without the user requesting it.

> Unless, that is, you can point to a general problem (harm) that can occur
> with _any_ library...
>
>     And it is not like this is a new debate, anyway.
>
> Sorry, the question is new to me. Point me to the thread, please.
>
>     > Is it appropriate to set the mode to off initially, if the user
>     > wants it on?
>
>     If the user has not indicated that he wants it on, there is no reason
>     to assume so.
>
> Please read what I wrote. I was discussing the case where the user
> specified (setq my-mode t) in .emacs.

It is irrelevant.

> If, as I thought you were suggesting,

I didn't suggest anything of that kind.

> loading the file could somehow override user settings, then it could
> override an explicit t setting as well as an explicit nil
> setting. That was the point here.

Straw man.

>     > The point of :init-value was to specify only a _default_ value, to
>     > be used only if the user expressed no preference beforehand.
>
>     And we are talking about this.  If your insistence about wanting to
>     shoot yourself in the foot is supposed to be representative, one
>     should probably remove the :init-value option altogether.
>
> Your metaphor doesn't help - what are you referring to? Is it true
> or not that loading a file can somehow override user mode-variable
> settings in .emacs?

"Somehow"?  Most certainly.  Though one would avoid it, usually.

> * If true, then that problem should be fixed. If it cannot be fixed,
> then :init-value does not perform as advertised, and it should be
> removed.
>
> * If not true, then I don't see the problem with the library
> specifying an :init-value of either nil or t. If the user's
> preference is always respected, then where's the harm?

Is this some sort of a game with you, or what?  We are talking about
the case where the user has not specified a preference, and Emacs is
turning randomly minor modes on at its whim.

>     > 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.
>
>     You are wildly speculating.
>
> Sorry; I got that speculation from your vague description of "the
> problem".  I asked for a specific scenario leading to "harm" or
> "pain", and that's all I could imagine you meant by your response
> that Customize might load the file behind the user's back. Loading
> the file should only set the mode value if the user has not already
> set it, which is not a problem (if it is, please explain). I figured
> you must be trying to say that loading by Customize somehow
> overrides a user setting. If not, what's the problem?

You are being disingenuous.  The problem is that Emacs should not be
turning minor modes on at random occasions.  It is not like this has
not been said already.

>     We are talking about the case where there
>     is no user setting in .emacs.
>
> If there is no user setting, then what is the problem? If the user
> doesn't have a preference whether loading turns the mode on or
> leaves it off, then why not let the library writer pick a default
> behavior (which is what :init-value is supposedly for)?

Because Emacs is not supposed to be turning on minor modes at random
moments.

> That is the same for any default value.

If the file for a minor mode is not loaded, there is no effect, and no
lighter set in the mode line.  So the only sensible default for a
minor mode is "off", since the default must not change by having the
file loaded: there still must be no effect, and no lighter set.  And
that means "off".

> If a user doesn't have a preference whether `debug-on-error' is t or
> nil at startup, then the default value is used. What is the specific
> problem that you see regarding the default value for a mode
> variable?

That a minor mode has an effect, and this effect should not be
activated as a side effect of a coincidental load.

>     It has been beaten to death even in this thread.
>
> Please point to the thread.

What about "this thread" did you not understand?

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

RE: doc of defining minor modes

[Drew Adams]

OK, I hear the argument as being that a user could be disoriented if a mode
is turned on without his/her being aware of it. That makes sense. It is also
not clearly expressed in the documentation.

As I said, if "you want people to understand and respect [this
recommendation], then it should be clarified and justified (explain why) in
the doc." I do not think the doc is clear on this at all.

The doc should explicitly say that loading a minor mode should not have any
user-visible effect, and explain why. The why should mention that it might
disorient users (or something to that effect). In particular, it should not
speak in terms of "harm" and "pain". No such harm or pain was finally
pointed out, so let's not be alarmist about this. It's enough to say that a
user might be disoriented to suddenly find that a mode was turned on. And
the doc should indicate how that might happen (e.g. Customize loading a
library...), so people understand it.

The doc should explicitly say that, because of this, :init-value should not
be used or should be used only with value nil, except for the corner case
described. And that corner case should be described better. Thx.

Re: doc of defining minor modes

[Miles Bader]

"Drew Adams" <drew.adams@oracle.com> writes:
> I'm not getting this.

That's very clear.

It's been explained repeatedly to you though, so I'm not sure there's
much else we can do.

-Miles
-- 
`To alcohol!  The cause of, and solution to,
 all of life's problems' --Homer J. Simpson

Re: doc of defining minor modes

[Richard Stallman]

The reasons for this rule is simple predictability: all minor modes
are initially disabled until you explicitly enable them, unless it
would not have any effect to do otherwise.  No minor modes get enabled
by anything except explicit enabling, unless they are harmless.

    FWIW, I do not agree. It is sometimes useful to enable a minor mode upon
    load,

I am not sure what that means.  If you present a specific scenario
I could think about it.

    Third, I don't see why we are stating this guideline / recommendation /
    prescription.

To make sure all minor modes follow this rule,
and thus avoid surprising the user.


Please do not start an argument about this.
I do not want to spend any more time on the question.

Re: doc of defining minor modes

[Stefan Monnier]

>     Elisp packages may be loaded because the user specifically
>     wants it to be loaded, but they can also be loaded for all
>     kinds of other unrelated reasons.  So as a matter of principle
>     the user-visible behavior of Emacs should be mostly unchanged
>     by (load <foo>).

>     This often means that minor modes should default to being disabled.

> I don't see why.  Regardless of why/when a file is loaded, it should be
> loaded for some good reason.

It may be loaded for a silly reason.  E.g. compiling a package `foo' which
gratuitously does a (require 'bar).

> For many libraries, that reason includes using a minor mode defined in
> the file.  In those cases, if it causes no harm for the mode to be enabled
> upon load (also the majority of cases, IMO), then why shouldn't the
> library do that?

The question is not whether it does harm, but whether it changes the
user-visible behavior.  An unrequested user-visible change due to some
apparently unrelated action is bad.

> I've still seen no scenario describing the harm. All I've heard is that the
> library might be loaded in any way at any time - so what? Loading the
> library should not override a user setting (e.g. to inhibit turning the mode
> on), no matter how or when the load occurs.

This is irrelevant.  The interesting case is when the user doesn't even know
that minor mode exists.

>     Not always, tho: E.g. foo-aux-mode could default to being
>     enabled without any harm if it only ever affects buffers
>     in foo-mode and foo-mode can't exist without foo-aux-mode
>     also existing (e.g. because they're defined in the
>     same file of because foo.el requires `foo-aux').

> This repeats what is said in the doc. I don't see it as the only, or even
> the typical, case where it should be permissible to use a non-nil
> :init-value.

Feel free to disagree, but this has been decided after a good bit of thought
and experience.


        Stefan

Re: doc of defining minor modes

[David Kastrup]

"Drew Adams" <drew.adams@oracle.com> writes:

> OK, I hear the argument as being that a user could be disoriented if
> a mode is turned on without his/her being aware of it. That makes
> sense. It is also not clearly expressed in the documentation.
>
> As I said, if "you want people to understand and respect [this
> recommendation], then it should be clarified and justified (explain
> why) in the doc." I do not think the doc is clear on this at all.
>
> The doc should explicitly say that loading a minor mode should not
> have any user-visible effect, and explain why. The why should
> mention that it might disorient users (or something to that
> effect). In particular, it should not speak in terms of "harm" and
> "pain". No such harm or pain was finally pointed out, so let's not
> be alarmist about this.

What constitutes "harm" to you?  If a little man jumps out from the
copmuter screen and stabs the user?

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

RE: doc of defining minor modes

[Drew Adams]

    No minor modes get enabled
    by anything except explicit enabling, unless they are harmless.

That was the question: what does it mean to be harmless? The answer I got
was that enabling the mode is always itself harmful, because it is
disorienting. That implies that "unless they are harmless" means unless pigs
fly.

        It is sometimes useful to enable a minor mode upon load

    I am not sure what that means. If you present a specific scenario
    I could think about it.

A simple, standalone, external library that defines a minor mode. The user
alone can load the library. (I don't see how it could be loaded
automatically, since it is unknown to Emacs until it is loaded.) The user
simply loads the library, turning on the mode automatically. Where's the
problem? If the user wants to load the library without turning on the mode,
then s?he sets the mode variable to nil first.

Whether I'm right or wrong about a standalone library being harmless, the
doc needs clarification. It is not at all clear why we provide :init-value
and then tell people not to use it. The potential problem mentioned here
involving automatic loading of a library behind the user's back is not
mentioned in the doc, and it is the motivation behind the admonition not to
use :init-value t. It's fine to issue a guideline "Don't do this!", but it
helps to explain why the rule makes sense.

RE: doc of defining minor modes

[Drew Adams]

I wrote this about the doc changes needed for this:

    OK, I hear the argument as being that a user could be
    disoriented if a mode is turned on without his/her being
    aware of it. That makes sense. It is also
    not clearly expressed in the documentation.

    As I said, if "you want people to understand and respect [this
    recommendation], then it should be clarified and justified
    (explain why) in the doc." I do not think the doc is clear on
    this at all.

    The doc should explicitly say that loading a minor mode should
    not have any user-visible effect, and explain why. The why
    should mention that it might disorient users (or something to
    that effect). In particular, it should not speak in terms of
    "harm" and "pain". No such harm or pain was finally pointed out,
    so let's not be alarmist about this. It's enough to say that a
    user might be disoriented to suddenly find that a mode was
    turned on. And the doc should indicate how that might happen
    (e.g. Customize loading a library...), so people understand it.

    The doc should explicitly say that, because of this,
    :init-value should not be used or should be used only with
    value nil, except for the corner case described. And that
    corner case should be described better. Thx.

It's not obvious to readers of the doc why we provide an :init-value
possibility and yet we warn people not to use it (except in a rare case).
There needs to be a good explanation of this uncommon coupling. The
explanation needs to indicate how the problem that the admonition hopes to
prevent could arise, that is, _how_ a library might get loaded without being
loaded directly by the user. That is not obvious.

I still have a question regarding that:

I think I understand what was said here about Customize, menu access, and
byte-compiling having a possible side effect of loading a library in some
circumstances. But doesn't that apply only to certain kinds of libraries,
which are not the common one-off, standalone, external libraries?

Consider a (typical) external library that is not required by any other
library. It is not part of Emacs itself; nothing in it is preloaded. Are you
saying that there is some way that browsing Customize or using a menu or
byte-compiling some file would cause that library to be loaded? Is there
some way for it to be loaded without the user explicitly loading it? If so,
this should be explained, because it is really not obvious.

I do not see how Emacs would even know of the existence of such a library
until it is loaded. I would think that for such a library only the user can
load it, so there is no way the minor mode could be turned on behind the
user's back. I want to understand this better (and doc readers will too), if
the problem mentioned can indeed happen in this case also. Many external
libraries are standalone like this, so this is not an atypical case.

If it is correct that such libraries don't present a problem, then this
distinction should be made in the doc. For in that case the admonition would
be irrelevant and overkill for many libraries. In that case, let's mention
that _if_ a library is required by another that is loaded or _if_ a
library's customizeable features are somehow available to Customize before
it is loaded or _if_ a library's command is in a menu before it is loaded
... _then_ there is the possibility that the library will be loaded other
than by the user directly. And in that case, the user could be disoriented.
So, in that case, use only :init-value nil.

Re: doc of defining minor modes

[David Kastrup]

"Drew Adams" <drew.adams@oracle.com> writes:

> Consider a (typical) external library that is not required by any
> other library. It is not part of Emacs itself; nothing in it is
> preloaded. Are you saying that there is some way that browsing
> Customize or using a menu or byte-compiling some file would cause
> that library to be loaded? Is there some way for it to be loaded
> without the user explicitly loading it? If so, this should be
> explained, because it is really not obvious.

Many external libraries use autoload cookies in order to create a
short startup file that gets loaded unconditionally in order to make
Emacs aware of the library's existence.

> I do not see how Emacs would even know of the existence of such a
> library until it is loaded.

Autoloads.  It does not make sense for larger libraries to get loaded
when they are possibly not going to be needed.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: doc of defining minor modes

[Stefan Monnier]

> A simple, standalone, external library that defines a minor mode. The user
> alone can load the library.  (I don't see how it could be loaded
> automatically, since it is unknown to Emacs until it is loaded.)  The user
> simply loads the library, turning on the mode automatically.
> Where's the problem?

The problem is that we can't integrate such a package into Emacs without
first fixing this behavior.  So of course we don't encourage that.


        Stefan

Re: doc of defining minor modes

[Stefan Monnier]

> It's not obvious to readers of the doc why we provide an :init-value
> possibility and yet we warn people not to use it (except in a rare case).
> There needs to be a good explanation of this uncommon coupling.
> The explanation needs to indicate how the problem that the admonition
> hopes to prevent could arise, that is, _how_ a library might get loaded
> without being loaded directly by the user.  That is not obvious.

I don't think it's worth the trouble to write a long explanation.
It's perfectly OK to have arguments and features marked as "don't ever use
this unless you really know what you're doing".


        Stefan

RE: doc of defining minor modes

[Drew Adams]

    What constitutes "harm" to you?  If a little man jumps out from the
    copmuter screen and stabs the user?
    
Only if that disorients the user.
If the user asked him to do that, then... ;-)

RE: doc of defining minor modes

[Drew Adams]

    > It's not obvious to readers of the doc why we provide an :init-value
    > possibility and yet we warn people not to use it (except in a
    > rare case). There needs to be a good explanation of this uncommon
    > coupling. The explanation needs to indicate how the problem that the
    > admonition hopes to prevent could arise, that is, _how_ a library
    > might get loaded without being loaded directly by the user.
    > That is not obvious.

    I don't think it's worth the trouble to write a long explanation.
    It's perfectly OK to have arguments and features marked as
    "don't ever use this unless you really know what you're doing".

It's more like "don't use this if you _know_ what you're doing and your
library is exceptional" (large, complex, coupled with other libraries,
preloaded,...).

The typical, simple case of a standalone external library will not be
preloaded or required by another library, it will not have autoload cookies,
and it would never be loaded behind the user's back. I think it's worth
pointing out what the potential but uncommon problem is.

    The problem is that we can't integrate such a package into Emacs without
    first fixing this behavior.  So of course we don't encourage that.

Changing :init-value t to :init-value nil would be the least of your
integration worries. I really don't see that concern as justification for
such a blanket admonition.

It makes sense, in any case and _especially_ if the admonition is kept as
general as it is, to explain the problem, so programmers know what they're
doing and why.

RE: doc of defining minor modes

[Drew Adams]

    > Consider a (typical) external library that is not required by any
    > other library. It is not part of Emacs itself; nothing in it is
    > preloaded. Are you saying that there is some way that browsing
    > Customize or using a menu or byte-compiling some file would cause
    > that library to be loaded? Is there some way for it to be loaded
    > without the user explicitly loading it? If so, this should be
    > explained, because it is really not obvious.

    Many external libraries use autoload cookies in order to create a
    short startup file that gets loaded unconditionally in order to make
    Emacs aware of the library's existence.

Yes, thanks. I almost added autoload cookies to the list myself, but I
didn't want to include something that wasn't already mentioned.

IIUC, if a external library has no autoload cookies (and it is not required
by another library etc.), then there should be no problem. Do you agree?

And even if a library has autoload cookies, there can be a problem only if
the user creates a loaddefs.el (or equivalent short startup file) that
includes those autoloads. That is, the user must explicitly do something in
order to manifest the problem in the case of a standalone library. And that
something is fairly sophisticated, in Lisp - e.g. use
`update-file-autoloads' on that library. This is hardly a case of surprising
an uninformed user. The library is not loaded behind his back in this case.

Of course, someone besides the end user might create the startup file based
on that library. But that person can then set the mode variable to nil. IOW,
if someone uninformed tries to use the library then there is no problem, and
if someone informed sets the library up for use by others then s?he will
know how to inhibit the mode at startup.

    > I do not see how Emacs would even know of the existence of such a
    > library until it is loaded.

    Autoloads.  It does not make sense for larger libraries to get loaded
    when they are possibly not going to be needed.

IIUC, it is not autoloads per se that are the problem, but creating a
startup file based on them. That is, a plain autoload (autoload 'foo-cmd
"foo" "foo t) that loads a library based on first use of a function should
not be a problem - do you agree?

The simple case of an unsophisticated user obtaining a standalone external
library and using it is, I think, quite common. And perhaps the most common
case is for such a library not to have autoload cookies.

For such simple cases, I don't see the problem arising. It would be good for
the doc to explain what the potential problem is and from where it can
arise.

Re: doc of defining minor modes

[David Kastrup]

"Drew Adams" <drew.adams@oracle.com> writes:

>     > It's not obvious to readers of the doc why we provide an :init-value
>     > possibility and yet we warn people not to use it (except in a
>     > rare case). There needs to be a good explanation of this uncommon
>     > coupling. The explanation needs to indicate how the problem that the
>     > admonition hopes to prevent could arise, that is, _how_ a library
>     > might get loaded without being loaded directly by the user.
>     > That is not obvious.
>
>     I don't think it's worth the trouble to write a long explanation.
>     It's perfectly OK to have arguments and features marked as
>     "don't ever use this unless you really know what you're doing".
>
> It's more like "don't use this if you _know_ what you're doing and your
> library is exceptional" (large, complex, coupled with other libraries,
> preloaded,...).
>
> The typical, simple case of a standalone external library will not
> be preloaded or required by another library, it will not have
> autoload cookies, and it would never be loaded behind the user's
> back.

I don't know what universe you are living in, but practically _all_
external Elisp I know comes with instructions of what to put into your
.emacs or elsewhere so that the file will get loaded on-demand.  And
if the package is somewhat larger, it will come with its own stub file
for achieving this.

> I think it's worth pointing out what the potential but uncommon
> problem is.

The problem is common, and that's why we bothered with it.

>     The problem is that we can't integrate such a package into Emacs
>     without first fixing this behavior.  So of course we don't
>     encourage that.
>
> Changing :init-value t to :init-value nil would be the least of your
> integration worries.

There is no sense in having a library behave differently once it is
included in Emacs.

> I really don't see that concern as justification for such a blanket
> admonition.

You are being obnoxious.  It has been pointed out to you about a dozen
times that this was not done on accident, has been discussed before,
and you were asked to stop ignoring the decision that has already been
reached and explained to you.  Not least of all by Richard.

Your opinion is different.  Guess what, we noticed.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: doc of defining minor modes

[Stefan Monnier]

>     I don't think it's worth the trouble to write a long explanation.
>     It's perfectly OK to have arguments and features marked as
>     "don't ever use this unless you really know what you're doing".

> It's more like "don't use this if you _know_ what you're doing and your
> library is exceptional" (large, complex, coupled with other libraries,
> preloaded,...).

You seem to want to document the technical problems that may come up.
I have no interest in doing that.  All I know is that it tends to create
problems so we discourage minor modes that are enabled by default.

If you can come up with a good reason why it may be *useful* (as opposed to
harmless) to have a minor mode enabled by default, please enlighten us.


        Stefan

Re: doc of defining minor modes

[Andreas Schwab]

"Drew Adams" <drew.adams@oracle.com> writes:

> And even if a library has autoload cookies, there can be a problem only if
> the user creates a loaddefs.el (or equivalent short startup file) that
> includes those autoloads.

That is typically done as part of the installation process.

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux Products GmbH, Maxfeldstraße 5, 90409 Nürnberg, Germany
PGP key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."