Improve documentation of self-insert-uses-region-functions

* lisp/simple.el (self-insert-uses-region-functions): Clarify the
doc string.
* lisp/delsel.el (delete-selection-uses-region-p): Mention
'self-insert-command' in the doc string.  (Bug#29373)

* doc/lispref/text.texi (Commands for Insertion): Mention
'self-insert-uses-region-functions'.
* doc/lispref/modes.texi (Keymaps and Minor Modes): Add a
cross-reference to "Commands for Insertion".

2 files changed, 21 insertions, 6 deletions

diff --git a/lisp/delsel.el b/lisp/delsel.el
index 17b46efc7cb..65b2cb85cea 100644
--- a/lisp/delsel.el
+++ b/lisp/delsel.el
@@ -256,12 +256,18 @@ See `delete-selection-helper'."
                                   (get this-command 'delete-selection)))))
 
 (defun delete-selection-uses-region-p ()
-  "Return t when the current command will be using the region
-rather than having `delete-selection' delete it, nil otherwise.
+  "Return t when `delete-selection-mode' should not delete the region.
+
+The `self-insert-command' could be the current command or may be
+called by the current command.  If this function returns nil,
+then `delete-selection' is allowed to delete the region.
 
 This function is intended for use as the value of the
 `delete-selection' property of a command, and shouldn't be used
-for anything else."
+for anything else.  In particular, `self-insert-command' has this
+function as its `delete-selection' property, so that \"electric\"
+self-insert commands that act on the region could adapt themselves
+to `delete-selection-mode'."
   (not (run-hook-with-args-until-success
         'self-insert-uses-region-functions)))
 
diff --git a/lisp/simple.el b/lisp/simple.el
index 7d47d0f8645..d629fb66599 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -401,9 +401,18 @@ Other major modes are defined by comparison with this one."
 (defvar self-insert-uses-region-functions nil
   "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.")
+
+If any function on this hook returns a non-nil value, `delete-selection-mode'
+will act on that value (see `delete-selection-helper'), and will
+usually delete the region.  If all the functions on this hook return
+nil, it is an indiction that `self-insert-command' needs the region
+untouched by `delete-selection-mode', and will itself do whatever is
+appropriate with the region.
+Any function on `post-self-insert-hook' which act on the region should
+add a function to this hook so that `delete-selection-mode' could
+refrain from deleting the region before `post-self-insert-hook'
+functions are called.
+This hook is run by `delete-selection-uses-region-p', which see.")
 
 (defvar hard-newline (propertize "\n" 'hard t 'rear-nonsticky '(hard))
   "Propertized string representing a hard newline character.")