Improve documentation of Delete Selection mode

* lisp/delsel.el (delete-selection-mode)
(delete-selection-helper): Update and expand the doc strings.
(Bug#22296)

* doc/emacs/mark.texi (Using Region): Document the behavior of
delete commands in Delete Selection mode.  (Bug#22296)

* doc/lispref/markers.texi (The Mark): Document how to add the
support for Delete Selection mode to Lisp programs. (Bug#22296)

3 files changed, 49 insertions, 9 deletions

diff --git a/doc/emacs/mark.texi b/doc/emacs/mark.texi
index 28b4e3ddae..98980d5fb3 100644
--- a/doc/emacs/mark.texi
+++ b/doc/emacs/mark.texi
@@ -288,7 +288,9 @@ instead signal an error if the mark is inactive.
 active---for example, typing @kbd{a} inserts the character @samp{a},
 then deactivates the mark.  If you enable Delete Selection mode, a
 minor mode, then inserting text while the mark is active causes the
-text in the region to be deleted first.  To toggle Delete Selection
+text in the region to be deleted first.  Also, commands that normally
+delete just one character, such as @kbd{C-d} or @kbd{@key{DEL}}, will
+delete the entire region instead.  To toggle Delete Selection
 mode on or off, type @kbd{M-x delete-selection-mode}.
 
 @node Mark Ring
diff --git a/doc/lispref/markers.texi b/doc/lispref/markers.texi
index d44085527a..bf18543138 100644
--- a/doc/lispref/markers.texi
+++ b/doc/lispref/markers.texi
@@ -659,6 +659,24 @@ more marks than this are pushed onto the @code{mark-ring},
 @c There is also global-mark-ring-max, but this chapter explicitly
 @c does not talk about the global mark.
 
+@cindex @code{delete-selection}, symbol property
+@findex delete-selection-helper
+@findex delete-selection-pre-hook
+When Delete Selection mode (@pxref{Using Region, Delete Selection, ,
+emacs, The GNU Emacs Manual}) is enabled, commands that operate on the
+active region (a.k.a.@: ``selection'') behave slightly differently.
+This works by adding the function @code{delete-selection-pre-hook} to
+the @code{pre-command-hook} (@pxref{Command Overview}).  That function
+calls @code{delete-selection-helper} to delete the selection as
+appropriate for the command.  If you want to adapt a command to Delete
+Selection mode, put the @code{delete-selection} property on the
+function's symbol (@pxref{Symbol Plists}); commands that don't have
+this property on their symbol won't delete the selection.  This
+property can have one of several values to tailor the behavior to what
+the command is supposed to do; see the doc strings of
+@code{delete-selection-pre-hook} and @code{delete-selection-helper}
+for the details.
+
 @node The Region
 @section The Region
 @c The index entry must be just "region" to make it the first hit
diff --git a/lisp/delsel.el b/lisp/delsel.el
index 46eea973a7..6a819ebbf6 100644
--- a/lisp/delsel.el
+++ b/lisp/delsel.el
@@ -37,16 +37,26 @@
 ;; the values:
 ;;  `yank'
 ;;      For commands which do a yank; ensures the region about to be
-;;      deleted isn't yanked.
+;;      deleted isn't immediately yanked back, which would make the
+;;      command a no-op.
 ;;  `supersede'
 ;;      Delete the active region and ignore the current command,
-;;      i.e. the command will just delete the region.
+;;      i.e. the command will just delete the region.  This is for
+;;      commands that normally delete small amounts of text, like
+;;      a single character -- they will instead delete the whole
+;;      active region.
+;;  `kill'
+;;      `kill-region' is used on the selection, rather than
+;;      `delete-region'.  (Text selected with the mouse will typically
+;;      be yankable anyhow.)
 ;;  t
 ;;      The normal case: delete the active region prior to executing
 ;;      the command which will insert replacement text.
-;;  <function>
+;;  FUNCTION
 ;;      For commands which need to dynamically determine this behavior.
-;;      The function should return one of the above values or nil.
+;;      FUNCTION should take no argument and return one of the above
+;;      values, or nil.  In the latter case, FUNCTION should itself
+;;      do with the active region whatever is appropriate."
 
 ;;; Code:
 
@@ -66,7 +76,11 @@ enable the mode if ARG is omitted or nil.
 
 When Delete Selection mode is enabled, typed text replaces the selection
 if the selection is active.  Otherwise, typed text is just inserted at
-point regardless of any selection."
+point regardless of any selection.  Also, commands that normally delete
+just one character will delete the entire selection instead.
+
+See `delete-selection-helper' and `delete-selection-pre-hook' for
+information on adapting behavior of commands in Delete Selection mode."
   :global t :group 'editing-basics
   (if (not delete-selection-mode)
       (remove-hook 'pre-command-hook 'delete-selection-pre-hook)
@@ -147,10 +161,14 @@ With ARG, repeat that many times.  `C-u' means until end of buffer."
   "Delete selection according to TYPE:
  `yank'
      For commands which do a yank; ensures the region about to be
-     deleted isn't yanked.
+     deleted isn't immediately yanked back, which would make the
+     command a no-op.
  `supersede'
      Delete the active region and ignore the current command,
-     i.e. the command will just delete the region.
+     i.e. the command will just delete the region.  This is for
+     commands that normally delete small amounts of text, like
+     a single character -- they will instead delete the whole
+     active region.
  `kill'
      `kill-region' is used on the selection, rather than
      `delete-region'.  (Text selected with the mouse will typically
@@ -160,7 +178,9 @@ With ARG, repeat that many times.  `C-u' means until end of buffer."
      the command which will insert replacement text.
  FUNCTION
      For commands which need to dynamically determine this behavior.
-     FUNCTION should take no argument and return one of the above values or nil."
+     FUNCTION should take no argument and return one of the above
+     values, or nil.  In the latter case, FUNCTION should itself
+     do with the active region whatever is appropriate."
   (condition-case data
       (cond ((eq type 'kill)            ;Deprecated, backward compatibility.
 	     (delete-active-region t)