bug#7196: 24.0.50; NEWS item "Selection changes"

[Eli Zaretskii <eliz@gnu.org>]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <7196@debbugs.gnu.org>
> Date: Fri, 15 Oct 2010 08:49:06 -0700
> 
> > > The NEWS item is woefully incomplete.  It doesn't explain much of
> > > anything about the selection changes for Emacs 24 - and they are
> > > radical changes.
> > >  
> > > Among other things, NEWS should detail the differences from the
> > > previous behavior, and explain clearly how to return to the
> > > previous behavior (exactly, completely).
> > 
> > The new text is reproduced below.  If it is good enough, this bug
> > report can be closed.
> 
> Thanks for taking a stab at it. Some suggestions and questions below.
> 
> For info, are the following statements correct?

Most of the time, but not always, depending on customizations.

Why is that important?

> #1 needs to also say something about the other systems, which do not support a
> separate primary: e.g. do they put the selection on the clipboard? the kill
> ring? Where do they put it?

They do nothing and don't put the text anywhere outside Emacs.

> >   Only commands that kill text or copy it to the
> >   kill-ring (C-w, M-w, C-k, etc.) put the killed text into the
> >   clipboard.  Selected text is put into the primary selection (on
> >   systems, such as X, that support the primary selection 
> >   separately from the clipboard).
> 
> Is it (a) "put into the primary selection" or (b) "becomes the primary
> selection"?

We use "put text into primary" and "set the primary with the text"
interchangeably.

> I.e., does it replace the existing primary or is it added
> (prepended/appended) to it?  I'm guessing (b), and that this is different from
> the kill ring.

It replaces the old content.

> I don't know about the clipboard - is it a list or ring, like the
> kill ring?

It's a single buffer.

> Anyway, if in some cases we replace what was in some location
> and in other cases we add to it, those cases need to be distinguished. "Put
> into" implies a container of a collection.

I believe every user nowadays knows what happens with text that is put
into the clipboard or the primary selection.  Anyway, NEWS entries are
not for explaining these issues.

> What happens to selected text on systems that do _not_ support a primary
> selection separate from the clipboard?

Nothing.  They stay Emacs selections.

> Please add that info - don't just say what happens for X.

There's nothing to tell.  This functionality does not exist on non-X
systems, so whatever happens on X does not happen elsewhere.

> >   Similarly, Emacs by default does not retrieve text from the 
> >   clipboard when the mouse (e.g., mouse-2) is used for pasting text
> >   selected in another application.  
> 
> Say here where it _is_ retrieved from for the mouse, before going on to talk
> about retrieval from the clipboard.

I transposed the two sentences, although I don't think a distance of
one sentence obfuscates the meaning enough to be confusing.

> Why "in another application"?  If not also true for text selected in Emacs, then
> state also what the case for that text is.

I set out to describe changes wrt exchange of text between Emacs and
other applications.  This is what this NEWS entry is about; it is not
about selected text in Emacs in general.

> >   Mouse commands that paste text retrieve text from the primary 
> >   selection, on systems that support it separately from the clipboard.
> 
> And retrieved from where on other systems?

Not retrieved at all.

> >   In other words, the default behavior is that mouse gestures that
> 
> Mouse actions - mouse gestures are typically thought of as something different.

"Mouse gestures" is frequently used terminology.

> >   while keyboard commands that kill/copy and paste text work with the
> clipboard.
> 
> I wouldn't say "copy", since there are different kinds of copy.

The "text" part in "kill/copy text" should disambiguate that.

> >   This change also means that the "Copy", "Cut", and "Paste" items of
> >   the menu-bar "Edit" menu are now exactly equivalent to, respectively
> >   M-w, C-w, and C-y.
> 
> I didn't realize that BTW.  That means that on Windows they are _not_ equivalent
> to the Windows menus of the same names.

Why not?  I think they are.

> >   To get back the previous behavior, whereby mouse gestures
> 
> Just mouse _selection_, no?  Not also mouse-2 (paste).

The part after "whereby" describes what behavior I had in mind.

> Be clear - to get back the previous behavior, _set them to_ t (or whatever the
> value is).  Don't just say customize them; say what to customize them to.

I added non-nil.

> >   If you don't want Emacs to put the text into the clipboard, only to
> >   the primary selection, additionally customize
> >   `x-select-enable-clipboard' to nil.
> 
> I'm lost now.

Not clear why.

> It's not clear, to start out with, what "the previous behavior" was.

The "whereby..." part says what it was.

> You made
> it clear that now selecting with the mouse sets the primary but not also the
> clipboard or the kill ring.  What's not clear is what the previous behavior was
> (all its aspects) and therefore what each of the options is for - which part(s)
> of the previous behavior each restores.

Detailed description of the previous behavior is outside the scope of
NEWS entries.  Especially since the previous behavior was confusingly
inconsistent on X.

> >   These changes in the default behavior are reflected in the default
> >   values of several variables:
> 
> Maybe it would help to start with that.

We will risk losing the reader before she gets to the important parts.

> >   It also accepts a new value, `only', which means to only set the
> >   primary selection for temporarily active regions (usually made by
> >   mouse-dragging or shift-selection).
> 
> BTW, why `only' and not `temporarily' or `immediate' or `on-the-fly' or some
> such?

I don't know why, I just documented it.

> >   *** `mouse-2' is now bound to `mouse-yank-primary'.
> >   Previously, it was bound to `mouse-yank-at-click' (which is now
> >   unbound by default.
>                       ^
>                       )
> 
> What's the difference in _behavior_? Why make readers look up each of those
> commands in order to understand what's changed?

Because that's what we do in general in NEWS: give the reader enough
info to go and find the details by using documentation commands.
Anything else would bloat NEWS to unreasonable proportions.

> >   *** `x-select-enable-primary' now defaults to nil.
> >   This variable exists only on X; its default value was t in previous
> >   versions.
> 
> What does it do?

The doc string tells the whole story.

> >   *** Support for X cut buffers has been removed.
> 
> What's the consequence for user-visible behavior?

I don't know.  And neither do others, I think -- this functionality is
long obsolete and unused.

I fixed the typos you pointed out, thanks.