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, 14 insertions, 5 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