Re: Enabling a globalized-minor-mode by default

[Kévin Le Gouguec]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> I guess the docstring is so long already that adding a couple more lines
> couldn't hurt, but really it's just a general principle, not specific to
> minor modes.

Fair enough.  I don't know how people come to write minor modes (I was
just trying to "fix" one).  Maybe most of them are diligent enough to
read the manual first?  I'd bet that a few lost souls will just read
define-minor-mode's docstring and go from there, and won't necessarily
be acquainted with this general principle.

For better or worse, Emacs's docstrings look fairly comprehensive, so
it's tempting to assume they cover everything one needs to know.  I, for
one, have yet to acquire the reflex to dig up the manual when something
doesn't match the expectations I got from the docstring.

It's not that C-h S is harder to hit than C-h f, but if nothing in the
docstring hints at things being More Complicated Than They Look™, it
won't occur to me to reach for the manual.

> Would the patch below help?
>
>     diff --git a/lisp/emacs-lisp/easy-mmode.el b/lisp/emacs-lisp/easy-mmode.el
>     index e3eb9294ed..1cde808e7a 100644
>     --- a/lisp/emacs-lisp/easy-mmode.el
>     +++ b/lisp/emacs-lisp/easy-mmode.el
>     @@ -137,6 +137,10 @@ define-minor-mode
>      usage of the mode argument.
>      
>      Optional INIT-VALUE is the initial value of the mode's variable.
>     +  Note that the minor mode function won't be called by setting
>     +  this option, so the value *reflects* the minor mode's natural
>     +  initial state, rather than *setting* it.
>     +  In the vast majority of cases it should be nil.
>      Optional LIGHTER is displayed in the mode line when the mode is on.
>      Optional KEYMAP is the default keymap bound to the mode keymap.
>        If non-nil, it should be a variable name (whose value is a keymap),

I think it does.  AFAICT the current description does nothing to warn
the user that there are two sources of truth (the mode variable, and
calling the mode function).  IMO it's easy to assume that INIT-VALUE
controls activation: what would be the point of letting the user set the
variable without calling the mode function?

The added lines hint that activation is more or less independent of
INIT-VALUE; I think it's enough to prompt the user to go fish for more
documentation.

Thank you for coming up with these!


PS: while trying to assess how common the ":init-value t enables the
    mode" fallacy is (if at all), I found this thread:

    
https://old.reddit.com/r/emacs/comments/aw84yn/defineminormode_initvalue_t_not_running_its_hook/

    This smonnier person sure sounds like a knowledgeable fellow :D and
    look at /u/tarsius_, with this helpful example code!