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

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

[Drew Adams]

> > 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.
> 
> I added a link in the doc string of delete-selection-mode to
> delete-selection-helper and delete-selection-pre-hook.

OK.  I still don't think that the helper function is the right,
or the better, place to mention the possible property values.
But this will help.  Thx.

> > 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.
> 
> I added that.

Thx.

> I added to the ELisp manual text that briefly mentions how Delete
> Selection mode affects commands, and refers to the doc strings of
> delete-selection-pre-hook and delete-selection-helper.
> 
> I think this makes the documentation of this quite adequate, so I'm
> marking this bug done.

Sounds good. Thx.

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

[Drew Adams]

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

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

[Eli Zaretskii]

> Date: Sun, 3 Jan 2016 11:54:12 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 22296@debbugs.gnu.org
> 
> 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.

I added a link in the doc string of delete-selection-mode to
delete-selection-helper and delete-selection-pre-hook.

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

I added that.

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

I added to the ELisp manual text that briefly mentions how Delete
Selection mode affects commands, and refers to the doc strings of
delete-selection-pre-hook and delete-selection-helper.

I think this makes the documentation of this quite adequate, so I'm
marking this bug done.

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

[Drew Adams]

> > 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?
> 
> How did they understand this before?

It was in the doc string of d-s-mode.  Each of the possible
property values was described.

> This bug report says "please document changes to
> delete-selection-mode".  I have shown that what was documented before
> was updated.

No.  Previously the doc string documented the possible values
for the property.  The new value is missing.

(And the deprecated value was removed from the doc string
of the mode command but not from the doc string of *-helper.)

> You now say that its previous documentation was
> insufficient, which is an entirely different issue.

If you really think so, feel free to copy the info from this
report to another bug report.  Or just go ahead and ignore it.
Your choice.  I've reported it.

> > And we no longer announce deprecations?  Except in code comments?
> 
> Most of the deprecations are indeed never announced in NEWS, you see
> them when the byte compiler emits a warning to that effect.

Not a great policy, IMO.  But whatever.  So does the byte-compiler
warn you about this deprecation?  I don't think so.

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

I see.

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

[Eli Zaretskii]

> Date: Sun, 3 Jan 2016 10:52:23 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 22296-done@debbugs.gnu.org
> 
> > > 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?
> > 
> > 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?

> > This bug report says "please document changes to
> > delete-selection-mode".  I have shown that what was documented before
> > was updated.
> 
> No.  Previously the doc string documented the possible values
> for the property.  The new value is missing.
> 
> (And the deprecated value was removed from the doc string
> of the mode command but not from the doc string of *-helper.)

Please tell explicitly what function/variables you are alluding to
here, where this documentation existed and was removed.  Also, I don't
know what *-helper refers to.

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

[Drew Adams]

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

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

[Eli Zaretskii]

> Date: Sun, 3 Jan 2016 10:00:46 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 22296@debbugs.gnu.org
> 
> > > 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?

How did they understand this before?

This bug report says "please document changes to
delete-selection-mode".  I have shown that what was documented before
was updated.  You now say that its previous documentation was
insufficient, which is an entirely different issue.

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

Most of the deprecations are indeed never announced in NEWS, you see
them when the byte compiler emits a warning to that effect.

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

I did.

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

[Drew Adams]

> I looked at delsel.el, and the only user-visible change in behavior
> since v24.3 is the one that was already announced in NEWS.24:
> 
>   ** Delete Selection mode can now be used without Transient Mark mode.

Somehow I didn't notice that mention.

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

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

2. d-s-mode now supports rectangular regions (?).  Not clear
to me what this is about, from a quick glance at the code.
Maybe you will characterize this as a bug fix, but the behavior
seems to be changed, in any case.

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.

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.

Those are a start - things I see that I wonder about.  You may
others, or you may understand these things better or differently.

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

[Eli Zaretskii]

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

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

[Drew Adams]

`delete-selection-mode' changed behavior in some ways since Emacs 24.3,
but I find nothing about any of the changes mentioned in any NEWS since
then.  Please update the different NEWS versions to reflet the changes.


In GNU Emacs 25.1.50.1 (i686-pc-mingw32)
 of 2015-12-10
Bzr revision: 6148555ee5a3d0139ae517803718b3e0357933c7
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/snapshot/trunk --enable-checking=yes
 --enable-check-lisp-object-type --without-compress-install 'CFLAGS=-Og
 -ggdb3' LDFLAGS=-Lc:/Devel/emacs/lib 'CPPFLAGS=-DGC_MCHECK=1
 -Ic:/Devel/emacs/include''

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

[Eli Zaretskii]

> Date: Sat, 2 Jan 2016 20:12:57 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> 
> `delete-selection-mode' changed behavior in some ways since Emacs 24.3,
> but I find nothing about any of the changes mentioned in any NEWS since
> then.  Please update the different NEWS versions to reflet the changes.

I looked at delsel.el, and the only user-visible change in behavior
since v24.3 is the one that was already announced in NEWS.24:

  ** Delete Selection mode can now be used without Transient Mark mode.

If you know about other changes (that are not bugfixes), please name
them.