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