bug#11361: 24.1.50; doc string of `yank-pop-change-selection'

["Drew Adams" <drew.adams@oracle.com>]

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