bug#22296: 25.1.50; Document changes to `delete-selection-mode'

[Eli Zaretskii <eliz@gnu.org>]

> Date: Sun, 3 Jan 2016 08:24:35 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 22296@debbugs.gnu.org
> 
> > If you know about other changes (that are not bugfixes), please name
> > them.
> 
> Frankly, I do not understand all of the changes I see in the code
> since 24.3.  There are a boatload of them.  `diff' the Emacs 25
> version against the 24.3 version.

You don't get to complain about the v25 version until you see its NEWS
complete.  We aren't there yet.

But yes, I did look at all the changes in that file since 24.3
release, and all I saw was the one mentioned, and a couple of
bugfixes.  That is all.

> 1. It "can now be used without transient mark mode" is misleading.
> 
> You could always turn off t-m-mode (after turning d-s-mode on)
> and still use d-s-mode.  (But you might have been surprised to see
> stuff disappear because you didn't notice what was in the region.)
> 
> The changes for this seem to be: (1) d-s-mode does not automatically
> turn on t-m-mode now, and (2) d-s-mode does NOT have any effect unless
> you turn on t-m-mode temporarily.  IOW, d-s-mode works now only with
> temporary t-m-mode; it no longer works with a non-active region.
> (And yes, this is a good change.)

NEWS is not a manual, it only gives summary of the changes.  If you
think the 2 manuals don't describe enough of the current behavior,
feel free to submit bug reports about specific deficiencies.

> 2. d-s-mode now supports rectangular regions (?).

I don't know what you are talking about, please give an example that
didn't work earlier.  (AFAIK, it always supported rectangles in
conjunction with CUA mode, but maybe I'm mistaken.)

> 3. Command `delete-selection-repeat-replace-region' was added.
> It seems to be bound, so far, only in CUA mode (to `M-v').
> Not real clear to me what this is about/for.

Read the commentary to the changeset.  It was a bugfix related to CUA
features that used to work previously.

> 4. Apparently you can no longer specify `kill' as the d-s behavior:
> (put 'some-command 'delete-selection 'kill).  Well, it's still
> supported for now, but `kill' has been removed from the file-header
> Commentary, and the code comments say that it is deprecated.
> 
> Why is this?  Where is this deprecation documented?  Why
> shouldn't a user or a library still be able to override a
> `delete-selection' setting for a given command, to specify
> it as `kill'?  Not clear to me what this is about.
> 
> 5. There is an additional, undocumented (why?) possible value
> for `delete-selection', which you can apparently put on a
> command's symbol: `delete-selection-uses-region-p'.  Please
> consider documenting this (e.g., not just mentioning it in NEWS).
> 
> 6. The default delete-selection behavior for multiple commands
> has apparently changed.  For example, `open-line' now has the
> default behavior and not the `kill' behavior.  Likewise, unloading
> (`delsel-unload-function') deals with a different command list.

We never documented any of this, and I see no reason to do so now.