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

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

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

Yes, of course.

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

Of course; agreed.  It is for notifying users of behavior changes.

> If you think the 2 manuals don't describe enough of the current
> behavior, feel free to submit bug reports about specific deficiencies.

I think I've done that here.  If you don't want to consider it, fine.

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

Dunno.  I'm just looking at the code, which seems to have changed
quite a bit in this regard.  If you think nothing has changed
wrt behavior, then feel free to ignore this heads-up.

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

OK.

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

Really?  The fact that you (apparently) can no longer specify that
a given command is handled by killing the region?  The fact that
there is a new possible value for the property (what is it for)?

How is a user supposed to understand how to use d-s-mode if these
things are not documented - either in a doc string or in a manual?

And we no longer announce deprecations?  Except in code comments?

Anyway, I've reported the problems I see.  Do with the information
what you will.