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

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

> > > > 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?
> > >
> > > How did they understand this before?
> >
> > It was in the doc string of d-s-mode.  Each of the possible
> > property values was described.
> 
> In what version of Emacs?  I tried 24.3 and 24.1, and didn't see that
> there.  Maybe I'm blind or didn't look where you intended me to look.
> But then you never actually said that, did you?

My bad.  I thought this was in the d-s-mode doc string.
Sorry for making you look for it to no avail.  I should have
checked first.

Prior to the existence of `delete-selection-helper' (e.g.,
Emacs 23) this info was only in the Commentary.  In Emacs 24 and
later it is also in the doc string of `delete-selection-helper'.

That helper-function doc string is really not the right place
for it, IMO (though I am glad it was at least added to some
doc string).  Users will look to the command/mode doc string
more than to a helper-function doc string, for information
about how to use delete-selection mode.

(And as I said, the Commentary and the `delete-selection-helper'
doc string are now out of sync wrt `kill'.)

So let me be clear that I do not think the doc is adequate.
Specifically: it should tell you how to set the d-s-mode
behavior for a given command.  And in doing that, it should
list the possible values for symbol property `delete-selection'.

Where this information is provided to users is another question.
At a minimum, I think it belongs in the `delete-selection-mode'
doc string.  And I would like to see d-s mode documented better
in the Emacs manual.  Currently, this is all that we say about
it there (node `Using Region'):

  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
  mode on or off, type `M-x delete-selection-mode'.

The last sentence is a bit redundant, both wrt toggling and
on/off and wrt Delete Selection mode and `delete-selection-mode'.
It's good to say, but if you are really interested in saving words
then please consider more information and less verbiage here.

D-s mode is not only about replacing selected text by text
you type.  It also deletes selected text when you hit certain
deletion keys.  This info is missing.

But the main thing missing, IMO, is how to specify the behavior
for a given command, and what the possible behaviors are for a
given command.  This is particularly important for someone
writing a mode that binds keys to new commands that delete text.
The mode writer will need to teach the mode to be handled well
by d-s-mode, and for that s?he will need to know about symbol
property `delete-selection.

Whether most Emacs users need to know this or it could be
presented only in the Elisp manual is another question.  I think
that an end user will also want to know that s?he can override
the default d-s-mode behavior for any given commands, and that
the way to do that is to set property `delete-selection' on the
command symbol.  Pretty simple to do, but you need to know about
it to do it.

That d-s mode has never been adequately documented is not a
reason not to document it properly, IMO.  Yes, I and others
no doubt learned how to use it by reading the source code.
But that should not be the main or the only way that users
have to learn about it.

Just one opinion.