[Emacs-diffs] /srv/bzr/emacs/trunk r105092: Update Killing chapter of manual for Emacs 24 clipboard changes.

[Chong Yidong]

------------------------------------------------------------
revno: 105092
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Sun 2011-07-10 23:38:49 -0400
message:
  Update Killing chapter of manual for Emacs 24 clipboard changes.
  
  * doc/emacs/frames.texi: Move Cut and Paste node and subnodes into
  killing.texi, except Mouse Commands and Word and Line Mouse.
  
  * doc/emacs/killing.texi (Killing, Deletion and Killing, Killing by Lines)
  (Other Kill Commands, Kill Options): Copyedits.
  (Deletion and Killing, Kill Ring): Kill/yank now use clipboard.
  (Yanking): Move yank-excluded properties discussion here.
  (Cut and Paste): Move from frames.texi.  Update subnodes to
  describe x-select-enable-clipboard case.
modified:
  doc/emacs/ChangeLog
  doc/emacs/emacs.texi
  doc/emacs/frames.texi
  doc/emacs/killing.texi

=== modified file 'doc/emacs/ChangeLog'
--- a/doc/emacs/ChangeLog       2011-07-10 18:35:59 +0000
+++ b/doc/emacs/ChangeLog       2011-07-11 03:38:49 +0000
@@ -1,3 +1,15 @@
+2011-07-11  Chong Yidong  <address@hidden>
+
+       * killing.texi (Killing, Deletion and Killing, Killing by Lines)
+       (Other Kill Commands, Kill Options): Copyedits.
+       (Deletion and Killing, Kill Ring): Kill/yank now use clipboard.
+       (Yanking): Move yank-excluded properties discussion here.
+       (Cut and Paste): Move from frames.texi.  Update subnodes to
+       describe x-select-enable-clipboard case.
+
+       * frames.texi: Move Cut and Paste node and subnodes into
+       killing.texi, except Mouse Commands and Word and Line Mouse.
+
 2011-07-10  Andy Moreton  <address@hidden>  (tiny change)
 
        * makefile.w32-in (EMACSSOURCES): Replace major.texi with modes.texi.

=== modified file 'doc/emacs/emacs.texi'
--- a/doc/emacs/emacs.texi      2011-07-10 04:05:33 +0000
+++ b/doc/emacs/emacs.texi      2011-07-11 03:38:49 +0000
@@ -167,6 +167,7 @@
 * Mark::                The mark: how to delimit a ``region'' of text.
 * Killing::             Killing (cutting) text.
 * Yanking::             Recovering killed text.  Moving text. (Pasting.)
+* Cut and Paste::       Clipboard and selections on graphical displays.
 * Accumulating Text::   Other ways of copying text.
 * Rectangles::          Operating on text in rectangular areas.
 * CUA Bindings::        Using @kbd{C-x}, @kbd{C-c}, @kbd{C-v} to kill and yank.
@@ -329,6 +330,12 @@
 * Appending Kills::     Several kills in a row all yank together.
 * Earlier Kills::       Yanking something killed some time ago.
 
+Killing and Yanking on Graphical Displays
+
+* Clipboard::           How Emacs interacts with the system clipboard.
+* Primary Selection::   The temporarily selected text selection.
+* Secondary Selection:: Cutting without altering point and mark.
+
 Registers
 
 * RegPos::              Saving positions in registers.
@@ -493,7 +500,8 @@
 
 Frames and Graphical Displays
 
-* Cut and Paste::       Mouse commands for cut and paste.
+* Mouse Commands::      Moving, cutting, and pasting, with the mouse.
+* Word and Line Mouse:: Mouse commands for selecting whole words or lines.
 * Mouse References::    Using the mouse to select an item from a list.
 * Menu Mouse Clicks::   Mouse clicks that bring up menus.
 * Mode Line Mouse::     Mouse clicks on the mode line.
@@ -515,14 +523,6 @@
 * Non-Window Terminals::  Multiple frames on terminals that show only one.
 * Text-Only Mouse::     Using the mouse in text-only terminals.
 
-Killing and Yanking on Graphical Displays
-
-* Mouse Commands::      Moving, cutting, and pasting, with the mouse.
-* Word and Line Mouse:: Mouse commands for selecting whole words or lines.
-* Cut/Paste Other App:: Transfering text between Emacs and other apps.
-* Secondary Selection:: Cutting without altering point and mark.
-* Clipboard::           Using the clipboard for selections.
-
 International Character Set Support
 
 * International Chars::     Basic concepts of multibyte characters.

=== modified file 'doc/emacs/frames.texi'
--- a/doc/emacs/frames.texi     2011-07-02 13:17:06 +0000
+++ b/doc/emacs/frames.texi     2011-07-11 03:38:49 +0000
@@ -33,7 +33,8 @@
 @end ifnottex
 
 @menu
-* Cut and Paste::       Mouse commands for cut and paste.
+* Mouse Commands::      Moving, cutting, and pasting, with the mouse.
+* Word and Line Mouse:: Mouse commands for selecting whole words or lines.
 * Mouse References::    Using the mouse to select an item from a list.
 * Menu Mouse Clicks::   Mouse clicks that bring up menus.
 * Mode Line Mouse::     Mouse clicks on the mode line.
@@ -56,22 +57,8 @@
 * Text-Only Mouse::     Using the mouse in text-only terminals.
 @end menu
 
address@hidden Cut and Paste
address@hidden Cutting and Pasting on Graphical Displays
-
-  This section describes commands for selecting a region, cutting, and
-pasting using the mouse.
-
address@hidden
-* Mouse Commands::      Moving, cutting, and pasting, with the mouse.
-* Word and Line Mouse:: Mouse commands for selecting whole words or lines.
-* Cut/Paste Other App:: Transfering text between Emacs and other apps.
-* Secondary Selection:: Cutting without altering point and mark.
-* Clipboard::           Using the clipboard for selections.
address@hidden menu
-
 @node Mouse Commands
address@hidden Mouse Commands for Editing
address@hidden Mouse Commands for Editing
 @cindex mouse buttons (what they do)
 
 @kindex Mouse-1
@@ -141,7 +128,7 @@
 @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{Cut/Paste Other App}).
+primary and secondary selections (@pxref{Primary Selection}).
 
 @findex mouse-save-then-kill
   Clicking with the right mouse button, @kbd{Mouse-3}, runs the
@@ -195,7 +182,7 @@
 @xref{Using Region}.
 
 @node Word and Line Mouse
address@hidden Mouse Commands for Words and Lines
address@hidden Mouse Commands for Words and Lines
 
   These variants of @kbd{Mouse-1} select entire words or lines at a
 time.  Emacs activates the region around the selected text, which is
@@ -224,164 +211,6 @@
 Select the text you drag across, in the form of whole lines.
 @end table
 
address@hidden Cut/Paste Other App
address@hidden Cut and Paste with Other Window Applications
-
address@hidden X cutting and pasting
address@hidden X selection
address@hidden primary selection
address@hidden selection, primary
-  When running Emacs under the X window system, you can easily
-transfer text between Emacs and other X applications using the
address@hidden selection} (also called the @dfn{X selection}).  This is
address@hidden the same thing as the @dfn{clipboard}, which is a separate
-facility used on desktop environments such as Gnome, and on operating
-systems such as Microsoft Windows (@pxref{Clipboard}).
-
-  Under X, whenever you select some text in Emacs by dragging or
-clicking the mouse (@pxref{Mouse Commands}), it is also saved in the
-primary selection.  You can then @dfn{paste} that text into any other
-X application, usually by clicking @kbd{Mouse-2} in that application.
-Unlike the Emacs kill ring (@pxref{Kill Ring}), the primary selection
-has no ``memory'': each time you save something in the primary
-selection, either in Emacs or in another X application, the previous
-contents of the primary selection are lost.
-
address@hidden MS-Windows, and primary selection
-  MS-Windows provides no primary selection, but Emacs emulates it
-within a single Emacs session, by storing the selected text
-internally.  Therefore, all the features and commands related to the
-primary selection work on Windows as they do on X, for cutting and
-pasting within the same session, but not across Emacs sessions or with
-other applications.
-
-  Whenever you kill some text using a command such as @kbd{C-w}
-(@code{kill-region}), or copy it into the kill ring using a command
-such as @kbd{M-w} (@code{kill-ring-save}), that text is also saved in
-the primary selection.  @xref{Killing}.
-
address@hidden 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 not normally saved to the primary selection.  However,
-if you change the variable @code{select-active-regions} to @code{t},
-the region is saved to the primary selection whenever you activate the
-mark.  Each change to the region also updates the primary selection.
-
address@hidden yank-pop-change-selection
-  If you change @code{yank-pop-change-selection} to @code{t}, rotating
-the kill ring with @kbd{M-y} (@code{yank-pop}) also saves the new yank
-to the primary selection (@pxref{Yanking}).
-
address@hidden save-interprogram-paste-before-kill
-  If you change @code{save-interprogram-paste-before-kill} to
address@hidden, each kill command first saves the existing selection onto
-the kill ring.  This prevents you from losing the existing selection,
-at the risk of large memory consumption if other applications generate
-large selections.
-
-  You can yank the primary selection into Emacs using the usual yank
-commands, such as @kbd{C-y} (@code{yank}) and @kbd{Mouse-2}
-(@code{mouse-yank-at-click}).  These commands actually check the
-primary selection before referring to the kill ring; if no primary
-selection is available, the kill ring contents are used.  To prevent
-yank commands from accessing the primary selection, set the variable
address@hidden to @code{nil}.
-
-  The standard coding system for the primary selection is
address@hidden  You may find that the pasted
-text is not what you expected.  In such a case, you can specify
-another coding system for the selection by typing @kbd{C-x @key{RET}
-x} or @kbd{C-x @key{RET} X}.  Alternatively, you can request a
-different data type by modifying the variable
address@hidden  @xref{Communication Coding}.
-
address@hidden Secondary Selection
address@hidden Secondary Selection
address@hidden secondary selection
-
-  In addition to the primary selection, the X Window System provides a
-second similar facility known as the @dfn{secondary selection}.
-Nowadays, few X applications make use of the secondary selection, but
-you can access it using the following Emacs commands:
-
address@hidden @kbd
address@hidden mouse-set-secondary
address@hidden M-Drag-Mouse-1
address@hidden M-Drag-Mouse-1
-Set the secondary selection, with one end at the place where you press
-down the button, and the other end at the place where you release it
-(@code{mouse-set-secondary}).  The selected text is highlighted, using
-the @code{secondary-selection} face, as you drag.  The window scrolls
-automatically if you drag the mouse off the top or bottom of the
-window, just like @code{mouse-set-region} (@pxref{Mouse Commands}).
-
-This command does not alter the kill ring.
-
address@hidden mouse-start-secondary
address@hidden M-Mouse-1
address@hidden M-Mouse-1
-Set one endpoint for the @dfn{secondary selection}
-(@code{mouse-start-secondary}).
-
address@hidden mouse-secondary-save-then-kill
address@hidden M-Mouse-3
address@hidden M-Mouse-3
-Set the secondary selection, with one end at the position clicked and
-the other at the position specified with @kbd{M-Mouse-1}
-(@code{mouse-secondary-save-then-kill}).  This also puts the selected
-text in the kill ring.  A second @kbd{M-Mouse-3} at the same place
-kills the secondary selection just made.
-
address@hidden mouse-yank-secondary
address@hidden M-Mouse-2
address@hidden M-Mouse-2
-Insert the secondary selection where you click, placing point at the
-end of the yanked text (@code{mouse-yank-secondary}).
address@hidden table
-
-Double or triple clicking of @kbd{M-Mouse-1} operates on words and
-lines, much like @kbd{Mouse-1}.
-
-If @code{mouse-yank-at-point} is address@hidden, @kbd{M-Mouse-2} yanks
-at point.  Then it does not matter precisely where you click, or even
-which of the frame's windows you click on.  @xref{Mouse Commands}.
-
address@hidden Clipboard
address@hidden Using the Clipboard
address@hidden clipboard
-
-  In desktop environments such as Gnome, and operating systems such as
-Microsoft Windows and Mac OS X, you can transfer data (usually text)
-between different applications using the @dfn{clipboard}.  The
-clipboard is distinct from the primary selection and secondary
-selection discussed earlier.  You can access the clipboard through the
address@hidden menu of the menu bar (@pxref{Menu Bar}).
-
address@hidden cut
address@hidden clipboard-kill-region
-  The command @code{clipboard-kill-region}, which is bound to the
address@hidden menu item, kills the region and saves it in the clipboard.
-
address@hidden copy
address@hidden clipboard-kill-ring-save
-  The command @code{clipboard-kill-ring-save}, which is bound to the
address@hidden menu item, copies the region to the kill ring and saves it
-in the clipboard.
-
address@hidden clipboard-yank
address@hidden paste
-  The @code{Paste} menu item in the Edit menu yanks the contents of
-the clipboard at point (@code{clipboard-yank}).
-
address@hidden x-select-enable-clipboard
-  You can customize the variable @code{x-select-enable-clipboard} to
-make the Emacs yank functions consult the clipboard before the primary
-selection, and to make the kill functions to store in the clipboard as
-well as the primary selection.  Otherwise, these commands do not
-access the clipboard at all.  Using the clipboard is the default on
-MS-Windows and Mac OS, but not on other systems.
-
 @node Mouse References
 @section Following References with the Mouse
 @kindex Mouse-1 @r{(selection)}

=== modified file 'doc/emacs/killing.texi'
--- a/doc/emacs/killing.texi    2011-07-10 03:11:47 +0000
+++ b/doc/emacs/killing.texi    2011-07-11 03:38:49 +0000
@@ -6,17 +6,21 @@
 @node Killing, Registers, Mark, Top
 @chapter Killing and Moving Text
 
-  @dfn{Killing} means erasing text and copying it into the @dfn{kill
-ring}, from which you can bring it back into the buffer by
address@hidden it.  (Some applications use the terms ``cutting'' and
-``pasting'' for similar operations.)  This is the most common way of
-moving or copying text within Emacs.  It is very versatile, because
-there are commands for killing many different types of syntactic
-units.
+  In Emacs, @dfn{killing} means erasing text and copying it into the
address@hidden ring}.  @dfn{Yanking} means bringing text from the kill ring
+back into the buffer.  (Some applications use the terms ``cutting''
+and ``pasting'' for similar operations.)  The kill ring is so-named
+because it can be visualized as a set of blocks of text arranged in a
+ring, which you can access in cyclic order.  @xref{Kill Ring}.
+
+  Killing and yanking are the most common way to move or copy text
+within Emacs.  It is very versatile, because there are commands for
+killing many different types of syntactic units.
 
 @menu
 * Deletion and Killing:: Commands that remove text.
 * Yanking::              Commands that insert text.
+* Cut and Paste::        Clipboard and selections on graphical displays.
 * Accumulating Text::    Other methods to add text to the buffer.
 * Rectangles::           Operating on text in rectangular areas.
 * CUA Bindings::         Using @kbd{C-x}/@kbd{C-c}/@kbd{C-v} to kill and yank.
@@ -29,25 +33,28 @@
 @cindex cutting text
 @cindex deletion
   Most commands which erase text from the buffer save it in the kill
-ring.  These are known as @dfn{kill} commands.  The kill ring stores
-several recent kills, not just the last one, so killing is a very safe
-operation: when you make a new kill, you don't have to worry much
-about losing text that you previously killed.
-
-  You can yank text from the kill ring into any position in a buffer,
-including a position in a different buffer; the kill ring is shared by
-all buffers.  The @kbd{C-/} (@code{undo}) command can undo both kill
-and delete commands (@pxref{Undo}); the importance of the kill ring is
-that you can yank the text in a different place.
+ring.  These are known as @dfn{kill} commands, and their names
+normally contain the word @samp{kill} (e.g. @code{kill-line}).  The
+kill ring stores several recent kills, not just the last one, so
+killing is a very safe operation: you don't have to worry much about
+losing text that you previously killed.  The kill ring is shared by
+all buffers, so text that is killed in one buffer can be yanked into
+another buffer.
+
+  When you use @kbd{C-/} (@code{undo}) to undo a kill command
+(@pxref{Undo}), that brings the killed text back into the buffer, but
+does not remove it from the kill ring.
+
+  On graphical displays, killing text also copies it to the system
+clipboard.  @xref{Cut and Paste}.
 
   Commands that erase text but do not save it in the kill ring are
-known as @dfn{delete} commands.  These include @kbd{C-d}
-(@code{delete-char}) and @key{DEL} (@code{delete-backward-char}),
-which delete only one character at a time, and those commands that
-delete only spaces or newlines.  Commands that can erase significant
-amounts of nontrivial data generally do a kill operation instead.  The
-commands' names and individual descriptions use the words @samp{kill}
-and @samp{delete} to say which kind of operation they perform.
+known as @dfn{delete} commands; their names usually contain the word
address@hidden  These include @kbd{C-d} (@code{delete-char}) and
address@hidden (@code{delete-backward-char}), which delete only one
+character at a time, and those commands that delete only spaces or
+newlines.  Commands that can erase significant amounts of nontrivial
+data generally do a kill operation instead.
 
   You can also use the mouse to kill and yank.  @xref{Cut and Paste}.
 
@@ -127,21 +134,22 @@
 
 @kindex C-k
 @findex kill-line
-  The simplest kill command is @kbd{C-k}.  If given at the beginning
-of a line, it kills all the text on the address@hidden, ``line''
-means a logical text line, not a screen line.  @xref{Continuation
-Lines}.}, leaving it blank.  When used on a blank line, it kills the
-whole line including its newline.
+  The simplest kill command is @kbd{C-k} (@code{kill-line}).  If used
+at the end of a line, it kills the line-ending newline character,
+merging the next line into the current one (thus, a blank line is
+entirely removed).  Otherwise, @kbd{C-k} kills all the text from point
+up to the end of the line; if point was originally at the beginning of
+the line, this leaves the line blank.
 
-  More precisely, @kbd{C-k} kills from point up to the end of the
-line, unless it is at the end of a line.  In that case it kills the
-newline following point, thus merging the next line into the current
-one.  Spaces and tabs at the end of the line are ignored when deciding
-which case applies, so as long as point is after the last visible
+  Spaces and tabs at the end of the line are ignored when deciding
+which case applies.  As long as point is after the last visible
 character in the line, you can be sure that @kbd{C-k} will kill the
 newline.  To kill an entire non-blank line, go to the beginning and
 type @kbd{C-k} twice.
 
+  In this context, ``line'' means a logical text line, not a screen
+line (@pxref{Continuation Lines}).
+
   When @kbd{C-k} is given a positive argument @var{n}, it kills
 @var{n} lines and the newlines that follow them (text on the current
 line before point is not killed).  With a negative argument
@@ -157,10 +165,10 @@
 
 @kindex C-S-backspace
 @findex kill-whole-line
-  @kbd{C-S-backspace} (@code{kill-whole-line}) will kill a whole line
-including its newline regardless of the position of point within the
-line.  Note that many character terminals will prevent you from typing
-the key sequence @kbd{C-S-backspace}.
+  @kbd{C-S-backspace} (@code{kill-whole-line}) kills a whole line
+including its newline, regardless of the position of point within the
+line.  Note that many text terminals will prevent you from typing the
+key sequence @kbd{C-S-backspace}.
 
 @node Other Kill Commands
 @subsection Other Kill Commands
@@ -196,10 +204,8 @@
 
 @kindex M-w
 @findex kill-ring-save
-  The command @kbd{M-w} (@code{kill-ring-save}) copies the region into
-the kill ring without removing it from the buffer.  This is
-approximately equivalent to @kbd{C-w} followed by @kbd{C-/}, except
-that @kbd{M-w} does not alter the undo history.
+  @kbd{M-w} (@code{kill-ring-save}) copies the region into the kill
+ring without removing it from the buffer.
 
   Emacs also provides commands to kill specific syntactic units:
 words, with @address@hidden and @kbd{M-d} (@pxref{Words}); balanced
@@ -220,12 +226,10 @@
 @vindex kill-read-only-ok
 @cindex read-only text, killing
   Some specialized buffers contain @dfn{read-only text}, which cannot
-be modified and therefore cannot be killed.  But some users like to
-use the kill commands to copy read-only text into the kill ring,
-without actually changing it.  Therefore, the kill commands work
-specially in a read-only buffer: they move over text, and copy it to
+be modified and therefore cannot be killed.  The kill commands work
+specially in a read-only buffer: they move over text and copy it to
 the kill ring, without actually deleting it from the buffer.
-Normally, kill commands beep and display an error message when this
+Normally, they also beep and display an error message when this
 happens.  But if you set the variable @code{kill-read-only-ok} to a
 address@hidden value, they just print a message in the echo area to
 explain why the text has not been erased.
@@ -257,10 +261,16 @@
 Append next kill to last batch of killed text (@code{append-next-kill}).
 @end table
 
-  On graphical displays with window systems, if there is a current
-selection in some other application, and you selected it more recently
-than you killed any text in Emacs, @kbd{C-y} copies the selection
-instead of text killed within Emacs.
address@hidden yanking and text properties
address@hidden yank-excluded-properties
+  The yank commands discard certain properties from the yanked text.
+These are properties that might lead to annoying results, such as
+causing the text to respond to the mouse or specifying key bindings.
+The list of properties to discard is stored in the variable
address@hidden  These properties are also discarded
+when yanking register contents and rectangles.  @xref{Text
+Properties,,, elisp, the Emacs Lisp Reference Manual}, for more
+information about text properties.
 
 @menu
 * Kill Ring::           Where killed text is stored.  Basic yanking.
@@ -271,38 +281,34 @@
 @node Kill Ring
 @subsection The Kill Ring
 
-  All killed text is recorded in the @dfn{kill ring}, a list of blocks
-of text that have been killed.  There is only one kill ring, shared by
-all buffers, so you can kill text in one buffer and yank it in another
-buffer.  This is the usual way to move text from one file to another.
-(There are several other methods: for instance, you could store the
-text in a register.  @xref{Registers}, for information about
-registers.  @xref{Accumulating Text}, for some other ways to move text
-around.)
+  The @dfn{kill ring} is a list of blocks of text that were previously
+killed.  There is only one kill ring, shared by all buffers, so you
+can kill text in one buffer and yank it in another buffer.  This is
+the usual way to move text from one file to another.  (There are
+several other methods: for instance, you could store the text in a
+register; see @ref{Registers}.  @xref{Accumulating Text}, for some
+other ways to move text around.)
 
 @kindex C-y
 @findex yank
-  The command @kbd{C-y} (@code{yank}) reinserts the text of the most
-recent kill, leaving the cursor at the end of the text.  It also adds
-the position of the beginning of the text to the mark ring, without
-activating the mark; this allows you to jump easily to that position
-with @kbd{C-x C-x} (@pxref{Setting Mark}).  With a plain prefix
-argument (@kbd{C-u C-y}), it instead leaves the cursor in front of the
-text, and adds the position of the end of the text to the mark ring.
-Using other sort of prefix argument specifies an earlier kill; for
-example, @kbd{C-u 4 C-y} reinserts the fourth most recent kill.
address@hidden Kills}.
-
address@hidden yanking and text properties
address@hidden yank-excluded-properties
-  The yank commands discard certain properties from the yanked text.
-These are properties that might lead to annoying results, such as
-causing the text to respond to the mouse or specifying key bindings.
-The list of properties to discard is stored in the variable
address@hidden  Yanking of register contents and
-rectangles also discard these properties.  @xref{Text Properties,,,
-elisp, the Emacs Lisp Reference Manual}, for more information about
-text properties.
+  @kbd{C-y} (@code{yank}) reinserts the text of the most recent kill,
+leaving the cursor at the end of the text.  It also adds the position
+of the beginning of the text to the mark ring, without activating the
+mark; this allows you to jump easily to that position with @kbd{C-x
+C-x} (@pxref{Setting Mark}).
+
+  On graphical displays, @kbd{C-y} first checks if another application
+has placed any text in the system clipboard more recently than the
+last Emacs kill.  If so, it inserts from the clipboard instead of the
+kill ring.  Conceptually, you can think of the clipboard as an
+``extra'' entry in the kill ring, which is present if you recently cut
+or copied some text in another application.  @xref{Cut and Paste}.
+
+  With a plain prefix argument (@kbd{C-u C-y}), the @code{yank}
+command instead leaves the cursor in front of the text, and adds the
+position of the end of the text to the mark ring.  Using any other
+prefix argument specifies an earlier kill; for example, @kbd{C-u 4
+C-y} reinserts the fourth most recent kill.  @xref{Earlier Kills}.
 
 @node Appending Kills
 @subsection Appending Kills
@@ -418,6 +424,177 @@
 @code{kill-ring}; you can view the entire contents of the kill ring with
 the command @kbd{C-h v kill-ring}.
 
address@hidden Cut and Paste
address@hidden ``Cut and Paste'' Operations on Graphical Displays
address@hidden cut
address@hidden copy
address@hidden paste
+
+  In most graphical desktop environments, you can transfer data
+(usually text) between different applications using a system facility
+called the @dfn{clipboard}.  On X, two other similar facilities are
+available: the primary selection and the secondary selection.  When
+Emacs is run on a graphical display, its kill and yank commands
+integrate with these facilities, so that you can easily transfer text
+between Emacs and other graphical applications.
+
+  By default, Emacs uses UTF-8 as the coding system for inter-program
+text transfers.  If you find that the pasted text is not what you
+expected, you can specify another coding system by typing @kbd{C-x
address@hidden x} or @kbd{C-x @key{RET} X}.  You can also request a
+different data type by customizing @code{x-select-request-type}.
address@hidden Coding}.
+
address@hidden
+* Clipboard::           How Emacs uses the system clipboard.
+* Primary Selection::   The temporarily selected text selection.
+* Secondary Selection:: Cutting without altering point and mark.
address@hidden menu
+
address@hidden Clipboard
address@hidden Using the Clipboard
address@hidden clipboard
+
+  The @dfn{clipboard} is the facility that most graphical applications
+use for ``cutting and pasting''.  When the clipboard exists, the kill
+and yank commands in Emacs make use of it.
+
+  When you kill some text with a command such as @kbd{C-w}
+(@code{kill-region}), or copy it to the kill ring with a command such
+as @kbd{M-w} (@code{kill-ring-save}), that text is also put in the
+clipboard.  @xref{Killing}.
+
address@hidden save-interprogram-paste-before-kill
+  When an Emacs kill command puts text in the clipboard, the existing
+clipboard contents are normally lost.  Optionally, you can change
address@hidden to @code{t}.  Then Emacs
+will first save the clipboard to its kill ring, preventing you from
+losing the old clipboard data---at the risk of high memory consumption
+if that data turns out to be large.
+
+  The usual yank commands, such as @kbd{C-y} (@code{yank}), also use
+the clipboard.  If another application ``owns'' the clipboard---i.e.,
+if you cut or copied text there more recently than your last kill
+command in Emacs---then Emacs yanks from the clipboard instead of the
+kill ring.  Otherwise, it yanks from the kill ring, as described in
address@hidden
+
address@hidden yank-pop-change-selection
+  Normally, rotating the kill ring with @kbd{M-y} (@code{yank-pop})
+does not alter the clipboard.  However, if you change
address@hidden to @code{t}, then @kbd{M-y} saves the
+new yank to the clipboard.
+
address@hidden x-select-enable-clipboard
+  To prevent kill and yank commands from accessing the clipboard,
+change the variable @code{x-select-enable-clipboard} to @code{nil}.
+
address@hidden x-select-enable-primary
address@hidden clipboard-kill-region
address@hidden clipboard-kill-ring-save
address@hidden clipboard-yank
+  Prior to Emacs 24, the kill and yank commands used the primary
+selection (@pxref{Primary Selection}), not the clipboard.  If you
+prefer this behavior, change @code{x-select-enable-clipboard} to
address@hidden, @code{x-select-enable-primary} to @code{t}, and
address@hidden to @code{t}.  In this case, you can use
+the following commands to act explicitly on the clipboard:
address@hidden kills the region and saves it to the
+clipboard; @code{clipboard-kill-ring-save} copies the region to the
+kill ring and saves it to the clipboard; and @code{clipboard-yank}
+yanks the contents of the clipboard at point.
+
address@hidden Primary Selection
address@hidden Cut and Paste with Other Window Applications
address@hidden X cutting and pasting
address@hidden X selection
address@hidden primary selection
address@hidden selection, primary
+
+  Under the X window system, there exists a @dfn{primary selection}
+containing the last stretch of text selected in an X application
+(usually by dragging the mouse).  Typically, this text can be inserted
+into other X applications by @kbd{mouse-2} clicks.  The primary
+selection is separate from the clipboard (@pxref{Clipboard}).  Its
+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.
+
address@hidden 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}.
+
+  To insert the primary selection into an Emacs buffer, click
address@hidden (@code{mouse-yank-primary}) where you want to insert it.
address@hidden Commands}.
+
address@hidden MS-Windows, and primary selection
+  MS-Windows provides no primary selection, but Emacs emulates it
+within a single Emacs session by storing the selected text internally.
+Therefore, all the features and commands related to the primary
+selection work on Windows as they do on X, for cutting and pasting
+within the same session, but not across Emacs sessions or with other
+applications.
+
address@hidden Secondary Selection
address@hidden Secondary Selection
address@hidden secondary selection
+
+  In addition to the primary selection, the X Window System provides a
+second similar facility known as the @dfn{secondary selection}.
+Nowadays, few X applications make use of the secondary selection, but
+you can access it using the following Emacs commands:
+
address@hidden @kbd
address@hidden mouse-set-secondary
address@hidden M-Drag-Mouse-1
address@hidden M-Drag-Mouse-1
+Set the secondary selection, with one end at the place where you press
+down the button, and the other end at the place where you release it
+(@code{mouse-set-secondary}).  The selected text is highlighted, using
+the @code{secondary-selection} face, as you drag.  The window scrolls
+automatically if you drag the mouse off the top or bottom of the
+window, just like @code{mouse-set-region} (@pxref{Mouse Commands}).
+
+This command does not alter the kill ring.
+
address@hidden mouse-start-secondary
address@hidden M-Mouse-1
address@hidden M-Mouse-1
+Set one endpoint for the @dfn{secondary selection}
+(@code{mouse-start-secondary}).
+
address@hidden mouse-secondary-save-then-kill
address@hidden M-Mouse-3
address@hidden M-Mouse-3
+Set the secondary selection, with one end at the position clicked and
+the other at the position specified with @kbd{M-Mouse-1}
+(@code{mouse-secondary-save-then-kill}).  This also puts the selected
+text in the kill ring.  A second @kbd{M-Mouse-3} at the same place
+kills the secondary selection just made.
+
address@hidden mouse-yank-secondary
address@hidden M-Mouse-2
address@hidden M-Mouse-2
+Insert the secondary selection where you click, placing point at the
+end of the yanked text (@code{mouse-yank-secondary}).
address@hidden table
+
+Double or triple clicking of @kbd{M-Mouse-1} operates on words and
+lines, much like @kbd{Mouse-1}.
+
+If @code{mouse-yank-at-point} is address@hidden, @kbd{M-Mouse-2} yanks
+at point.  Then it does not matter precisely where you click, or even
+which of the frame's windows you click on.  @xref{Mouse Commands}.
+
 @node Accumulating Text
 @section Accumulating Text
 @findex append-to-buffer