`define-globalized-minor-mode': why the need for a separate TURN-ON function?

`define-globalized-minor-mode': why the need for a separate TURN-ON function?

[Drew Adams]

I've only looked briefly at this, and am no doubt not noticing something.

Anyway, why for `define-globalized-minor-mode' must one define a separate
TURN-ON function to turn the mode on, but using the (local) minor-mode function
suffices to turn it off?

The relevant code in the definition of `define-globalized-minor-mode' seems to
be this part:

;; Go through existing buffers.
(dolist (buf (buffer-list))
  (with-current-buffer buf
    (if ,global-mode (,turn-on) (when ,mode (,mode -1))))))

Why not just this?

(dolist (buf (buffer-list))
  (with-current-buffer buf
    (if ,global-mode (,mode 1) (when ,mode (,mode -1))))))

There is another bit of code later on, but it seems similar - same question: why
not just (,mode 1) instead of (,turn-on)?  The (local) minor-mode function is
already defined, and it does a fine job of turning on the mode in a single
buffer - why the need for another, no-args function to do that?

There is no doubt a reason, otherwise we wouldn't have introduced this extra
TURN-ON hoop as a mandatory arg to `define-globalized-minor-mode'.  (I could
understand an optional arg, I guess, for the cases where such a turn-on function
already exists and might differ for some reason from what the minor-mode
function does with a positive arg.)

What am I missing?  Thx.

Re: `define-globalized-minor-mode': why the need for a separate TURN-ON function?

[Stefan Monnier]

> I've only looked briefly at this, and am no doubt not noticing
> something.  Anyway, why for `define-globalized-minor-mode' must one
> define a separate TURN-ON function to turn the mode on, but using the
> (local) minor-mode function suffices to turn it off?

As the docstring says: "try to turn MODE on if applicable for that
buffer".  That's different to MODE itself which should turn it in if at
all possible.


        Stefan

RE: `define-globalized-minor-mode': why the need for a separate TURN-ON function?

[Drew Adams]

> > why for `define-globalized-minor-mode' must one
> > define a separate TURN-ON function to turn the mode on, but 
> > using the (local) minor-mode function suffices to turn it off?
> 
> As the docstring says: "try to turn MODE on if applicable for that
> buffer".  That's different to MODE itself which should turn 
> it in if at all possible.

I see; thanks.  The "for that buffer" qualification did not jump out at me,
especially since the local mode already presumably does its thing for the
specific buffer where it is turned on.  The difference is that in the local case
it is the user who decides whether the mode makes sense and can be turned "for
that buffer".  In the global case it is the command that must decide separately,
for each buffer.

I understand now, but this was not at all obvious (to me) from just that 3-word
qualification.  You might want to make this distinction a bit more obvious in
the doc.  Perhaps say what you just said here, or add a brief example where the
distinction makes sense.