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

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

[Drew Adams]

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.
 
(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.
 
Variables and such that have no meaning or effect on some platforms
should be pointed out wrt this behavior.  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.
 
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.
 
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.
 
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.
 
Perhaps back then we were just attempting to be friendlier to newbies
(?), passing killing off as cutting, and yanking as pasting.  But the
job was done haphazardly (hence the title disconnect), and now the
result is confusion - especially since there now is a significant
difference in behavior between the two ways of removing and inserting
text.  Cleanup is needed.
 

In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2010-12-20 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.4) --no-opt --cflags
-Ic:/imagesupport/include'
 

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

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Tue, 21 Dec 2010 20:02:28 -0800
> Cc: 
> 
> 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."

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

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

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

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

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

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

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.

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

[Drew Adams]

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

What is missing, I think, is some description of what is meant by "primary
emulation".  I think we need to say explicitly that wherever the manual speaks
of the "primary selection" understand that Emacs on Windows uses an internal
cache (variable, call it what you like) that acts the same as the primary
selection in X Window, with the one exception about sessions.

That's all.  IOW be clear that on Windows you get the same behavior as on X,
even though Windows does not have a primary selection: Emacs in effect creates
and uses an (internal) primary selection (emulation).  Modulo the one exception
wrt sessions.

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

See above.  It's enough to make clear once and for all that Emacs emulates the X
Window primary selection internally; IOW, it has its own internal pseudo-primary
selection.

[Personally, as I said from the get-go, I think it would be clearer to just call
it the primary selection and have a single footnote/paragraph explaining that
since Windows actually has no primary selection Emacs emulates it internally.
And mention the session exception for Windows.

IOW, aside from such a (single) clarification/footnote, the doc could just speak
about primary selection and not mention Windows as being exceptional - not
mention emulation etc.  IOW2, put the proviso/explanation in a single place, and
otherwise just refer to this as the primary selection, making no distinction for
Windows.]

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

That works if you take my suggestion and just let Emacs doc speak about the
primary selection with no distinction/explanation about Windows except in a
single place in the manual.  But if you sprinkle mentions of primary emulation
here and there users will wonder here and there how much is being emulated,
whether this or that piece of doc also applies to Windows, etc.  But we can
agree to disagree about this.

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

From the moment we say that Emacs emulates the primary selection, users need
some mental mode of what we mean by that.  It's not about describing or even
faithfully reflecting the implementation.  It's about letting users know what
the behavior is on Windows.  See above.  It is enough to say (explicitly) that
in all respects Emacs on Windows behaves as if there were a primary selection
(the one exception being session behavior).

"Emulation" can mean many things.  There are degrees of emulation.  Apparently
our emulation of the primary is 100% faithful (modulo the sessions thing), so we
should say that.

IMHO, if that is the case then we should not even speak about emulation, except
in one place in the manual, essentially as a footnote to anyone wondering about
the behavior on Windows.  The rest of the doc can then just refer to the
primary, with no mention of Windows.

The reason I was asking "What about Windows?" here and there is that our
approach is instead to tell users here and there that we do "primary emulation",
without saying just what it means (user-visible behavior, not implementation).
It is far simpler, IMO, to state the emulation thing once and for all, in one
place, in the manual, and otherwise speak as if Emacs has a primary selection -
on all platforms.

IOW, speak about the _Emacs_ primary selection, which behaves the same as the X
Window primary selection (modulo the sessions thing on Windows).  That's much
easier for users, less wondering what is meant and what the behavior is.

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

You've misunderstood.  It's not about describing the implementation; it's always
about describing the user-visible behavior; it's always about a user point of
view.  The description needs only to say that Emacs _always_ behaves as if there
is a primary selection, on all platforms - see above.

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

See above.  As I see it, there are two possibilities:

1. Speak here and there about "primary selection emulation", without describing
the behavior, i.e., without saying how well it's emulated, how the emulated
behavior differs etc.

2. Speak everywhere only about the "primary selection" (or, better, the Emacs
primary selection).  And in only one place in the manual (only), mention that
although, technically, Windows has no primary selection, Emacs on Windows does
effectively have a primary selection:

Emacs emulates the X Window primary selection internally.  The Emacs primary
selection behaves everywhere exactly the same as an X Window primary selection.
One exception: the sessions thing.

You've chosen #1; I suggested #2.  With choice #1, users can everywhere (e.g.
each doc string) wonder just what is involved, how it behaves on Windows.

By now I think I've made myself clear.  What you choose to do with my feedback
is up to you.

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

OK by me if you want to wait.  Yes, it's a big job, but it was part of this bug
report - see the Subject and original report.  But I'm OK with your waiting.  I
won't bother to create another report, but you can if that's how you prefer to
handle this.

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

Good; thanks for that.

> The manual describes the correct behavior.  Bugs which violate that
> correctness should be fixed, they don't need to affect the manual.

100% agreement.  Bugs and workarounds are not for the manual or doc strings.

> What I say above is how Emacs _should_ work on Windows.  Any deviation
> from that behavior is potentially a bug that should be fixed.

Agreed.

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

Thanks again for tackling this.

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@debbugs.gnu.org>
> Date: Sat, 25 Dec 2010 10:50:24 -0800
> 
> > 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.
> 
> What is missing, I think, is some description of what is meant by "primary
> emulation".  I think we need to say explicitly that wherever the manual speaks
> of the "primary selection" understand that Emacs on Windows uses an internal
> cache (variable, call it what you like) that acts the same as the primary
> selection in X Window, with the one exception about sessions.

I modified the text slightly to mention the internal store.

> IOW, aside from such a (single) clarification/footnote, the doc could just speak
> about primary selection and not mention Windows as being exceptional - not
> mention emulation etc.  IOW2, put the proviso/explanation in a single place, and
> otherwise just refer to this as the primary selection, making no distinction for
> Windows.

That's exactly what I did.  I added a single paragraph about the
Windows specifics; the rest of the text talks about the primary
selection without mentioning X or Windows.

> But if you sprinkle mentions of primary emulation here and there
> users will wonder here and there how much is being emulated, whether
> this or that piece of doc also applies to Windows, etc.

There's no such sprinkling.

> But we can agree to disagree about this.

But we agree.

> 1. Speak here and there about "primary selection emulation", without describing
> the behavior, i.e., without saying how well it's emulated, how the emulated
> behavior differs etc.
> 
> 2. Speak everywhere only about the "primary selection" (or, better, the Emacs
> primary selection).  And in only one place in the manual (only), mention that
> although, technically, Windows has no primary selection, Emacs on Windows does
> effectively have a primary selection:
> 
> Emacs emulates the X Window primary selection internally.  The Emacs primary
> selection behaves everywhere exactly the same as an X Window primary selection.
> One exception: the sessions thing.
> 
> You've chosen #1; I suggested #2.  With choice #1, users can everywhere (e.g.
> each doc string) wonder just what is involved, how it behaves on Windows.

No, I've chosen #2.  If you understood differently, it's a
misunderstanding.

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

[Drew Adams]

 
> > But we can agree to disagree about this.
> But we agree.
> 
> > You've chosen #1; I suggested #2....
> No, I've chosen #2.  If you understood differently, it's a
> misunderstanding.

Great.  Thanks for working on this (doc & code).
I'm sure it is much cleaner & clearer now.