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

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <7702-done@debbugs.gnu.org>
> Date: Sat, 25 Dec 2010 09:38:48 -0800
> 
> >   "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.

The manual now explains what that means on Windows (that's the change
I described below).  There's also an index entry wrt primary selection
on MS-Windows.  I don't think we can or should explain all that in a
doc string of an option.

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

This variable has the same meaning and effect on Windows as on X, and
its default value is the same.  So I see nothing that should be said
about that.  The only difference -- that on Windows the primary
selection exists only within a single Emacs session -- is now in the
manual.

> >   @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?

"As described" in this subsection, and elsewhere in the manual.  If
that's not clear, we could say that explicitly.

> E.g. what does it mean for a var like `select-active-regions'?

Just what the documentation of that variable says: an active region is
placed into the primary selection, and can be pasted from there by any
command that retrieves text from the primary selection.

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

Neither.  It's an entirely separate store.  Why is this important?
The manual doesn't explain how the primary selection works on X, and
most users will probably never know.  So why should we go into these
implementation details for Windows?  If the emulation were using one
of the existing facilities, like the kill-ring, then we would need to
tell that, because the effect would be visible to the user.  But since
it doesn't, and the place where the selection is stored is entirely
concealed from the user, I see no reason for any further details.

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

Given that I modified it to not refer to X, why would a user think
that it is irrelevant?  It's unreasonable to ask that we repeat in
each doc string related to selections that these features also work on
Windows.

> Also, as I mentioned, the notion of "other app" needs to be
> clarified.  Does it include Emacs (another session)?

I said (below) that it does, and the exception wrt primary selection
was already mentioned in the text before the paragraph about "other
app".

> You clarified the Windows behavior wrt other sessions, but what
> about non-Windows?

The exception wrt to other session is clearly Windows-specific.  The
text says this explicitly.

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

That's a different job, and a much larger one.  I would suggest a
separate bug report, or maybe wait until Emacs 24 is near its pretest.
That's because Emacs 23, in whose manual I made the change, makes no
distinction between these two, and in fact mixes them freely (e.g.,
mouse-2 does the equivalent of C-y), so explaining the difference is
hopelessly complicated, perhaps even impossible in Emacs 23.

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

Not anymore.

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

The manual describes the correct behavior.  Bugs which violate that
correctness should be fixed, they don't need to affect the manual.
What I say above is how Emacs _should_ work on Windows.  Any deviation
from that behavior is potentially a bug that should be fixed.

> [I] look forward to the new version.  If I then notice anything that
> I think is unclear I'll let you know.

Thanks.

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

Will do.