GNU bug report logs - #11361
24.1.50; doc string of `yank-pop-change-selection'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 11361 in the body.
You can then email your comments to 11361 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: 24.1.50; doc string of `yank-pop-change-selection'
Date: Fri, 27 Apr 2012 07:18:24 -0700

This is the entire doc string:
 
"If non-nil, rotating the kill ring changes the window system
selection."
 
That is worthless, to use a polite word.  What on earth does "changes
the window system selection"?  What is "the window system selection"?
How is it changed by setting this to non-nil?  What do nil and non-nil
actually do?  What does rotating the kill ring do to "the window system
selection" in each case?
 
Emacs users deserve better.  See the Emacs manual, node Clipboard (presumably)
for inspiration.

In GNU Emacs 24.1.50.1 (i386-mingw-nt5.1.2600)
 of 2012-04-23 on MARVIN
Bzr revision: 108006
agustin.martin <at> hispalinux.es-20120423103325-xmra3329elgzhmpc
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.6) --no-opt --enable-checking --cflags
 -ID:/devel/emacs/libs/libXpm-3.5.8/include
 -ID:/devel/emacs/libs/libXpm-3.5.8/src
 -ID:/devel/emacs/libs/libpng-dev_1.4.3-1/include
 -ID:/devel/emacs/libs/zlib-dev_1.2.5-2/include
 -ID:/devel/emacs/libs/giflib-4.1.4-1/include
 -ID:/devel/emacs/libs/jpeg-6b-4/include
 -ID:/devel/emacs/libs/tiff-3.8.2-1/include
 -ID:/devel/emacs/libs/gnutls-3.0.9/include
 -ID:/devel/emacs/libs/libiconv-1.13.1-1-dev/include
 -ID:/devel/emacs/libs/libxml2-2.7.8/include/libxml2'
 

Message #8 received at 11361 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 11361 <at> debbugs.gnu.org
Subject: Re: bug#11361: 24.1.50; doc string of `yank-pop-change-selection'
Date: Fri, 27 Apr 2012 17:58:29 +0300

> From: "Drew Adams" <drew.adams <at> oracle.com>
> Date: Fri, 27 Apr 2012 07:18:24 -0700
> 
> This is the entire doc string:
>  
> "If non-nil, rotating the kill ring changes the window system
> selection."
>
> That is worthless, to use a polite word.

I don't know why you decided to go after this doc string.  It is quite
clear.

> What on earth does "changes the window system selection"?

Would "sets the window system's primary selection" be clearer?

> What is "the window system selection"?

"Selection" is widely accepted terminology.  From the Emacs Glossary:

  Primary Selection
       The primary selection is one particular X selection (q.v.); it is
       the selection that most X applications use for transferring text
       to and from other applications.

       The Emacs kill commands set the primary selection and the yank
       command uses the primary selection when appropriate.  *Note
       Killing::.

> How is it changed by setting this to non-nil?  What do nil and non-nil
> actually do?

The nil value doesn't do anything, obviously.

Message #11 received at 11361 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Eli Zaretskii'" <eliz <at> gnu.org>
Cc: 11361 <at> debbugs.gnu.org
Subject: RE: bug#11361: 24.1.50; doc string of `yank-pop-change-selection'
Date: Fri, 27 Apr 2012 08:34:36 -0700

> I don't know why you decided to go after this doc string.  It is quite
> clear.

The manual is clear.  The doc string is worthless.

> > What on earth does "changes the window system selection"?
> 
> Would "sets the window system's primary selection" be clearer?

No.

> > What is "the window system selection"?
> 
> "Selection" is widely accepted terminology.  From the Emacs Glossary:

None of that helps.  And none of it mentions "window system selection".  And
none of it says anything close to what the Emacs manual says about this option.

> > How is it changed by setting this to non-nil?  What do nil 
> > and non-nil actually do?
> 
> The nil value doesn't do anything, obviously.

There must be a difference in behavior between nil and non-nil (or else it is
not only the doc string that is problematic).  That's the point.

Instead of playing word games, try clarifying what this option does.  What does
it mean to "change" the "window system selection"?  Change it how?  Change it to
what?  From what?

As I said:
> See the Emacs manual, node Clipboard (presumably) for inspiration.

There you will see that this option is apparently about _rotating_ the _kill
ring_ (perhaps among other things?):

 "if you change `yank-pop-change-selection' to `t', then `M-y'
  saves the new yank to the clipboard."

That at least is clear.  Whether that is all that the option does, I do not
know.  If so, then its doc string should speak in terms of rotating the kill
ring.  If it is more complicated than that, then additional explanation is
needed.

Message #14 received at 11361 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 11361 <at> debbugs.gnu.org
Subject: Re: bug#11361: 24.1.50; doc string of `yank-pop-change-selection'
Date: Fri, 27 Apr 2012 18:46:03 +0300

> From: "Drew Adams" <drew.adams <at> oracle.com>
> Cc: <11361 <at> debbugs.gnu.org>
> Date: Fri, 27 Apr 2012 08:34:36 -0700
> 
> > > How is it changed by setting this to non-nil?  What do nil 
> > > and non-nil actually do?
> > 
> > The nil value doesn't do anything, obviously.
> 
> There must be a difference in behavior between nil and non-nil (or else it is
> not only the doc string that is problematic).  That's the point.

A non-nil value changes the default behavior in the way that is
documented.  A nil value does not make that change, that's all.  I see
no need to say obvious things like that; I wonder why you do.

> Instead of playing word games, try clarifying what this option does.  What does
> it mean to "change" the "window system selection"?  Change it how?  Change it to
> what?  From what?

I suggested to use "set" instead of "change", for that very reason.

> As I said:
> > See the Emacs manual, node Clipboard (presumably) for inspiration.

There's more than one way to cut a cake.  The issue here is why this
particular way is "useless".  I think it needs small improvements,
like I suggested, but that's all.

>  "if you change `yank-pop-change-selection' to `t', then `M-y'
>   saves the new yank to the clipboard."
> 
> That at least is clear.

Is it?  What is a "yank"? what is a "clipboard"?  And why an option is
called yank-pop-change-SELECTION when it affects the clipboard?  Etc.,
etc., ad nauseam.

Message #17 received at 11361 <at> debbugs.gnu.org (full text, mbox):

From: Chong Yidong <cyd <at> gnu.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 11361 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#11361: 24.1.50; doc string of `yank-pop-change-selection'
Date: Sat, 07 Jul 2012 17:35:41 +0800

Eli Zaretskii <eliz <at> gnu.org> writes:

>>  "if you change `yank-pop-change-selection' to `t', then `M-y' saves
>>  the new yank to the clipboard."
>> 
>> That at least is clear.
>
> Is it?  What is a "yank"? what is a "clipboard"?  And why an option is
> called yank-pop-change-SELECTION when it affects the clipboard?  Etc.,
> etc., ad nauseam.

Pretty much.

I added a reference to `interprogram-cut-function' to the docstring,
which should clarify somewhat.  Closing the bug.

Message #22 received at 11361 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Chong Yidong'" <cyd <at> gnu.org>, "'Eli Zaretskii'" <eliz <at> gnu.org>
Cc: 11361 <at> debbugs.gnu.org
Subject: RE: bug#11361: 24.1.50; doc string of `yank-pop-change-selection'
Date: Sat, 7 Jul 2012 08:35:31 -0700

> I added a reference to `interprogram-cut-function' to the docstring,
> which should clarify somewhat.  Closing the bug.

How does referencing `interprogram-cut-function' answer the questions?

"What do nil and non-nil actually _do_?  What does rotating the
 kill ring _do_ to "the window system selection" in each case?"

etc.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.