In display-buffer-pop-up-frame make BUFFER current (Bug#15133).
[emacs.git] / doc / emacs / killing.texi
blobcb33327faa1e6d5962878df4a6c8abbf2f8c9230
1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2013 Free Software
3 @c Foundation, Inc.
4 @c See file emacs.texi for copying conditions.
6 @node Killing
7 @chapter Killing and Moving Text
9   In Emacs, @dfn{killing} means erasing text and copying it into the
10 @dfn{kill ring}.  @dfn{Yanking} means bringing text from the kill ring
11 back into the buffer.  (Some applications use the terms ``cutting''
12 and ``pasting'' for similar operations.)  The kill ring is so-named
13 because it can be visualized as a set of blocks of text arranged in a
14 ring, which you can access in cyclic order.  @xref{Kill Ring}.
16   Killing and yanking are the most common way to move or copy text
17 within Emacs.  It is very versatile, because there are commands for
18 killing many different types of syntactic units.
20 @menu
21 * Deletion and Killing:: Commands that remove text.
22 * Yanking::              Commands that insert text.
23 * Cut and Paste::        Clipboard and selections on graphical displays.
24 * Accumulating Text::    Other methods to add text to the buffer.
25 * Rectangles::           Operating on text in rectangular areas.
26 * CUA Bindings::         Using @kbd{C-x}/@kbd{C-c}/@kbd{C-v} to kill and yank.
27 @end menu
29 @node Deletion and Killing
30 @section Deletion and Killing
32 @cindex killing text
33 @cindex cutting text
34 @cindex deletion
35   Most commands which erase text from the buffer save it in the kill
36 ring.  These are known as @dfn{kill} commands, and their names
37 normally contain the word @samp{kill} (e.g., @code{kill-line}).  The
38 kill ring stores several recent kills, not just the last one, so
39 killing is a very safe operation: you don't have to worry much about
40 losing text that you previously killed.  The kill ring is shared by
41 all buffers, so text that is killed in one buffer can be yanked into
42 another buffer.
44   When you use @kbd{C-/} (@code{undo}) to undo a kill command
45 (@pxref{Undo}), that brings the killed text back into the buffer, but
46 does not remove it from the kill ring.
48   On graphical displays, killing text also copies it to the system
49 clipboard.  @xref{Cut and Paste}.
51   Commands that erase text but do not save it in the kill ring are
52 known as @dfn{delete} commands; their names usually contain the word
53 @samp{delete}.  These include @kbd{C-d} (@code{delete-char}) and
54 @key{DEL} (@code{delete-backward-char}), which delete only one
55 character at a time, and those commands that delete only spaces or
56 newlines.  Commands that can erase significant amounts of nontrivial
57 data generally do a kill operation instead.
59   You can also use the mouse to kill and yank.  @xref{Cut and Paste}.
61 @menu
62 * Deletion::            Commands for deleting small amounts of text and
63                           blank areas.
64 * Killing by Lines::    How to kill entire lines of text at one time.
65 * Other Kill Commands:: Commands to kill large regions of text and
66                           syntactic units such as words and sentences.
67 * Kill Options::        Options that affect killing.
68 @end menu
70 @node Deletion
71 @subsection Deletion
72 @findex delete-backward-char
73 @findex delete-char
75   Deletion means erasing text and not saving it in the kill ring.  For
76 the most part, the Emacs commands that delete text are those that
77 erase just one character or only whitespace.
79 @table @kbd
80 @item @key{DEL}
81 @itemx @key{Backspace}
82 Delete the previous character, or the text in the region if it is
83 active (@code{delete-backward-char}).
85 @item @key{Delete}
86 Delete the next character, or the text in the region if it is active
87 (@code{delete-forward-char}).
89 @item C-d
90 Delete the next character (@code{delete-char}).
92 @item M-\
93 Delete spaces and tabs around point (@code{delete-horizontal-space}).
94 @item M-@key{SPC}
95 Delete spaces and tabs around point, leaving one space
96 (@code{just-one-space}).
97 @item C-x C-o
98 Delete blank lines around the current line (@code{delete-blank-lines}).
99 @item M-^
100 Join two lines by deleting the intervening newline, along with any
101 indentation following it (@code{delete-indentation}).
102 @end table
104   We have already described the basic deletion commands @key{DEL}
105 (@code{delete-backward-char}), @key{delete}
106 (@code{delete-forward-char}), and @kbd{C-d} (@code{delete-char}).
107 @xref{Erasing}.  With a numeric argument, they delete the specified
108 number of characters.  If the numeric argument is omitted or one, they
109 delete all the text in the region if it is active (@pxref{Using
110 Region}).
112 @c FIXME: `cycle-spacing' should be documented, too.  (Maybe not in
113 @c this node, tho.)  --xfq
114 @kindex M-\
115 @findex delete-horizontal-space
116 @kindex M-SPC
117 @findex just-one-space
118   The other delete commands are those that delete only whitespace
119 characters: spaces, tabs and newlines.  @kbd{M-\}
120 (@code{delete-horizontal-space}) deletes all the spaces and tab
121 characters before and after point.  With a prefix argument, this only
122 deletes spaces and tab characters before point.  @kbd{M-@key{SPC}}
123 (@code{just-one-space}) does likewise but leaves a single space before
124 point, regardless of the number of spaces that existed previously
125 (even if there were none before).  With a numeric argument @var{n}, it
126 leaves @var{n} spaces before point if @var{n} is positive; if @var{n}
127 is negative, it deletes newlines in addition to spaces and tabs,
128 leaving @var{-n} spaces before point.
130   @kbd{C-x C-o} (@code{delete-blank-lines}) deletes all blank lines
131 after the current line.  If the current line is blank, it deletes all
132 blank lines preceding the current line as well (leaving one blank line,
133 the current line).  On a solitary blank line, it deletes that line.
135   @kbd{M-^} (@code{delete-indentation}) joins the current line and the
136 previous line, by deleting a newline and all surrounding spaces, usually
137 leaving a single space.  @xref{Indentation,M-^}.
139 @node Killing by Lines
140 @subsection Killing by Lines
142 @table @kbd
143 @item C-k
144 Kill rest of line or one or more lines (@code{kill-line}).
145 @item C-S-backspace
146 Kill an entire line at once (@code{kill-whole-line})
147 @end table
149 @kindex C-k
150 @findex kill-line
151   The simplest kill command is @kbd{C-k} (@code{kill-line}).  If used
152 at the end of a line, it kills the line-ending newline character,
153 merging the next line into the current one (thus, a blank line is
154 entirely removed).  Otherwise, @kbd{C-k} kills all the text from point
155 up to the end of the line; if point was originally at the beginning of
156 the line, this leaves the line blank.
158   Spaces and tabs at the end of the line are ignored when deciding
159 which case applies.  As long as point is after the last visible
160 character in the line, you can be sure that @kbd{C-k} will kill the
161 newline.  To kill an entire non-blank line, go to the beginning and
162 type @kbd{C-k} twice.
164   In this context, ``line'' means a logical text line, not a screen
165 line (@pxref{Continuation Lines}).
167   When @kbd{C-k} is given a positive argument @var{n}, it kills
168 @var{n} lines and the newlines that follow them (text on the current
169 line before point is not killed).  With a negative argument
170 @minus{}@var{n}, it kills @var{n} lines preceding the current line,
171 together with the text on the current line before point.  @kbd{C-k}
172 with an argument of zero kills the text before point on the current
173 line.
175 @vindex kill-whole-line
176   If the variable @code{kill-whole-line} is non-@code{nil}, @kbd{C-k} at
177 the very beginning of a line kills the entire line including the
178 following newline.  This variable is normally @code{nil}.
180 @kindex C-S-backspace
181 @findex kill-whole-line
182   @kbd{C-S-backspace} (@code{kill-whole-line}) kills a whole line
183 including its newline, regardless of the position of point within the
184 line.  Note that many text terminals will prevent you from typing the
185 key sequence @kbd{C-S-backspace}.
187 @node Other Kill Commands
188 @subsection Other Kill Commands
189 @findex kill-region
190 @kindex C-w
192 @table @kbd
193 @item C-w
194 Kill the region (@code{kill-region}).
195 @item M-w
196 Copy the region into the kill ring (@code{kill-ring-save}).
197 @item M-d
198 Kill the next word (@code{kill-word}).  @xref{Words}.
199 @item M-@key{DEL}
200 Kill one word backwards (@code{backward-kill-word}).
201 @item C-x @key{DEL}
202 Kill back to beginning of sentence (@code{backward-kill-sentence}).
203 @xref{Sentences}.
204 @item M-k
205 Kill to the end of the sentence (@code{kill-sentence}).
206 @item C-M-k
207 Kill the following balanced expression (@code{kill-sexp}).  @xref{Expressions}.
208 @item M-z @var{char}
209 Kill through the next occurrence of @var{char} (@code{zap-to-char}).
210 @end table
212 @kindex C-w
213 @findex kill-region
214 @kindex M-w
215 @findex kill-ring-save
216   One of the commonly-used kill commands is @kbd{C-w}
217 (@code{kill-region}), which kills the text in the region
218 (@pxref{Mark}).  Similarly, @kbd{M-w} (@code{kill-ring-save}) copies
219 the text in the region into the kill ring without removing it from the
220 buffer.  If the mark is inactive when you type @kbd{C-w} or @kbd{M-w},
221 the command acts on the text between point and where you last set the
222 mark (@pxref{Using Region}).
224   Emacs also provides commands to kill specific syntactic units:
225 words, with @kbd{M-@key{DEL}} and @kbd{M-d} (@pxref{Words}); balanced
226 expressions, with @kbd{C-M-k} (@pxref{Expressions}); and sentences,
227 with @kbd{C-x @key{DEL}} and @kbd{M-k} (@pxref{Sentences}).
229 @kindex M-z
230 @findex zap-to-char
231   The command @kbd{M-z} (@code{zap-to-char}) combines killing with
232 searching: it reads a character and kills from point up to (and
233 including) the next occurrence of that character in the buffer.  A
234 numeric argument acts as a repeat count; a negative argument means to
235 search backward and kill text before point.
237 @node Kill Options
238 @subsection Options for Killing
240 @vindex kill-read-only-ok
241 @cindex read-only text, killing
242   Some specialized buffers contain @dfn{read-only text}, which cannot
243 be modified and therefore cannot be killed.  The kill commands work
244 specially in a read-only buffer: they move over text and copy it to
245 the kill ring, without actually deleting it from the buffer.
246 Normally, they also beep and display an error message when this
247 happens.  But if you set the variable @code{kill-read-only-ok} to a
248 non-@code{nil} value, they just print a message in the echo area to
249 explain why the text has not been erased.
251 @vindex kill-do-not-save-duplicates
252   If you change the variable @code{kill-do-not-save-duplicates} to a
253 non-@code{nil} value, identical subsequent kills yield a single
254 kill-ring entry, without duplication.
256 @node Yanking
257 @section Yanking
258 @cindex moving text
259 @cindex copying text
260 @cindex kill ring
261 @cindex yanking
262 @cindex pasting
264   @dfn{Yanking} means reinserting text previously killed.  The usual
265 way to move or copy text is to kill it and then yank it elsewhere.
267 @table @kbd
268 @item C-y
269 Yank the last kill into the buffer, at point (@code{yank}).
270 @item M-y
271 Replace the text just yanked with an earlier batch of killed text
272 (@code{yank-pop}).  @xref{Earlier Kills}.
273 @item C-M-w
274 Cause the following command, if it is a kill command, to append to the
275 previous kill (@code{append-next-kill}).  @xref{Appending Kills}.
276 @end table
278 @kindex C-y
279 @findex yank
280   The basic yanking command is @kbd{C-y} (@code{yank}).  It inserts
281 the most recent kill, leaving the cursor at the end of the inserted
282 text.  It also sets the mark at the beginning of the inserted text,
283 without activating the mark; this lets you jump easily to that
284 position, if you wish, with @kbd{C-u C-@key{SPC}} (@pxref{Mark Ring}).
286   With a plain prefix argument (@kbd{C-u C-y}), the command instead
287 leaves the cursor in front of the inserted text, and sets the mark at
288 the end.  Using any other prefix argument specifies an earlier kill;
289 e.g., @kbd{C-u 4 C-y} reinserts the fourth most recent kill.
290 @xref{Earlier Kills}.
292   On graphical displays, @kbd{C-y} first checks if another application
293 has placed any text in the system clipboard more recently than the
294 last Emacs kill.  If so, it inserts the clipboard's text instead.
295 Thus, Emacs effectively treats ``cut'' or ``copy'' clipboard
296 operations performed in other applications like Emacs kills, except
297 that they are not recorded in the kill ring.  @xref{Cut and Paste},
298 for details.
300 @menu
301 * Kill Ring::           Where killed text is stored.
302 * Earlier Kills::       Yanking something killed some time ago.
303 * Appending Kills::     Several kills in a row all yank together.
304 @end menu
306 @node Kill Ring
307 @subsection The Kill Ring
309   The @dfn{kill ring} is a list of blocks of text that were previously
310 killed.  There is only one kill ring, shared by all buffers, so you
311 can kill text in one buffer and yank it in another buffer.  This is
312 the usual way to move text from one buffer to another.  (There are
313 several other methods: for instance, you could store the text in a
314 register; see @ref{Registers}.  @xref{Accumulating Text}, for some
315 other ways to move text around.)
317 @vindex kill-ring-max
318   The maximum number of entries in the kill ring is controlled by the
319 variable @code{kill-ring-max}.  The default is 60.  If you make a new
320 kill when this limit has been reached, Emacs makes room by deleting
321 the oldest entry in the kill ring.
323 @vindex kill-ring
324   The actual contents of the kill ring are stored in a variable named
325 @code{kill-ring}; you can view the entire contents of the kill ring
326 with @kbd{C-h v kill-ring}.
328 @node Earlier Kills
329 @subsection Yanking Earlier Kills
330 @cindex yanking previous kills
332   As explained in @ref{Yanking}, you can use a numeric argument to
333 @kbd{C-y} to yank text that is no longer the most recent kill.  This
334 is useful if you remember which kill ring entry you want.  If you
335 don't, you can use the @kbd{M-y} (@code{yank-pop}) command to cycle
336 through the possibilities.
338 @kindex M-y
339 @findex yank-pop
340   If the previous command was a yank command, @kbd{M-y} takes the text
341 that was yanked and replaces it with the text from an earlier kill.
342 So, to recover the text of the next-to-the-last kill, first use
343 @kbd{C-y} to yank the last kill, and then use @kbd{M-y} to replace it
344 with the previous kill.  @kbd{M-y} is allowed only after a @kbd{C-y}
345 or another @kbd{M-y}.
347   You can understand @kbd{M-y} in terms of a ``last yank'' pointer which
348 points at an entry in the kill ring.  Each time you kill, the ``last
349 yank'' pointer moves to the newly made entry at the front of the ring.
350 @kbd{C-y} yanks the entry which the ``last yank'' pointer points to.
351 @kbd{M-y} moves the ``last yank'' pointer to a different entry, and the
352 text in the buffer changes to match.  Enough @kbd{M-y} commands can move
353 the pointer to any entry in the ring, so you can get any entry into the
354 buffer.  Eventually the pointer reaches the end of the ring; the next
355 @kbd{M-y} loops back around to the first entry again.
357   @kbd{M-y} moves the ``last yank'' pointer around the ring, but it does
358 not change the order of the entries in the ring, which always runs from
359 the most recent kill at the front to the oldest one still remembered.
361   @kbd{M-y} can take a numeric argument, which tells it how many entries
362 to advance the ``last yank'' pointer by.  A negative argument moves the
363 pointer toward the front of the ring; from the front of the ring, it
364 moves ``around'' to the last entry and continues forward from there.
366   Once the text you are looking for is brought into the buffer, you can
367 stop doing @kbd{M-y} commands and it will stay there.  It's just a copy
368 of the kill ring entry, so editing it in the buffer does not change
369 what's in the ring.  As long as no new killing is done, the ``last
370 yank'' pointer remains at the same place in the kill ring, so repeating
371 @kbd{C-y} will yank another copy of the same previous kill.
373   When you call @kbd{C-y} with a numeric argument, that also sets the
374 ``last yank'' pointer to the entry that it yanks.
376 @node Appending Kills
377 @subsection Appending Kills
379 @cindex appending kills in the ring
380   Normally, each kill command pushes a new entry onto the kill ring.
381 However, two or more kill commands in a row combine their text into a
382 single entry, so that a single @kbd{C-y} yanks all the text as a unit,
383 just as it was before it was killed.
385   Thus, if you want to yank text as a unit, you need not kill all of it
386 with one command; you can keep killing line after line, or word after
387 word, until you have killed it all, and you can still get it all back at
388 once.
390   Commands that kill forward from point add onto the end of the previous
391 killed text.  Commands that kill backward from point add text onto the
392 beginning.  This way, any sequence of mixed forward and backward kill
393 commands puts all the killed text into one entry without rearrangement.
394 Numeric arguments do not break the sequence of appending kills.  For
395 example, suppose the buffer contains this text:
397 @example
398 This is a line @point{}of sample text.
399 @end example
401 @noindent
402 with point shown by @point{}.  If you type @kbd{M-d M-@key{DEL} M-d
403 M-@key{DEL}}, killing alternately forward and backward, you end up with
404 @samp{a line of sample} as one entry in the kill ring, and @samp{This
405 is@ @ text.} in the buffer.  (Note the double space between @samp{is}
406 and @samp{text}, which you can clean up with @kbd{M-@key{SPC}} or
407 @kbd{M-q}.)
409   Another way to kill the same text is to move back two words with
410 @kbd{M-b M-b}, then kill all four words forward with @kbd{C-u M-d}.
411 This produces exactly the same results in the buffer and in the kill
412 ring.  @kbd{M-f M-f C-u M-@key{DEL}} kills the same text, all going
413 backward; once again, the result is the same.  The text in the kill ring
414 entry always has the same order that it had in the buffer before you
415 killed it.
417 @kindex C-M-w
418 @findex append-next-kill
419   If a kill command is separated from the last kill command by other
420 commands (not just numeric arguments), it starts a new entry on the kill
421 ring.  But you can force it to append by first typing the command
422 @kbd{C-M-w} (@code{append-next-kill}) right before it.  The @kbd{C-M-w}
423 tells the following command, if it is a kill command, to append the text
424 it kills to the last killed text, instead of starting a new entry.  With
425 @kbd{C-M-w}, you can kill several separated pieces of text and
426 accumulate them to be yanked back in one place.@refill
428   A kill command following @kbd{M-w} (@code{kill-ring-save}) does not
429 append to the text that @kbd{M-w} copied into the kill ring.
431 @node Cut and Paste
432 @section ``Cut and Paste'' Operations on Graphical Displays
433 @cindex cut
434 @cindex copy
435 @cindex paste
437   In most graphical desktop environments, you can transfer data
438 (usually text) between different applications using a system facility
439 called the @dfn{clipboard}.  On X, two other similar facilities are
440 available: the primary selection and the secondary selection.  When
441 Emacs is run on a graphical display, its kill and yank commands
442 integrate with these facilities, so that you can easily transfer text
443 between Emacs and other graphical applications.
445   By default, Emacs uses UTF-8 as the coding system for inter-program
446 text transfers.  If you find that the pasted text is not what you
447 expected, you can specify another coding system by typing @kbd{C-x
448 @key{RET} x} or @kbd{C-x @key{RET} X}.  You can also request a
449 different data type by customizing @code{x-select-request-type}.
450 @xref{Communication Coding}.
452 @menu
453 * Clipboard::           How Emacs uses the system clipboard.
454 * Primary Selection::   The temporarily selected text selection.
455 * Secondary Selection:: Cutting without altering point and mark.
456 @end menu
458 @node Clipboard
459 @subsection Using the Clipboard
460 @cindex clipboard
462   The @dfn{clipboard} is the facility that most graphical applications
463 use for ``cutting and pasting''.  When the clipboard exists, the kill
464 and yank commands in Emacs make use of it.
466   When you kill some text with a command such as @kbd{C-w}
467 (@code{kill-region}), or copy it to the kill ring with a command such
468 as @kbd{M-w} (@code{kill-ring-save}), that text is also put in the
469 clipboard.
471 @vindex save-interprogram-paste-before-kill
472   When an Emacs kill command puts text in the clipboard, the existing
473 clipboard contents are normally lost.  Optionally, you can change
474 @code{save-interprogram-paste-before-kill} to @code{t}.  Then Emacs
475 will first save the clipboard to its kill ring, preventing you from
476 losing the old clipboard data---at the risk of high memory consumption
477 if that data turns out to be large.
479   Yank commands, such as @kbd{C-y} (@code{yank}), also use the
480 clipboard.  If another application ``owns'' the clipboard---i.e., if
481 you cut or copied text there more recently than your last kill command
482 in Emacs---then Emacs yanks from the clipboard instead of the kill
483 ring.
485 @vindex yank-pop-change-selection
486   Normally, rotating the kill ring with @kbd{M-y} (@code{yank-pop})
487 does not alter the clipboard.  However, if you change
488 @code{yank-pop-change-selection} to @code{t}, then @kbd{M-y} saves the
489 new yank to the clipboard.
491 @vindex x-select-enable-clipboard
492   To prevent kill and yank commands from accessing the clipboard,
493 change the variable @code{x-select-enable-clipboard} to @code{nil}.
495 @cindex clipboard manager
496 @vindex x-select-enable-clipboard-manager
497   Many X desktop environments support a feature called the
498 @dfn{clipboard manager}.  If you exit Emacs while it is the current
499 ``owner'' of the clipboard data, and there is a clipboard manager
500 running, Emacs transfers the clipboard data to the clipboard manager
501 so that it is not lost.  In some circumstances, this may cause a delay
502 when exiting Emacs; if you wish to prevent Emacs from transferring
503 data to the clipboard manager, change the variable
504 @code{x-select-enable-clipboard-manager} to @code{nil}.
506 @vindex x-select-enable-primary
507 @findex clipboard-kill-region
508 @findex clipboard-kill-ring-save
509 @findex clipboard-yank
510   Prior to Emacs 24, the kill and yank commands used the primary
511 selection (@pxref{Primary Selection}), not the clipboard.  If you
512 prefer this behavior, change @code{x-select-enable-clipboard} to
513 @code{nil}, @code{x-select-enable-primary} to @code{t}, and
514 @code{mouse-drag-copy-region} to @code{t}.  In this case, you can use
515 the following commands to act explicitly on the clipboard:
516 @code{clipboard-kill-region} kills the region and saves it to the
517 clipboard; @code{clipboard-kill-ring-save} copies the region to the
518 kill ring and saves it to the clipboard; and @code{clipboard-yank}
519 yanks the contents of the clipboard at point.
521 @node Primary Selection
522 @subsection Cut and Paste with Other Window Applications
523 @cindex X cutting and pasting
524 @cindex X selection
525 @cindex primary selection
526 @cindex selection, primary
528   Under the X Window System, there exists a @dfn{primary selection}
529 containing the last stretch of text selected in an X application
530 (usually by dragging the mouse).  Typically, this text can be inserted
531 into other X applications by @kbd{mouse-2} clicks.  The primary
532 selection is separate from the clipboard.  Its contents are more
533 ``fragile''; they are overwritten each time you select text with the
534 mouse, whereas the clipboard is only overwritten by explicit ``cut''
535 or ``copy'' commands.
537   Under X, whenever the region is active (@pxref{Mark}), the text in
538 the region is saved in the primary selection.  This applies regardless
539 of whether the region was made by dragging or clicking the mouse
540 (@pxref{Mouse Commands}), or by keyboard commands (e.g., by typing
541 @kbd{C-@key{SPC}} and moving point; @pxref{Setting Mark}).
543 @vindex select-active-regions
544   If you change the variable @code{select-active-regions} to
545 @code{only}, Emacs saves only temporarily active regions to the
546 primary selection, i.e., those made with the mouse or with shift
547 selection (@pxref{Shift Selection}).  If you change
548 @code{select-active-regions} to @code{nil}, Emacs avoids saving active
549 regions to the primary selection entirely.
551   To insert the primary selection into an Emacs buffer, click
552 @kbd{mouse-2} (@code{mouse-yank-primary}) where you want to insert it.
553 @xref{Mouse Commands}.
555 @cindex MS-Windows, and primary selection
556   MS-Windows provides no primary selection, but Emacs emulates it
557 within a single Emacs session by storing the selected text internally.
558 Therefore, all the features and commands related to the primary
559 selection work on Windows as they do on X, for cutting and pasting
560 within the same session, but not across Emacs sessions or with other
561 applications.
563 @node Secondary Selection
564 @subsection Secondary Selection
565 @cindex secondary selection
567   In addition to the primary selection, the X Window System provides a
568 second similar facility known as the @dfn{secondary selection}.
569 Nowadays, few X applications make use of the secondary selection, but
570 you can access it using the following Emacs commands:
572 @table @kbd
573 @findex mouse-set-secondary
574 @kindex M-Drag-Mouse-1
575 @item M-Drag-Mouse-1
576 Set the secondary selection, with one end at the place where you press
577 down the button, and the other end at the place where you release it
578 (@code{mouse-set-secondary}).  The selected text is highlighted, using
579 the @code{secondary-selection} face, as you drag.  The window scrolls
580 automatically if you drag the mouse off the top or bottom of the
581 window, just like @code{mouse-set-region} (@pxref{Mouse Commands}).
583 This command does not alter the kill ring.
585 @findex mouse-start-secondary
586 @kindex M-Mouse-1
587 @item M-Mouse-1
588 Set one endpoint for the @dfn{secondary selection}
589 (@code{mouse-start-secondary}).
591 @findex mouse-secondary-save-then-kill
592 @kindex M-Mouse-3
593 @item M-Mouse-3
594 Set the secondary selection, with one end at the position clicked and
595 the other at the position specified with @kbd{M-Mouse-1}
596 (@code{mouse-secondary-save-then-kill}).  This also puts the selected
597 text in the kill ring.  A second @kbd{M-Mouse-3} at the same place
598 kills the secondary selection just made.
600 @findex mouse-yank-secondary
601 @kindex M-Mouse-2
602 @item M-Mouse-2
603 Insert the secondary selection where you click, placing point at the
604 end of the yanked text (@code{mouse-yank-secondary}).
605 @end table
607 Double or triple clicking of @kbd{M-Mouse-1} operates on words and
608 lines, much like @kbd{Mouse-1}.
610 If @code{mouse-yank-at-point} is non-@code{nil}, @kbd{M-Mouse-2} yanks
611 at point.  Then it does not matter precisely where you click, or even
612 which of the frame's windows you click on.  @xref{Mouse Commands}.
614 @node Accumulating Text
615 @section Accumulating Text
616 @findex append-to-buffer
617 @findex prepend-to-buffer
618 @findex copy-to-buffer
619 @findex append-to-file
621 @cindex accumulating scattered text
622   Usually we copy or move text by killing it and yanking it, but there
623 are other convenient methods for copying one block of text in many
624 places, or for copying many scattered blocks of text into one place.
625 Here we describe the commands to accumulate scattered pieces of text
626 into a buffer or into a file.
628 @table @kbd
629 @item M-x append-to-buffer
630 Append region to the contents of a specified buffer.
631 @item M-x prepend-to-buffer
632 Prepend region to the contents of a specified buffer.
633 @item M-x copy-to-buffer
634 Copy region into a specified buffer, deleting that buffer's old contents.
635 @item M-x insert-buffer
636 Insert the contents of a specified buffer into current buffer at point.
637 @item M-x append-to-file
638 Append region to the contents of a specified file, at the end.
639 @end table
641   To accumulate text into a buffer, use @kbd{M-x append-to-buffer}.
642 This reads a buffer name, then inserts a copy of the region into the
643 buffer specified.  If you specify a nonexistent buffer,
644 @code{append-to-buffer} creates the buffer.  The text is inserted
645 wherever point is in that buffer.  If you have been using the buffer for
646 editing, the copied text goes into the middle of the text of the buffer,
647 starting from wherever point happens to be at that moment.
649   Point in that buffer is left at the end of the copied text, so
650 successive uses of @code{append-to-buffer} accumulate the text in the
651 specified buffer in the same order as they were copied.  Strictly
652 speaking, @code{append-to-buffer} does not always append to the text
653 already in the buffer---it appends only if point in that buffer is at
654 the end.  However, if @code{append-to-buffer} is the only command you
655 use to alter a buffer, then point is always at the end.
657   @kbd{M-x prepend-to-buffer} is just like @code{append-to-buffer}
658 except that point in the other buffer is left before the copied text, so
659 successive prependings add text in reverse order.  @kbd{M-x
660 copy-to-buffer} is similar, except that any existing text in the other
661 buffer is deleted, so the buffer is left containing just the text newly
662 copied into it.
664   The command @kbd{M-x insert-buffer} can be used to retrieve the
665 accumulated text from another buffer.  This prompts for the name of a
666 buffer, and inserts a copy of all the text in that buffer into the
667 current buffer at point, leaving point at the beginning of the
668 inserted text.  It also adds the position of the end of the inserted
669 text to the mark ring, without activating the mark.  @xref{Buffers},
670 for background information on buffers.
672   Instead of accumulating text in a buffer, you can append text
673 directly into a file with @kbd{M-x append-to-file}.  This prompts for
674 a filename, and adds the text of the region to the end of the
675 specified file.  The file is changed immediately on disk.
677   You should use @code{append-to-file} only with files that are
678 @emph{not} being visited in Emacs.  Using it on a file that you are
679 editing in Emacs would change the file behind Emacs's back, which
680 can lead to losing some of your editing.
682   Another way to move text around is to store it in a register.
683 @xref{Registers}.
685 @node Rectangles
686 @section Rectangles
687 @cindex rectangle
688 @cindex columns (and rectangles)
689 @cindex killing rectangular areas of text
691   @dfn{Rectangle} commands operate on rectangular areas of the text:
692 all the characters between a certain pair of columns, in a certain
693 range of lines.  Emacs has commands to kill rectangles, yank killed
694 rectangles, clear them out, fill them with blanks or text, or delete
695 them.  Rectangle commands are useful with text in multicolumn formats,
696 and for changing text into or out of such formats.
698 @cindex mark rectangle
699   To specify a rectangle for a command to work on, set the mark at one
700 corner and point at the opposite corner.  The rectangle thus specified
701 is called the @dfn{region-rectangle}.  If point and the mark are in
702 the same column, the region-rectangle is empty.  If they are in the
703 same line, the region-rectangle is one line high.
705   The region-rectangle is controlled in much the same way as the
706 region is controlled.  But remember that a given combination of point
707 and mark values can be interpreted either as a region or as a
708 rectangle, depending on the command that uses them.
710 @table @kbd
711 @item C-x r k
712 Kill the text of the region-rectangle, saving its contents as the
713 ``last killed rectangle'' (@code{kill-rectangle}).
714 @item C-x r M-w
715 Save the text of the region-rectangle as the ``last killed rectangle''
716 (@code{copy-rectangle-as-kill}).
717 @item C-x r d
718 Delete the text of the region-rectangle (@code{delete-rectangle}).
719 @item C-x r y
720 Yank the last killed rectangle with its upper left corner at point
721 (@code{yank-rectangle}).
722 @item C-x r o
723 Insert blank space to fill the space of the region-rectangle
724 (@code{open-rectangle}).  This pushes the previous contents of the
725 region-rectangle to the right.
726 @item C-x r N
727 Insert line numbers along the left edge of the region-rectangle
728 (@code{rectangle-number-lines}).  This pushes the previous contents of
729 the region-rectangle to the right.
730 @item C-x r c
731 Clear the region-rectangle by replacing all of its contents with spaces
732 (@code{clear-rectangle}).
733 @item M-x delete-whitespace-rectangle
734 Delete whitespace in each of the lines on the specified rectangle,
735 starting from the left edge column of the rectangle.
736 @item C-x r t @var{string} @key{RET}
737 Replace rectangle contents with @var{string} on each line
738 (@code{string-rectangle}).
739 @item M-x string-insert-rectangle @key{RET} @var{string} @key{RET}
740 Insert @var{string} on each line of the rectangle.
741 @end table
743   The rectangle operations fall into two classes: commands to erase or
744 insert rectangles, and commands to make blank rectangles.
746 @kindex C-x r k
747 @kindex C-x r d
748 @findex kill-rectangle
749 @findex delete-rectangle
750   There are two ways to erase the text in a rectangle: @kbd{C-x r d}
751 (@code{delete-rectangle}) to delete the text outright, or @kbd{C-x r
752 k} (@code{kill-rectangle}) to remove the text and save it as the
753 @dfn{last killed rectangle}.  In both cases, erasing the
754 region-rectangle is like erasing the specified text on each line of
755 the rectangle; if there is any following text on the line, it moves
756 backwards to fill the gap.
758   ``Killing'' a rectangle is not killing in the usual sense; the
759 rectangle is not stored in the kill ring, but in a special place that
760 only records the most recent rectangle killed.  This is because
761 yanking a rectangle is so different from yanking linear text that
762 different yank commands have to be used.  Yank-popping is not defined
763 for rectangles.
765 @kindex C-x r M-w
766 @findex copy-rectangle-as-kill
767   @kbd{C-x r M-w} (@code{copy-rectangle-as-kill}) is the equivalent of
768 @kbd{M-w} for rectangles: it records the rectangle as the ``last
769 killed rectangle'', without deleting the text from the buffer.
771 @kindex C-x r y
772 @findex yank-rectangle
773   To yank the last killed rectangle, type @kbd{C-x r y}
774 (@code{yank-rectangle}).  The rectangle's first line is inserted at
775 point, the rectangle's second line is inserted at the same horizontal
776 position one line vertically below, and so on.  The number of lines
777 affected is determined by the height of the saved rectangle.
779   For example, you can convert two single-column lists into a
780 double-column list by killing one of the single-column lists as a
781 rectangle, and then yanking it beside the other list.
783   You can also copy rectangles into and out of registers with @kbd{C-x r
784 r @var{r}} and @kbd{C-x r i @var{r}}.  @xref{Rectangle Registers}.
786 @kindex C-x r o
787 @findex open-rectangle
788 @kindex C-x r c
789 @findex clear-rectangle
790   There are two commands you can use for making blank rectangles:
791 @kbd{C-x r c} (@code{clear-rectangle}) blanks out existing text in the
792 region-rectangle, and @kbd{C-x r o} (@code{open-rectangle}) inserts a
793 blank rectangle.
795 @findex delete-whitespace-rectangle
796   @kbd{M-x delete-whitespace-rectangle} deletes horizontal whitespace
797 starting from a particular column.  This applies to each of the lines
798 in the rectangle, and the column is specified by the left edge of the
799 rectangle.  The right edge of the rectangle does not make any
800 difference to this command.
802 @kindex C-x r N
803 @findex rectangle
804   The command @kbd{C-x r N} (@code{rectangle-number-lines}) inserts
805 line numbers along the left edge of the region-rectangle.  Normally,
806 the numbering begins from 1 (for the first line of the rectangle).
807 With a prefix argument, the command prompts for a number to begin
808 from, and for a format string with which to print the numbers
809 (@pxref{Formatting Strings,,, elisp, The Emacs Lisp Reference
810 Manual}).
812 @kindex C-x r t
813 @findex string-rectangle
814   The command @kbd{C-x r t} (@code{string-rectangle}) replaces the
815 contents of a region-rectangle with a string on each line.  The
816 string's width need not be the same as the width of the rectangle.  If
817 the string's width is less, the text after the rectangle shifts left;
818 if the string is wider than the rectangle, the text after the
819 rectangle shifts right.
821 @findex string-insert-rectangle
822   The command @kbd{M-x string-insert-rectangle} is similar to
823 @code{string-rectangle}, but inserts the string on each line,
824 shifting the original text to the right.
826 @node CUA Bindings
827 @section CUA Bindings
828 @findex cua-mode
829 @vindex cua-mode
830 @cindex CUA key bindings
831 @vindex cua-enable-cua-keys
832   The command @kbd{M-x cua-mode} sets up key bindings that are
833 compatible with the Common User Access (CUA) system used in many other
834 applications.
836   When CUA mode is enabled, the keys @kbd{C-x}, @kbd{C-c}, @kbd{C-v},
837 and @kbd{C-z} invoke commands that cut (kill), copy, paste (yank), and
838 undo respectively.  The @kbd{C-x} and @kbd{C-c} keys perform cut and
839 copy only if the region is active.  Otherwise, they still act as
840 prefix keys, so that standard Emacs commands like @kbd{C-x C-c} still
841 work.  Note that this means the variable @code{mark-even-if-inactive}
842 has no effect for @kbd{C-x} and @kbd{C-c} (@pxref{Using Region}).
844   To enter an Emacs command like @kbd{C-x C-f} while the mark is
845 active, use one of the following methods: either hold @kbd{Shift}
846 together with the prefix key, e.g., @kbd{S-C-x C-f}, or quickly type
847 the prefix key twice, e.g., @kbd{C-x C-x C-f}.
849   To disable the overriding of standard Emacs binding by CUA mode,
850 while retaining the other features of CUA mode described below, set
851 the variable @code{cua-enable-cua-keys} to @code{nil}.
853   In CUA mode, typed text replaces the active region as in
854 Delete-Selection mode (@pxref{Mouse Commands}).
856 @cindex rectangle highlighting
857   CUA mode provides enhanced rectangle support with visible
858 rectangle highlighting.  Use @kbd{C-RET} to start a rectangle,
859 extend it using the movement commands, and cut or copy it using
860 @kbd{C-x} or @kbd{C-c}.  @kbd{RET} moves the cursor to the next
861 (clockwise) corner of the rectangle, so you can easily expand it in
862 any direction.  Normal text you type is inserted to the left or right
863 of each line in the rectangle (on the same side as the cursor).
865   With CUA you can easily copy text and rectangles into and out of
866 registers by providing a one-digit numeric prefix to the kill, copy,
867 and yank commands, e.g., @kbd{C-1 C-c} copies the region into register
868 @code{1}, and @kbd{C-2 C-v} yanks the contents of register @code{2}.
870 @cindex global mark
871   CUA mode also has a global mark feature which allows easy moving and
872 copying of text between buffers.  Use @kbd{C-S-SPC} to toggle the
873 global mark on and off.  When the global mark is on, all text that you
874 kill or copy is automatically inserted at the global mark, and text
875 you type is inserted at the global mark rather than at the current
876 position.
878   For example, to copy words from various buffers into a word list in
879 a given buffer, set the global mark in the target buffer, then
880 navigate to each of the words you want in the list, mark it (e.g., with
881 @kbd{S-M-f}), copy it to the list with @kbd{C-c} or @kbd{M-w}, and
882 insert a newline after the word in the target list by pressing
883 @key{RET}.