More documentation of Emacs 24 X selection changes.

* doc/emacs/frames.texi (Mouse Commands): Document mouse-yank-primary.

* doc/emacs/killing.texi (Primary Selection): Document `only' setting for
select-active-regions.

* doc/emacs/mark.texi (Setting Mark): Reference Shift Selection node.

* doc/lispref/frames.texi (Window System Selections): Discussion of
x-select-enable-clipboard moved to Emacs manual.

7 files changed, 80 insertions, 53 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index 8a275b9e359..e72edf77acc 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,12 @@
+2011-07-11  Chong Yidong  <cyd@stupidchicken.com>
+
+        * killing.texi (Primary Selection): Document `only' setting for
+        select-active-regions.
+
+        * mark.texi (Setting Mark): Reference Shift Selection node.
+
+        * frames.texi (Mouse Commands): Document mouse-yank-primary.
+
 2011-07-11  Lars Magne Ingebrigtsen  <larsi@gnus.org>
 
         * mark.texi (Setting Mark): Clarify what's meant by "Shifted
diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi
index 0fc4dfa427d..5f708895d07 100644
--- a/doc/emacs/frames.texi
+++ b/doc/emacs/frames.texi
@@ -119,16 +119,21 @@ entirely on the screen.  The number of lines scrolled per step depends
 on how far away from the window edge the mouse has gone; the variable
 @code{mouse-scroll-min-lines} specifies a minimum step size.
 
+@findex mouse-yank-primary
 @findex mouse-yank-at-click
-@vindex mouse-yank-at-point
   Clicking with the middle mouse button, @kbd{Mouse-2}, moves point to
-the position where you clicked and performs a yank
-(@code{mouse-yank-at-click}).  @xref{Yanking}.  If you change the
-variable @code{mouse-yank-at-point} to a non-@code{nil} value,
-@kbd{Mouse-2} does not move point.  Then it does not matter where you
-click, or even which of the frame's windows you click on; the yank
-occurs at the existing point.  This variable also affects yanking the
-primary and secondary selections (@pxref{Primary Selection}).
+the position where you clicked and inserts the contents of the primary
+selection (@code{mouse-yank-primary}).  @xref{Primary Selection}.
+This behavior is consistent with other X applications; alternatively,
+you can rebind @kbd{Mouse-2} to @code{mouse-yank-at-click}, which
+performs a yank at point.
+
+@vindex mouse-yank-at-point
+  If you change the variable @code{mouse-yank-at-point} to a
+non-@code{nil} value, @kbd{Mouse-2} does not move point; it inserts
+the text at point, regardless of where you clicked or even which of
+the frame's windows you clicked on.  This variable affects both
+@code{mouse-yank-primary} and @code{mouse-yank-at-click}.
 
 @findex mouse-save-then-kill
   Clicking with the right mouse button, @kbd{Mouse-3}, runs the
diff --git a/doc/emacs/killing.texi b/doc/emacs/killing.texi
index 6be40c85832..06839ce5187 100644
--- a/doc/emacs/killing.texi
+++ b/doc/emacs/killing.texi
@@ -520,17 +520,19 @@ contents are more ``fragile''; they are overwritten by any mouse
 selection, whereas the clipboard is only overwritten by explicit
 ``cut'' or ``copy'' commands.
 
-  Under X, whenever you select some text in Emacs by dragging or
-clicking the mouse (@pxref{Mouse Commands}), it is also saved to the
-primary selection.
+  Under X, whenever you set an active region (@pxref{Mark}), Emacs
+saves the text in the active region to the primary selection.  This
+applies to active regions made by dragging or clicking the mouse
+(@pxref{Mouse Commands}), and those made by keyboard commands (e.g. by
+typing @kbd{C-@key{SPC}} and moving point; see @ref{Setting Mark}).
 
 @vindex select-active-regions
-  If you set the region using the keyboard---for instance, by typing
-@kbd{C-@key{SPC}} and moving point away from the mark---the text in
-the region is also saved to the primary selection.  (The updating of
-the primary selection is done at the end of each command, as long as
-the region is active and non-empty.)  To disable this behavior, change
-the variable @code{select-active-regions} to @code{nil}.
+  If you change the variable @code{select-active-regions} to
+@code{only}, Emacs saves only temporarily active regions to the
+primary selection, i.e. those made with the mouse or with shift
+selection (@pxref{Shift Selection}).  If you change
+@code{select-active-regions} to @code{nil}, Emacs avoids saving active
+regions to the primary selection entirely.
 
   To insert the primary selection into an Emacs buffer, click
 @kbd{mouse-2} (@code{mouse-yank-primary}) where you want to insert it.
diff --git a/doc/emacs/mark.texi b/doc/emacs/mark.texi
index 6d3ed351e43..20cc127d272 100644
--- a/doc/emacs/mark.texi
+++ b/doc/emacs/mark.texi
@@ -68,11 +68,11 @@ Set point and the mark around the text you drag across.
 @item Mouse-3
 Set the mark at point, then move point to where you click
 (@code{mouse-save-then-kill}).
+@item @samp{Shifted cursor motion keys}
+Set the mark at point if the mark is inactive, then move point.
+@xref{Shift Selection}.
 @end table
 
-Also, the shifted motion keys (for example, @key{S-Right}) will set
-the mark at point if the mark is inactive, then move point.
-
 @kindex C-SPC
 @kindex C-@@
 @findex set-mark-command
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index f9ab82e7966..fdf5a7753ba 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,8 @@
+2011-07-11  Chong Yidong  <cyd@stupidchicken.com>
+
+        * frames.texi (Window System Selections): Discussion of
+        x-select-enable-clipboard moved to Emacs manual.
+
 2011-07-11  Deniz Dogan  <deniz@dogan.se>
 
         * commands.texi (Prefix Command Arguments): Remove excessive
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 7dc6934c7d9..9a30ba5fdb4 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -1959,30 +1959,34 @@ defined in the file @file{lisp/term/x-win.el}.  Use @kbd{M-x apropos
 @node Window System Selections
 @section Window System Selections
 @cindex selection (for window systems)
-
-The X server records a set of @dfn{selections} which permit transfer of
-data between application programs.  The various selections are
-distinguished by @dfn{selection types}, represented in Emacs by
-symbols.  X clients including Emacs can read or set the selection for
-any given type.
+@cindex clipboard
+@cindex primary selection
+@cindex secondary selection
+
+  In the X window system, data can be transferred between different
+applications by means of @dfn{selections}.  X defines an arbitrary
+number of @dfn{selection types}, each of which can store its own data;
+however, only three are commonly used: the @dfn{clipboard},
+@dfn{primary selection}, and @dfn{secondary selection}.  @xref{Cut and
+Paste,, Cut and Paste, emacs, The GNU Emacs Manual}, for Emacs
+commands that make use of these selections.  This section documents
+the low-level functions for reading and setting X selections.
 
 @deffn Command x-set-selection type data
-This function sets a ``selection'' in the X server.  It takes two
-arguments: a selection type @var{type}, and the value to assign to it,
-@var{data}.  If @var{data} is @code{nil}, it means to clear out the
-selection.  Otherwise, @var{data} may be a string, a symbol, an integer
-(or a cons of two integers or list of two integers), an overlay, or a
-cons of two markers pointing to the same buffer.  An overlay or a pair
-of markers stands for text in the overlay or between the markers.
-
-The argument @var{data} may also be a vector of valid non-vector
-selection values.
-
-Each possible @var{type} has its own selection value, which changes
-independently.  The usual values of @var{type} are @code{PRIMARY},
-@code{SECONDARY} and @code{CLIPBOARD}; these are symbols with upper-case
-names, in accord with X Window System conventions.  If @var{type} is
-@code{nil}, that stands for @code{PRIMARY}.
+This function sets an X selection.  It takes two arguments: a
+selection type @var{type}, and the value to assign to it, @var{data}.
+
+@var{type} should be a symbol; it is usually one of @code{PRIMARY},
+@code{SECONDARY} or @code{CLIPBOARD}.  These are symbols with
+upper-case names, in accord with X Window System conventions.  If
+@var{type} is @code{nil}, that stands for @code{PRIMARY}.
+
+If @var{data} is @code{nil}, it means to clear out the selection.
+Otherwise, @var{data} may be a string, a symbol, an integer (or a cons
+of two integers or list of two integers), an overlay, or a cons of two
+markers pointing to the same buffer.  An overlay or a pair of markers
+stands for text in the overlay or between the markers.  The argument
+@var{data} may also be a vector of valid non-vector selection values.
 
 This function returns @var{data}.
 @end deffn
@@ -2019,14 +2023,6 @@ and @code{x-set-selection} on MS-Windows support the text data type
 only; if the clipboard holds other types of data, Emacs treats the
 clipboard as empty.
 
-@defopt x-select-enable-clipboard
-If this is non-@code{nil}, the Emacs yank functions consult the
-clipboard before the primary selection, and the kill functions store in
-the clipboard as well as the primary selection.  Otherwise they do not
-access the clipboard at all.  The default is @code{t} on systems with
-clipboards.
-@end defopt
-
 @node Drag and Drop
 @section Drag and Drop
 
diff --git a/etc/NEWS b/etc/NEWS
index c32159f6540..ab9900883c8 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -419,42 +419,52 @@ use the primary selection.
 In the following, we provide a list of these changes, followed by a
 list of steps to get the old behavior back if you prefer that.
 
-*** `mouse-drag-copy-region' now defaults to nil.
++++
 *** `select-active-regions' now defaults to t.
 Merely selecting text (e.g. with drag-mouse-1) no longer puts it in
-the kill-ring.  The selected text is put in the primary selection, if
+the kill ring.  The selected text is put in the primary selection, if
 the system possesses a separate primary selection facility (e.g. X).
 
++++
 **** `select-active-regions' also accepts a new value, `only'.
 This means to only set the primary selection for temporarily active
 regions (usually made by mouse-dragging or shift-selection);
 "ordinary" active regions, such as those made with C-SPC followed by
 point motion, do not alter the primary selection.
 
+---
+**** `mouse-drag-copy-region' now defaults to nil.
+
++++
 *** mouse-2 is now bound to `mouse-yank-primary'.
 This pastes from the primary selection, ignoring the kill-ring.
 Previously, mouse-2 was bound to `mouse-yank-at-click'.
 
++++
 *** `x-select-enable-clipboard' now defaults to t on all platforms.
++++
 *** `x-select-enable-primary' now defaults to nil.
 Thus, commands that kill text or copy it to the kill-ring (such as
 M-w, C-w, and C-k) also use the clipboard---not the primary selection.
 
+---
 **** The "Copy", "Cut", and "Paste" items in the "Edit" menu are now
 exactly equivalent to, respectively M-w, C-w, and C-y.
 
+---
 **** Note that on MS-Windows, `x-select-enable-clipboard' was already
 non-nil by default, as Windows does not support the primary selection
 between applications.
 
+---
 *** To return to the previous behavior, do the following:
-
 **** Change `select-active-regions' to nil.
 **** Change `mouse-drag-copy-region' to t.
 **** Change `x-select-enable-primary' to t (on X only).
 **** Change `x-select-enable-clipboard' to nil.
 **** Bind `mouse-yank-at-click' to mouse-2.
 
++++
 *** Support for X cut buffers has been removed.
 
 *** Support for X clipboard managers has been added.