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.