bug#29373: 24.5; doc string of `self-insert-uses-region-functions'

[Eli Zaretskii <eliz@gnu.org>]

> 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.