RE: use and doc of function symbol properties [was: bug#11381: 23.3; isearch-search-and-update issue?]

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

> > Even so, I think that `yank' and `kill' are pretty clear even
> > without reading their descriptions.
> 
> Not to me.  "For commands that do a yank" is not a description, it's
> tautology at best.  "Ensures that the region about to be deleted is
> not yanked"? why would it be yanked otherwise? and why the value is
> 'yank' if it "ensures the region will NOT be yanked"?  That just
> doesn't make any sense!

It does makes sense, I think, but perhaps only after you understand what it
does, not necessarily as a lesson. ;-)

Let me try to do a little better.

Whenever the value of property `delete-selection' for a command symbol is
non-nil, and you are in `delete-selection-mode', the text of the active region
is removed.  Always.  That is the first thing to understand.

This removal happens before - or instead of - the action normally performed by
the command.  That is the second thing to understand.

So in the above text, "the region about to be deleted" refers to the deletion of
the active region, which takes place before the yank command does its own thing
(yanks).

And "ensures the region will NOT be yanked" means that the property value `yank'
ensures that when the yank command does its yanking it does not just yank the
exact same text that was just deleted - the active region text - even if that
was the text that the kill ring offered.

That's an attempt to explain the existing commentary text.  Some more help
below.

> 'kill'? let's see... "`kill-region' is used on the selection, rather
> than `delete-region'".  So? why would that matter, and when would I
> want the former rather than the latter?

You would use `kill' when you want the active region text killed instead of
being simply deleted.  That's all that that is trying to say.

> And what is "Text selected with the mouse is typically
> yankable anyway" about?  why "anyway"?

No idea, sorry.

> > I'm not saying the existing descriptions should not be 
> > changed.  I'm asking you what changes you have in mind.
> 
> How can I explain what I don't understand?  I _really_ have no clear
> idea about what each value does, can you believe that?  If I'd study
> the code long enough, I'd eventually understand, but I didn't.

I see.  I thought you were saying before that you understood the code, and that
it is necessary to study the code in order to understand.  I misunderstood
probably from your saying this:

  the only place you can really understand what these properties
  mean is by looking at the code in delsel.el that handles them,
  because even the commentary in delsel.el leaves a lot of place
  for improvement.

I took that to mean that you "really understand" the code, and that the
commentary description does not live up to such an understanding.  My bad.

> > > What is needed is a clear description what each value does,
> > For instance?  What is missing, in your opinion?
> 
> I don't know.  How about if you try explaining each value in full,
> from scratch?  Assume that only primitives like kill-region,
> delete-region, 'yank', etc. are known, all the rest is not.  Explain
> the effect of each value, both on the text that was selected and on
> any other text that's involved.  Give at least one example for a use
> case where each value will be useful.  That kind of stuff.

See if this helps at all -

In all cases when `delete-selection-mode' is turned on and the
`delete-selection' value of a command symbol is non-nil, the text of
the active region is removed.  It is either deleted or killed (i.e.,
deleted and moved to the `kill-ring').  It is killed only if the value
of property `delete-selection' is `kill'.

The action of the invoked command itself is either carried out (after
deletion of the active region), which is the case for
`delete-selection' values `yank' and `t', or not (it is ignored),
which is the case for values `supersede' and `kill'.

`delete-selection' value `yank' ensures that the invoked yanking
command does not yank the same text as that in the region.  The
kill ring is rotated if necessary, so that the yank operation is not a
no-op.

Here is a summary of the `delete-selection' property values.  You can apply a
value to a command symbol to make the command delete the active region text and
perhaps do something more:

`kill'      - Use it if you want the command to kill the region text,
              so you can yank it later.

              The command's own operation does NOT take place - it is
              superseded by the region killing.

              Typically, the command itself is a kill command: its
              own killing is replaced by killing the active region.

`supersede' - Use it for a command that deletes text that you do not
              want to yank later.

              The command's own operation does NOT take place - it is
              superseded by the region deletion.

              Typically, the command is a deletion command: its own
              deletion is replaced by deleting the active region.

`t'         - Use it for a command that inserts text.

              The command's insertion operation takes place after
              deleting the active region.

`yank'      - Use it for a command that yanks text.

              The command's yank operation takes place after deleting
              the active region.

              If the kill-ring entry to be yanked has the same text as
              the region, then first rotate the kill ring so that the
              yank will not be a no-op.

`nil'       - Invoke the command normally.  Delete-selection mode does
              nothing for a command whose `delete-selection' property 
              value is nil.

That is a summary, but it also outlines the important use cases.  In fact, there
is nothing that requires you to use only a deletion command with `supersede' or
only an insertion command with `t', etc.

Example use cases:

* If the command action is to kill some text, then you might want it
  to kill the region instead, when it is active.  In this case, use 
  `kill' as the `delete-selection' value.

* If the command action is to delete some text without killing it, 
  then you might want it to delete the active region instead (without
  killing it).  In this case, use `supersede' as the
  `delete-selection' value.

* If the command action is to insert some text, you typically want 
  that text to replace the active region.  In this case, use `t' as
  the `delete-selection' value.

* If the command action is to yank some text, then use `yank' as
  the `delete-selection' value.

Concrete examples from Org mode:

 `org-self-insert-command' gets value `t' (i.e., replace)
 `org-delete-char' gets value `supersede' (i.e., just delete)
 `org-yank' gets `value yank' (i.e., replace, but prevent a no-op)

FWIW, Org mode does EXACTLY the same thing for handling `flyspell-mode': It puts
property `flyspell-delayed' on commands `org-self-insert-command' and
`org-delete-char'.  And it does EXACTLY the same thing for handling
`pabbrev-mode': It puts property `pabbrev-expand-after-command' on command
`org-self-insert-command'.

The attachment of properties to function symbols in order to affect behavior in
some mode is not a new idiom.  And it is not limited to Emacs Lisp.



In any case, this is all apparently moot, since Stefan appears to want to do
away with this (simple & elegant) mechanism and instead do something like what
was done recently for shift-select or even his completion tables.
http://debbugs.gnu.org/cgi/bugreport.cgi?bug=11381#62

If you had trouble understanding the delsel approach and code, well, then ...
bonjour les degats when it is replaced by a concoction a la completion tables.
;-)  And good luck with the relevant doc strings and Commentary.

HTH.