* bug#29373: 24.5; doc string of `self-insert-uses-region-functions'
[not found] ` <<83y3mv8v1r.fsf@gnu.org>
@ 2017-11-24 17:33 ` Drew Adams
2017-11-25 23:56 ` Noam Postavsky
0 siblings, 1 reply; 6+ messages in thread
From: Drew Adams @ 2017-11-24 17:33 UTC (permalink / raw)
To: Eli Zaretskii, Drew Adams; +Cc: 29373
> Sometimes it's impossible to limit a line to 70 characters without
> incurring worse problems. This is one such case.
I don't see any such "worse problems" in this case.
Without any change to the wording (which does need
to be changed), this shows no "worse problems":
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.
> > > > 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.
> >
> > Nothing derogatory intended.
>
> That sentence could simply be omitted without any effect on the
> report. May I suggest that you try to refrain from such unneeded
> remarks?
>
> > That's a summary of the problem - lack of clarity overall.
>
> "Lack of clarity" would be fine (although it, too, adds nothing).
> "Incomprehensible" is not a summary.
"Incomprehensible" was not the summary I used.
"Close to incomprehensible" is the summary I used.
I stand by that characterization, as one user
reporting a doc problem: to me, the doc string was
close to incomprehensible. You might not find it so.
It's understandable that a new doc string might not
have had the attention it deserves, and so is not
as clear as it could be.
To me, this one was not really understandable.
Perhaps you prefer the statement, "I don't
understand this doc string, and I think others
may also have trouble making sense of it."
And no, I don't think that such a statement adds
nothing, even if it is better if accompanied by
guesses about the meaning, suggestions for
improvement, or pointing out particular places
that are especially problematic for the reporter.
If a reporter has no clue what is meant and no
clue what parts are particularly unclear, the
simple report that a doc string is unclear to
that reporter can help. We can disagree about
this, of course.
But my guess is that if you agree with the
reporter after reading such an incomplete "Huh?"
report then the aim is reached. And if you
disagree with the reporter - the doc is clear
to you, even if the reporter doesn't understand
it at all - it is still good that the perceived
problem was reported, and no harm was done.
We can disagree about this too, of course.
^ permalink raw reply [flat|nested] 6+ messages in thread
[parent not found: <<d8b52361-9340-4a18-b2fd-557c78c382d7@default>]
* bug#29373: 24.5; doc string of `self-insert-uses-region-functions'
@ 2017-11-21 2:56 Drew Adams
2017-11-24 10:50 ` Eli Zaretskii
0 siblings, 1 reply; 6+ messages in thread
From: Drew Adams @ 2017-11-21 2:56 UTC (permalink / raw)
To: 29373
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'
^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#29373: 24.5; doc string of `self-insert-uses-region-functions'
2017-11-21 2:56 Drew Adams
@ 2017-11-24 10:50 ` Eli Zaretskii
0 siblings, 0 replies; 6+ messages in thread
From: Eli Zaretskii @ 2017-11-24 10:50 UTC (permalink / raw)
To: Drew Adams; +Cc: 29373-done
> Date: Mon, 20 Nov 2017 18:56:15 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
>
> 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.
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2017-11-25 23:56 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
[not found] <<<d8b52361-9340-4a18-b2fd-557c78c382d7@default>
[not found] ` <<<83h8tk9chp.fsf@gnu.org>
[not found] ` <<86584c33-6e52-4cf5-8e22-bb9952b296b2@default>
[not found] ` <<83y3mv8v1r.fsf@gnu.org>
2017-11-24 17:33 ` bug#29373: 24.5; doc string of `self-insert-uses-region-functions' Drew Adams
2017-11-25 23:56 ` Noam Postavsky
[not found] <<d8b52361-9340-4a18-b2fd-557c78c382d7@default>
[not found] ` <<83h8tk9chp.fsf@gnu.org>
2017-11-24 16:43 ` Drew Adams
2017-11-24 17:07 ` Eli Zaretskii
2017-11-21 2:56 Drew Adams
2017-11-24 10:50 ` Eli Zaretskii
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).