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

4 files changed, 35 insertions, 11 deletions

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index f7013da9433..bd94aeadf15 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -1490,10 +1490,11 @@ alist @code{minor-mode-map-alist}.  @xref{Definition of minor-mode-map-alist}.
   One use of minor mode keymaps is to modify the behavior of certain
 self-inserting characters so that they do something else as well as
 self-insert.  (Another way to customize @code{self-insert-command} is
-through @code{post-self-insert-hook}.  Apart from this, the facilities
-for customizing @code{self-insert-command} are limited to special cases,
-designed for abbrevs and Auto Fill mode.  Do not try substituting your
-own definition of @code{self-insert-command} for the standard one.  The
+through @code{post-self-insert-hook}, see @ref{Commands for
+Insertion}.  Apart from this, the facilities for customizing
+@code{self-insert-command} are limited to special cases, designed for
+abbrevs and Auto Fill mode.  Do not try substituting your own
+definition of @code{self-insert-command} for the standard one.  The
 editor command loop handles this function specially.)
 
 Minor modes may bind commands to key sequences consisting of @kbd{C-c}
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 3d26d0930f7..1e19f75d682 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -525,9 +525,17 @@ responsible for calling @code{blink-paren-function} when the inserted
 character has close parenthesis syntax (@pxref{Blinking}).
 
 @vindex post-self-insert-hook
+@vindex self-insert-uses-region-functions
 The final thing this command does is to run the hook
 @code{post-self-insert-hook}.  You could use this to automatically
-reindent text as it is typed, for example.
+reindent text as it is typed, for example.  If any function on this
+hook needs to act on the region (@pxref{The Region}), it should make
+sure Delete Selection mode (@pxref{Using Region, Delete Selection, ,
+emacs, The GNU Emacs Manual}) doesn't delete the region before
+@code{post-self-insert-hook} functions are invoked.  The way to do so
+is to add a function that returns @code{nil} to
+@code{self-insert-uses-region-functions}, a special hook that tells
+Delete Selection mode it should not delete the region.
 
 Do not try substituting your own definition of
 @code{self-insert-command} for the standard one.  The editor command
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.")