--- Begin Message ---
|
Subject: |
24.5; doc string of `self-insert-uses-region-functions' |
|
Date: |
Mon, 20 Nov 2017 18:56:15 -0800 (PST) |
Two lines of the doc string are too long.
The doc string is close to incomprehensible.
Special hook to tell if `self-insert-command' will use the region.
It must be called via `run-hook-with-args-until-success' with no arguments.
Any `post-self-insert-command' which consumes the region should
register a function on this hook so that things like `delete-selection-mode'
can refrain from consuming the region.
HOW does this hook "tell if `self-insert-command' will use the region"?
What does a function on this hook need to do or return, to tell that?
And what does it mean for `self-insert-command' to "use the region"?
What does "any `post-self-insert-command'" even mean? What is meant by
"consumes the region"? Does "consume" mean the same thing in each
occurrence here? What is meant by "registering" a function on a hook?
Is this ONLY about `delete-selection-mode'? If not, what else is it
for?
A guess is that this is just a way to conditionalize the treatment of
`self-insert-command' by `delete-selection-mode'. In some mode
(`electric-pair-mode'), you want to use a certain function as the value
of property `delete-selection' for symbol `self-insert-command'.
If so, then things would likely be clearer if that was said.
In that case, it needs to be understood that `delete-selection-mode'
checks the value of property `delete-selection' on
`self-insert-command', and if that value is nil or is a function that
returns nil then `delete-selection-mode' does nothing.
Say that, together with the fact that the function value of property
`delete-selection-mode' for `self-insert-command' runs the hook
functions in order, returning nil if any of them returns non-nil.
So a function on the hook should return non-nil when its aim is to
prevent deletion of the region by `self-insert-command'. Say that.
Looking at the uses in the Emacs code, the aim seems to be only to
prevent deletion of the region by `delete-selection-mode' before
`self-insert-command' does its thing. Whether `self-insert-command'
"uses" the region or "consumes" it, or even deletes it or ignores it, is
irrelevant, AFAICT. All that matters is that this gives you a way to
decide conditionally whether `delete-selection-mode' deletes the region
on its pre-hook.
In GNU Emacs 24.5.1 (i686-pc-mingw32)
of 2015-04-11 on LEG570
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
`configure --prefix=/c/usr --host=i686-pc-mingw32'
--- End Message ---
--- Begin Message ---
|
Subject: |
Re: bug#29373: 24.5; doc string of `self-insert-uses-region-functions' |
|
Date: |
Fri, 24 Nov 2017 12:50:42 +0200 |
> Date: Mon, 20 Nov 2017 18:56:15 -0800 (PST)
> From: Drew Adams <address@hidden>
>
> Two lines of the doc string are too long.
Longer than 79 characters? I didn't find any such lines.
> The doc string is close to incomprehensible.
Such derogatory remarks are best kept out of bug reports. The facts
are grave enough to tell we should fix this.
> Special hook to tell if `self-insert-command' will use the region.
> It must be called via `run-hook-with-args-until-success' with no arguments.
> Any `post-self-insert-command' which consumes the region should
> register a function on this hook so that things like `delete-selection-mode'
> can refrain from consuming the region.
>
> HOW does this hook "tell if `self-insert-command' will use the region"?
> What does a function on this hook need to do or return, to tell that?
> And what does it mean for `self-insert-command' to "use the region"?
>
> What does "any `post-self-insert-command'" even mean? What is meant by
> "consumes the region"? Does "consume" mean the same thing in each
> occurrence here? What is meant by "registering" a function on a hook?
post-self-insert-command really meant to refer to post-self-insert-hook.
> A guess is that this is just a way to conditionalize the treatment of
> `self-insert-command' by `delete-selection-mode'. In some mode
> (`electric-pair-mode'), you want to use a certain function as the value
> of property `delete-selection' for symbol `self-insert-command'.
>
> If so, then things would likely be clearer if that was said.
I clarified that.
> In that case, it needs to be understood that `delete-selection-mode'
> checks the value of property `delete-selection' on
> `self-insert-command', and if that value is nil or is a function that
> returns nil then `delete-selection-mode' does nothing.
The first part was already in delsel.el. I made clear that
self-insert-command uses this hook via delete-selection-uses-region-p.
> Say that, together with the fact that the function value of property
> `delete-selection-mode' for `self-insert-command' runs the hook
> functions in order, returning nil if any of them returns non-nil.
This is the usual behavior of run-hook-with-args-until-success.
> So a function on the hook should return non-nil when its aim is to
> prevent deletion of the region by `self-insert-command'. Say that.
Done.
--- End Message ---