[Emacs-diffs] /srv/bzr/emacs/trunk r105111: More documentation of Emacs 24 X selection changes.

[Chong Yidong]

------------------------------------------------------------
revno: 105111
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Mon 2011-07-11 14:40:48 -0400
message:
  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.
modified:
  doc/emacs/ChangeLog
  doc/emacs/frames.texi
  doc/emacs/killing.texi
  doc/emacs/mark.texi
  doc/lispref/ChangeLog
  doc/lispref/frames.texi
  etc/NEWS

=== modified file 'doc/emacs/ChangeLog'
--- a/doc/emacs/ChangeLog       2011-07-11 16:29:15 +0000
+++ b/doc/emacs/ChangeLog       2011-07-11 18:40:48 +0000
@@ -1,3 +1,12 @@
+2011-07-11  Chong Yidong  <address@hidden>
+
+       * 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  <address@hidden>
 
        * mark.texi (Setting Mark): Clarify what's meant by "Shifted

=== modified file 'doc/emacs/frames.texi'
--- a/doc/emacs/frames.texi     2011-07-11 03:38:49 +0000
+++ b/doc/emacs/frames.texi     2011-07-11 18:40:48 +0000
@@ -119,16 +119,21 @@
 on how far away from the window edge the mouse has gone; the variable
 @code{mouse-scroll-min-lines} specifies a minimum step size.
 
address@hidden mouse-yank-primary
 @findex mouse-yank-at-click
+  Clicking with the middle mouse button, @kbd{Mouse-2}, moves point to
+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
-  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 address@hidden value,
address@hidden 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}).
+  If you change the variable @code{mouse-yank-at-point} to a
address@hidden 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
address@hidden and @code{mouse-yank-at-click}.
 
 @findex mouse-save-then-kill
   Clicking with the right mouse button, @kbd{Mouse-3}, runs the

=== modified file 'doc/emacs/killing.texi'
--- a/doc/emacs/killing.texi    2011-07-11 15:41:41 +0000
+++ b/doc/emacs/killing.texi    2011-07-11 18:40:48 +0000
@@ -520,17 +520,19 @@
 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 @address@hidden and moving point; see @ref{Setting Mark}).
 
 @vindex select-active-regions
-  If you set the region using the keyboard---for instance, by typing
address@hidden@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
address@hidden, 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
address@hidden 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.

=== modified file 'doc/emacs/mark.texi'
--- a/doc/emacs/mark.texi       2011-07-11 16:29:15 +0000
+++ b/doc/emacs/mark.texi       2011-07-11 18:40:48 +0000
@@ -68,11 +68,11 @@
 @item Mouse-3
 Set the mark at point, then move point to where you click
 (@code{mouse-save-then-kill}).
address@hidden @samp{Shifted cursor motion keys}
+Set the mark at point if the mark is inactive, then move point.
address@hidden 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

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2011-07-11 17:45:01 +0000
+++ b/doc/lispref/ChangeLog     2011-07-11 18:40:48 +0000
@@ -1,3 +1,8 @@
+2011-07-11  Chong Yidong  <address@hidden>
+
+       * frames.texi (Window System Selections): Discussion of
+       x-select-enable-clipboard moved to Emacs manual.
+
 2011-07-11  Deniz Dogan  <address@hidden>
 
        * commands.texi (Prefix Command Arguments): Remove excessive

=== modified file 'doc/lispref/frames.texi'
--- a/doc/lispref/frames.texi   2011-07-11 14:35:46 +0000
+++ b/doc/lispref/frames.texi   2011-07-11 18:40:48 +0000
@@ -1959,30 +1959,34 @@
 @node Window System Selections
 @section Window System Selections
 @cindex selection (for window systems)
address@hidden clipboard
address@hidden primary selection
address@hidden secondary selection
 
-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.
+  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},
address@hidden 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,
address@hidden  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},
address@hidden and @code{CLIPBOARD}; these are symbols with upper-case
-names, in accord with X Window System conventions.  If @var{type} is
address@hidden, 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}.
+
address@hidden should be a symbol; it is usually one of @code{PRIMARY},
address@hidden or @code{CLIPBOARD}.  These are symbols with
+upper-case names, in accord with X Window System conventions.  If
address@hidden 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
address@hidden may also be a vector of valid non-vector selection values.
 
 This function returns @var{data}.
 @end deffn
@@ -2019,14 +2023,6 @@
 only; if the clipboard holds other types of data, Emacs treats the
 clipboard as empty.
 
address@hidden x-select-enable-clipboard
-If this is address@hidden, 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.
address@hidden defopt
-
 @node Drag and Drop
 @section Drag and Drop
 

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2011-07-10 23:06:43 +0000
+++ b/etc/NEWS  2011-07-11 18:40:48 +0000
@@ -419,42 +419,52 @@
 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.