Subject: bug#76535: Recommend against turn-on-<FOO>-mode functions

From: Drew Adams <[email-masked]>
Date: Tue, 25 Feb 2025 05:36:44 +0000

> > They aren't redundant for global minor modes created using
> > `define-global-minor-mode' and `define-globalized-minor-mode',
> > AFAIK.  Arg TURN-ON is a required argument.
> >
> >   TURN-ON is a function that will be called with no args in every
> >   buffer and that should try to turn MODE on if applicable for
> >   that buffer.
> 
> Just because the arg is called "TURN-ON" doesn't mean it needs to take
> an argument called `turn-on-FOO-mode` nor that it should behave the same
> as `turn-on-FOO-mode`.

Maybe I misunderstood the bug request; sorry, if so.

I didn't understand it to be about functions named
that way (or any particular way).

I don't think the wishlist wish was very clear, if
my understanding was indeed incorrect:

  How about adding to tips.texi a recommendation
  not to add any new functions like these?
                               ^^^^^^^^^^

    (defun turn-on-<FOO>-mode () (<FOO>-mode 1))
    (defun turn-off-<FOO>-mode () (<FOO>-mode -1))

Just what was meant by "like these"?

I understood "any new functions like these" to mean
any TURN-ON functions, with whatever name and with
whatever behavior, as long as they try to turn on
the mode whenever applicable in some buffer.  IOW,
just what the doc for arg TURN-ON says:

  a function that will be called with no args in
  every buffer and that should try to turn MODE on
  if applicable for that buffer

What else is the wish advising against, if not such
a function?

Provided you're right, and such a TURN-ON function
wasn't what was meant, and won't be what's proscribed
in the proposed "tips", great.

In that case, please at least come up with some clear
wording for the tips.  And for the wishlist proposal,
please say clearly what's being proposed - just what
do you want to advise users not to do?

But in that case, why would any such tips be needed?
Would anyone really think, reading that doc, that the
required TURN-ON arg needs to be a function named
`turn-on-...-mode'?  Has that actually been a problem
- users thinking that?

It's also not clear to me just what you mean by

  "nor that it should behave the same as
  `turn-on-FOO-mode`"

What exactly is the `turn-on-FOO-mode' behavior that
you want to tell users the function doesn't need to
provide, if by that you mean something other than
just be able to be called with no args in any buffer
and when called "try to turn MODE on if applicable
for that buffer"?

You say it doesn't need to behave "the same as
`turn-on-FOO-mode'".  What does that mean?  How does
the presumed function `turn-on-FOO-mode' behave, if
not just as described for arg TURN-ON?  What behavior
doesn't the function need to have?

Sorry I'm not getting your drift.  Can you clarify
it a bit?