bug#55692: 29.0.50; delete-selection-mode: Replace region only if set using the mouse

[Drew Adams <drew.adams@oracle.com>]

This has long been the text in the manual: 

>        By default, text insertion occurs normally even if the mark is
>     active—for example, typing ‘a’ inserts the character ‘a’, then
>     deactivates the mark.  Delete Selection mode, a minor mode,
>     modifies
>     this behavior: if you enable that mode, then inserting text while
>     the mark is active causes the text in the region to be deleted first.

But this, or similar, is apparently being added now:

>     However, you can tune this behavior by customizing the
>     ‘delete-selection-temporary-region’ option.  Its default value is
>     ‘nil’, but you can set it to ‘t’, in which case only temporarily-active
>     regions
>     will be replaced: those which are set by dragging the mouse (*note
>     Setting Mark) or by shift-selection (*note Shift Selection), as
>     well as by ‘C-u C-x C-x’ when Transient Mark Mode is disabled.  You can
>     further tune the behavior by setting ‘delete-selection-temporary-
>     region’
>     to ‘selection’: then temporary regions by ‘C-u C-x C-x’ won’t be
>     replaced, only the ones activated by dragging the mouse or
>     shift-selection.  To toggle Delete Selection mode on or off, type
>     ‘M-x delete-selection-mode’.

FWIW, I disagree with this doc change.

If you're going to do something like that (let
alone say _more_ about this minor new feature than
about `delete-selection-mode' itself), then at
least tell users about the _real_ way to customize
d-s-mode - the part that's _basic_ to its design
and purpose.

I'm talking about the fact that d-s-mode does _not_
just replace selected text - even by _default_ for
some commands.

The design of d-s-mode - its features that are
useful for both end users and Lisp coders - isn't
even hinted at in the doc.

What is that design?  The mode behaves differently
for different commands.  Both by default and by
easy-peasy customization.

The doc says nothing about this, and yet it's so
simple, general, elegant, and powerful.  Just put
the kind of action you want on a command symbol
as property `delete-selection'.  There are basic,
predefined actions, and you can define any other
action you like.

From the delsel.el Commentary - which is the real
doc, IMO:

;; Commands which will delete the selection need a 'delete-selection
;; property on their symbols; commands which insert text but don't
;; have this property won't delete the selection.  It can be one of
;; the values:
;;
;;  `yank'
;;      For commands which do a yank; ensures the region about to be
;;      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.  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
;;      For commands which need to dynamically determine this behavior.
;;      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."

Note the first sentence, BTW.  You don't get _any_
`delete-selection-mode' behavior at all for a
command unless it has property `delete-selection'.

Yes, most insertion of regular text falls into the
default case.  And yes, that's the main idea behind
the mode.  But that's not a reason for the manual
to speak _only_ of that behavior.  d-s-mode doesn't
have as its aim only to replicate behavior that you
might be used to outside Emacs.

If you're going to start mentioning non-replacement
behavior, please prioritize the basic design of
d-s-mode, not the changes proposed in this thread.

Mention the latter if you like, but please don't
overwhelm the description of d-s-mode itself, and
(especially) please prioritize its essential means
of customization - the basic design.

Emphasize what's important.  The proposed new
feature isn't what's important about being able to
"tune this behavior".  Not IMO.