Subject: RE: bug#7702: 24.0.50; doc of select-active-regions, cut/paste/kill/yank

From: "Drew Adams" <[email-masked]>
Date: Sat, 25 Dec 2010 09:38:48 -0800

> > Doc string of `select-active-regions':
> >  
> > "If non-nil, an active region automatically becomes the window
> > selection."
> >  
> > Nowhere in Emacs is it defined or described what a "window 
> > selection" is.  This new terminology (and perhaps a new concept?)
> > needs to be explained to Emacs users.
> 
> I fixed that (on the emacs-23 branch) to say
>   "If non-nil, an active region automatically sets the 
>    primary selection."

That doesn't help for a system such as Windows that has no concept of primary
selection.  It leaves the user wondering: does this variable do nothing on
Windows?  Is the behavior on Windows always as if the variable is nil? non-nil?

We need to inform users what the behavior of this variable is, and not just for
X Window.  If this variable has no effect on Windows (for example), then, just
as we say that it has no effect unless Transient Mark mode is enable, so we need
to stipulate the behavior when there is no concept of primary selection.

> > (emacs) `Cut/Paste Other App':
> > This node has become _much_ more complicated, and much less clear.
> > It is not clear which of the things (all of them? any of them?)
> > discussed in this node are for an X window system only.  
> > This needs to be clarified.  Distinguish statements that are
> > true for Emacs across platforms from statements that are specific
> > to particular platforms - in particular but not only, X Window.
> 
> I found that I can take care of this by adding the following paragraph
> after the first 2 paragraphs:
> 
>   @cindex MS-Windows, and primary selection
>     MS-Windows provides no primary selection, but Emacs emulates it
>   within a single Emacs session: all the features and commands related
>   to the primary selection work as described for cutting and pasting
>   within the same session, but not across Emacs sessions or with other
>   applications.

OK, but what does "work as described" mean for something whose behavior is
described wrt the primary?  E.g. what does it mean for a var like
`select-active-regions'?

I think we should be more specific and say what Emacs on Windows does with the
emulated primary.  Does it use the kill-ring? the clipboard?  Just what does
"emulate the primary" mean?  It's a sincere question.  If I knew the answer then
I as a user would understand the doc and the new behavior much better, I think.

_You_ know just what you mean by this emulation, because you know the code.  But
"emulate" disguises as much as it reveals; it raises questions at least as much
as it answers questions.  What you mean by emulation here needs a little
description.

> If I read the whole subsection with this paragraph included, I see no
> need for further differentiation between X and MS-Windows.

That would be great.  If you can please clarify what the Windows behavior is
(e.g. what emulation is/does), then I think Bob will be our uncle.

> > For example, the description of `select-active-regions' makes it
> > sound like it has no effect on a system, such as MS Windows, that
> > has no concept of a primary selection.  If that is so, then say so.
> 
> It has the same effect on MS-Windows, with the caveat that the primary
> selection "works" only within the current session.

Then let's say that, including the last part.  You've added the last part in the
manual (above), so that's OK.  But the doc string should at least give some
indication that this var is not irrelevant on Windows.  And it could point to
the manual section for more info.

> > In general, this content needs cleanup, clarification, and 
> > probably some reorganization.  The node should cover _Emacs_,
> > not just Emacs on X Window.  It should say everything that users
> > need to know about cutting and pasting between applications and Emacs.
> 
> Please be more specific.  What else is needed, after adding the above
> paragraph about MS-Windows specifics?  My reading is that everything
> is now described correctly.

See my comment above, first.  If that gets addressed then once I see the result
I'll be glad to offer any other suggestions if I think they would be helpful.

Also, as I mentioned, the notion of "other app" needs to be clarified.  Does it
include Emacs (another session)?  You clarified the Windows behavior wrt other
sessions, but what about non-Windows?

And, as I mentioned, there is the problem of just what the relation is between
pasting and yanking - see what I wrote in the initial bug report.  Even just the
notion of "pasting" is not very clear.  When you use `mouse-2' are you pasting?
Or is "pasting" reserved for something that is pasted from the clipboard.  Etc.
- we need to be clearer about these terms.

As I mentioned, there is even a mismatch between the node name and the node
title: one refers to cut/paste and the other to kill/yank.  That doesn't help
users understand, and they need to understand these differences in Emacs.

> > And it (or some other node) should cover pasting between 
> > Emacs sessions, to the extent that this is not covered under
> > the category of "other app".  Does another Emacs session act
> > just like some other, non-Emacs app in all respects wrt
> > transferring text?  If not, what are the differences?  Does it
> > matter which Emacs versions the Emacs sessions manifest?
> > If so, explain.
> 
> AFAIK, there's nothing special about Emacs wrt cutting/pasting between
> different applications (with the exception of primary selections on
> MS-Windows, which is now covered).  If you know about anything else,
> please tell.

No, I don't know more than you about it, obviously.  But this bug was filed the
same day as #7699 (it was actually sent before, but the bug number is slightly
higher), and that report was about the fact that copying text in another app did
not paste it into Emacs.

It's not been super clear to me which changes have been intentional and which
are bugs.  You are better placed to say whether the doc is now complete and
correct wrt copying/cutting/pasting among apps on different platforms.  I
respect your understanding of it.  I've spoken up where I think there might
still be problems.

> > Also, the concepts of "pasting" and "yanking" need to be 
> > compared and contrasted.  Sometimes Emacs doc seems to treat
> > them as the same; sometimes as different.  This just confuses users, 
> > especially if there
> > is no section that covers the relation between the two explicitly.
> > Likewise, cutting and killing.
> >  
> > Finally, there is a disconnect between the name of node 
> `Cut and Paste'
> > and its title, "Killing and Yanking on Graphical Displays". 
>  This mess
> > was introduced in Emacs 22.
> 
> I fixed that: it now uses "cut and paste", not "kill and yank".

Excellent.  I think you got my general point, and look forward to the new
version.  If I then notice anything that I think is unclear I'll let you know.
If you're comfortable with having responded to my concerns, then please go ahead
and close this bug.  But please first think about what I said above, then
decide.