Commit | Line | Data |
---|---|---|
6bf7aab6 | 1 | @c This is part of the Emacs manual. |
b65d8176 TTN |
2 | @c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, |
3 | @c 2002, 2003, 2004, 2005 Free Software Foundation, Inc. | |
6bf7aab6 | 4 | @c See file emacs.texi for copying conditions. |
6bf7aab6 | 5 | |
1f67b1dd RS |
6 | @node Killing, Yanking, Mark, Top |
7 | @chapter Killing and Moving Text | |
6bf7aab6 | 8 | |
6cca5de0 LT |
9 | @ifnottex |
10 | @raisesections | |
11 | @end ifnottex | |
12 | ||
1f67b1dd RS |
13 | @dfn{Killing} means erasing text and copying it into the @dfn{kill |
14 | ring}, from which you can bring it back into the buffer by | |
15 | @dfn{yanking} it. (Some systems use the terms ``cutting'' and | |
16 | ``pasting'' for these operations.) This is the most common way of | |
17 | moving or copying text within Emacs. Killing and yanking is very safe | |
18 | because Emacs remembers several recent kills, not just the last one. | |
19 | It is versatile, because the many commands for killing syntactic units | |
20 | can also be used for moving those units. But there are other ways of | |
21 | copying text for special purposes. | |
22 | ||
23 | @iftex | |
6bf7aab6 | 24 | @section Deletion and Killing |
1f67b1dd | 25 | @end iftex |
6bf7aab6 DL |
26 | |
27 | @cindex killing text | |
28 | @cindex cutting text | |
29 | @cindex deletion | |
1f67b1dd RS |
30 | Most commands which erase text from the buffer save it in the kill |
31 | ring. These commands are known as @dfn{kill} commands. The commands | |
32 | that erase text but do not save it in the kill ring are known as | |
33 | @dfn{delete} commands. The @kbd{C-x u} (@code{undo}) command | |
34 | (@pxref{Undo}) can undo both kill and delete commands; the importance | |
35 | of the kill ring is that you can also yank the text in a different | |
36 | place or places. Emacs has only one kill ring for all buffers, so you | |
37 | can kill text in one buffer and yank it in another buffer. | |
8b0645d6 | 38 | |
6bf7aab6 | 39 | The delete commands include @kbd{C-d} (@code{delete-char}) and |
58fa012d EZ |
40 | @key{DEL} (@code{delete-backward-char}), which delete only one |
41 | character at a time, and those commands that delete only spaces or | |
1f67b1dd | 42 | newlines. Commands that can erase significant amounts of nontrivial |
58fa012d EZ |
43 | data generally do a kill operation instead. The commands' names and |
44 | individual descriptions use the words @samp{kill} and @samp{delete} to | |
45 | say which kind of operation they perform. | |
6bf7aab6 | 46 | |
1f67b1dd RS |
47 | @vindex kill-read-only-ok |
48 | @cindex read-only text, killing | |
49 | You cannot kill read-only text, since such text does not allow any | |
50 | kind of modification. But some users like to use the kill commands to | |
51 | copy read-only text into the kill ring, without actually changing it. | |
52 | Therefore, the kill commands work specially in a read-only buffer: | |
53 | they move over text, and copy it to the kill ring, without actually | |
54 | deleting it from the buffer. Normally, kill commands beep and display | |
55 | an error message when this happens. But if you set the variable | |
56 | @code{kill-read-only-ok} to a non-@code{nil} value, they just print a | |
57 | message in the echo area to explain why the text has not been erased. | |
dd5c1ea9 | 58 | |
6bf7aab6 DL |
59 | @menu |
60 | * Deletion:: Commands for deleting small amounts of text and | |
61 | blank areas. | |
62 | * Killing by Lines:: How to kill entire lines of text at one time. | |
63 | * Other Kill Commands:: Commands to kill large regions of text and | |
177c0ea7 | 64 | syntactic units such as words and sentences. |
1f67b1dd RS |
65 | * Graphical Kill:: The kill ring on graphical terminals: |
66 | yanking between applications. | |
6bf7aab6 DL |
67 | @end menu |
68 | ||
c46cabfa | 69 | @need 1500 |
6bf7aab6 DL |
70 | @node Deletion |
71 | @subsection Deletion | |
6bf7aab6 DL |
72 | @findex delete-backward-char |
73 | @findex delete-char | |
6bf7aab6 | 74 | |
ba5d9bfd RS |
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. | |
78 | ||
6bf7aab6 DL |
79 | @table @kbd |
80 | @item C-d | |
4933bc02 EZ |
81 | @itemx @key{Delete} |
82 | Delete next character (@code{delete-char}). If your keyboard has a | |
83 | @key{Delete} function key (usually located in the edit keypad), Emacs | |
84 | binds it to @code{delete-char} as well. | |
6bf7aab6 | 85 | @item @key{DEL} |
4933bc02 EZ |
86 | @itemx @key{BS} |
87 | Delete previous character (@code{delete-backward-char}). Some keyboards | |
c46cabfa | 88 | refer to this key as a ``backspace key'' and label it with a left arrow. |
6bf7aab6 DL |
89 | @item M-\ |
90 | Delete spaces and tabs around point (@code{delete-horizontal-space}). | |
91 | @item M-@key{SPC} | |
92 | Delete spaces and tabs around point, leaving one space | |
93 | (@code{just-one-space}). | |
94 | @item C-x C-o | |
95 | Delete blank lines around the current line (@code{delete-blank-lines}). | |
96 | @item M-^ | |
97 | Join two lines by deleting the intervening newline, along with any | |
98 | indentation following it (@code{delete-indentation}). | |
99 | @end table | |
100 | ||
2155102b RS |
101 | @kindex DEL |
102 | @kindex C-d | |
6bf7aab6 DL |
103 | The most basic delete commands are @kbd{C-d} (@code{delete-char}) and |
104 | @key{DEL} (@code{delete-backward-char}). @kbd{C-d} deletes the | |
105 | character after point, the one the cursor is ``on top of.'' This | |
106 | doesn't move point. @key{DEL} deletes the character before the cursor, | |
107 | and moves point back. You can delete newlines like any other characters | |
108 | in the buffer; deleting a newline joins two lines. Actually, @kbd{C-d} | |
109 | and @key{DEL} aren't always delete commands; when given arguments, they | |
110 | kill instead, since they can erase more than one character this way. | |
111 | ||
2155102b RS |
112 | @kindex BACKSPACE |
113 | @kindex BS | |
114 | @kindex DELETE | |
115 | Every keyboard has a large key, labeled @key{DEL}, @key{BACKSPACE}, | |
116 | @key{BS} or @key{DELETE}, which is a short distance above the | |
117 | @key{RET} or @key{ENTER} key and is normally used for erasing what you | |
9ab48fa6 | 118 | have typed. Regardless of the actual name on the key, in Emacs it is |
2155102b RS |
119 | equivalent to @key{DEL}---or it should be. |
120 | ||
79ea1938 RS |
121 | Many keyboards (including standard PC keyboards) have a |
122 | @key{BACKSPACE} key a short ways above @key{RET} or @key{ENTER}, and a | |
123 | @key{DELETE} key elsewhere. In that case, the @key{BACKSPACE} key is | |
124 | @key{DEL}, and the @key{DELETE} key is equivalent to @kbd{C-d}---or it | |
125 | should be. | |
2155102b | 126 | |
2155102b | 127 | Why do we say ``or it should be''? When Emacs starts up using a |
9ab48fa6 | 128 | window system, it determines automatically which key or keys should be |
58fa012d | 129 | equivalent to @key{DEL}. As a result, @key{BACKSPACE} and/or @key{DELETE} |
9ab48fa6 RS |
130 | keys normally do the right things. But in some unusual cases Emacs |
131 | gets the wrong information from the system. If these keys don't do | |
79ea1938 | 132 | what they ought to do, you need to tell Emacs which key to use for |
82f6ab38 | 133 | @key{DEL}. @xref{DEL Does Not Delete}, for how to do this. |
9ab48fa6 RS |
134 | |
135 | @findex normal-erase-is-backspace-mode | |
79ea1938 RS |
136 | On most text-only terminals, Emacs cannot tell which keys the |
137 | keyboard really has, so it follows a uniform plan which may or may not | |
76dd3692 EZ |
138 | fit your keyboard. The uniform plan is that the @acronym{ASCII} @key{DEL} |
139 | character deletes, and the @acronym{ASCII} @key{BS} (backspace) character asks | |
79ea1938 | 140 | for help (it is the same as @kbd{C-h}). If this is not right for your |
0ec1f115 | 141 | keyboard, such as if you find that the key which ought to delete backwards |
82f6ab38 | 142 | enters Help instead, see @ref{DEL Does Not Delete}. |
4933bc02 | 143 | |
6bf7aab6 DL |
144 | @kindex M-\ |
145 | @findex delete-horizontal-space | |
146 | @kindex M-SPC | |
147 | @findex just-one-space | |
148 | The other delete commands are those which delete only whitespace | |
149 | characters: spaces, tabs and newlines. @kbd{M-\} | |
150 | (@code{delete-horizontal-space}) deletes all the spaces and tab | |
151 | characters before and after point. @kbd{M-@key{SPC}} | |
152 | (@code{just-one-space}) does likewise but leaves a single space after | |
153 | point, regardless of the number of spaces that existed previously (even | |
870f8c97 RS |
154 | if there were none before). With a numeric argument @var{n}, it |
155 | leaves @var{n} spaces after point. | |
6bf7aab6 DL |
156 | |
157 | @kbd{C-x C-o} (@code{delete-blank-lines}) deletes all blank lines | |
158 | after the current line. If the current line is blank, it deletes all | |
159 | blank lines preceding the current line as well (leaving one blank line, | |
fda95b3d | 160 | the current line). On a solitary blank line, it deletes that line. |
6bf7aab6 DL |
161 | |
162 | @kbd{M-^} (@code{delete-indentation}) joins the current line and the | |
163 | previous line, by deleting a newline and all surrounding spaces, usually | |
164 | leaving a single space. @xref{Indentation,M-^}. | |
165 | ||
166 | @node Killing by Lines | |
167 | @subsection Killing by Lines | |
168 | ||
169 | @table @kbd | |
170 | @item C-k | |
171 | Kill rest of line or one or more lines (@code{kill-line}). | |
172 | @end table | |
173 | ||
174 | @kindex C-k | |
175 | @findex kill-line | |
176 | The simplest kill command is @kbd{C-k}. If given at the beginning of | |
177 | a line, it kills all the text on the line, leaving it blank. When used | |
178 | on a blank line, it kills the whole line including its newline. To kill | |
179 | an entire non-blank line, go to the beginning and type @kbd{C-k} twice. | |
180 | ||
181 | More generally, @kbd{C-k} kills from point up to the end of the line, | |
182 | unless it is at the end of a line. In that case it kills the newline | |
183 | following point, thus merging the next line into the current one. | |
184 | Spaces and tabs that you can't see at the end of the line are ignored | |
185 | when deciding which case applies, so if point appears to be at the end | |
186 | of the line, you can be sure @kbd{C-k} will kill the newline. | |
187 | ||
188 | When @kbd{C-k} is given a positive argument, it kills that many lines | |
189 | and the newlines that follow them (however, text on the current line | |
58fa012d | 190 | before point is not killed). With a negative argument @minus{}@var{n}, it |
6bf7aab6 DL |
191 | kills @var{n} lines preceding the current line (together with the text |
192 | on the current line before point). Thus, @kbd{C-u - 2 C-k} at the front | |
193 | of a line kills the two previous lines. | |
194 | ||
195 | @kbd{C-k} with an argument of zero kills the text before point on the | |
196 | current line. | |
197 | ||
198 | @vindex kill-whole-line | |
199 | If the variable @code{kill-whole-line} is non-@code{nil}, @kbd{C-k} at | |
200 | the very beginning of a line kills the entire line including the | |
201 | following newline. This variable is normally @code{nil}. | |
202 | ||
203 | @node Other Kill Commands | |
204 | @subsection Other Kill Commands | |
205 | @findex kill-region | |
206 | @kindex C-w | |
207 | ||
6bf7aab6 DL |
208 | @table @kbd |
209 | @item C-w | |
210 | Kill region (from point to the mark) (@code{kill-region}). | |
211 | @item M-d | |
212 | Kill word (@code{kill-word}). @xref{Words}. | |
213 | @item M-@key{DEL} | |
214 | Kill word backwards (@code{backward-kill-word}). | |
215 | @item C-x @key{DEL} | |
216 | Kill back to beginning of sentence (@code{backward-kill-sentence}). | |
217 | @xref{Sentences}. | |
218 | @item M-k | |
219 | Kill to end of sentence (@code{kill-sentence}). | |
220 | @item C-M-k | |
46497336 | 221 | Kill the following balanced expression (@code{kill-sexp}). @xref{Expressions}. |
6bf7aab6 DL |
222 | @item M-z @var{char} |
223 | Kill through the next occurrence of @var{char} (@code{zap-to-char}). | |
224 | @end table | |
225 | ||
3423ce02 RS |
226 | The most general kill command is @kbd{C-w} (@code{kill-region}), |
227 | which kills everything between point and the mark. With this command, | |
228 | you can kill any contiguous sequence of characters, if you first set | |
229 | the region around them. | |
6bf7aab6 DL |
230 | |
231 | @kindex M-z | |
232 | @findex zap-to-char | |
233 | A convenient way of killing is combined with searching: @kbd{M-z} | |
234 | (@code{zap-to-char}) reads a character and kills from point up to (and | |
235 | including) the next occurrence of that character in the buffer. A | |
236 | numeric argument acts as a repeat count. A negative argument means to | |
237 | search backward and kill text before point. | |
238 | ||
46497336 RS |
239 | Other syntactic units can be killed: words, with @kbd{M-@key{DEL}} |
240 | and @kbd{M-d} (@pxref{Words}); balanced expressions, with @kbd{C-M-k} | |
241 | (@pxref{Expressions}); and sentences, with @kbd{C-x @key{DEL}} and | |
242 | @kbd{M-k} (@pxref{Sentences}).@refill | |
6bf7aab6 | 243 | |
132c9624 AS |
244 | @node Graphical Kill |
245 | @subsection Killing on Graphical Terminals | |
246 | ||
247 | On multi-window terminals, the most recent kill done in Emacs is | |
248 | also the primary selection, if it is more recent than any selection | |
249 | you made in another program. This means that the paste commands of | |
250 | other applications with separate windows copy the text that you killed | |
251 | in Emacs. In addition, Emacs yank commands treat other applications' | |
252 | selections as part of the kill ring, so you can yank them into Emacs. | |
253 | ||
254 | @cindex Delete Selection mode | |
255 | @cindex mode, Delete Selection | |
256 | @findex delete-selection-mode | |
257 | Many window systems follow the convention that insertion while text | |
258 | is selected deletes the selected text. You can make Emacs behave this | |
259 | way by enabling Delete Selection mode, with @kbd{M-x | |
260 | delete-selection-mode}, or using Custom. Another effect of this mode | |
261 | is that @key{DEL}, @kbd{C-d} and some other keys, when a selection | |
262 | exists, will kill the whole selection. It also enables Transient Mark | |
263 | mode (@pxref{Transient Mark}). | |
264 | ||
6bf7aab6 DL |
265 | @node Yanking, Accumulating Text, Killing, Top |
266 | @section Yanking | |
267 | @cindex moving text | |
268 | @cindex copying text | |
269 | @cindex kill ring | |
270 | @cindex yanking | |
271 | @cindex pasting | |
272 | ||
273 | @dfn{Yanking} means reinserting text previously killed. This is what | |
274 | some systems call ``pasting.'' The usual way to move or copy text is to | |
b3ada791 RS |
275 | kill it and then yank it elsewhere one or more times. This is very safe |
276 | because Emacs remembers many recent kills, not just the last one. | |
6bf7aab6 DL |
277 | |
278 | @table @kbd | |
279 | @item C-y | |
280 | Yank last killed text (@code{yank}). | |
281 | @item M-y | |
282 | Replace text just yanked with an earlier batch of killed text | |
283 | (@code{yank-pop}). | |
284 | @item M-w | |
285 | Save region as last killed text without actually killing it | |
3423ce02 | 286 | (@code{kill-ring-save}). Some systems call this ``copying''. |
6bf7aab6 DL |
287 | @item C-M-w |
288 | Append next kill to last batch of killed text (@code{append-next-kill}). | |
289 | @end table | |
290 | ||
7464a646 RS |
291 | On window systems, if there is a current selection in some other |
292 | application, and you selected it more recently than you killed any | |
293 | text in Emacs, @kbd{C-y} copies the selection instead of text | |
294 | killed within Emacs. | |
295 | ||
6bf7aab6 DL |
296 | @menu |
297 | * Kill Ring:: Where killed text is stored. Basic yanking. | |
298 | * Appending Kills:: Several kills in a row all yank together. | |
299 | * Earlier Kills:: Yanking something killed some time ago. | |
300 | @end menu | |
301 | ||
302 | @node Kill Ring | |
303 | @subsection The Kill Ring | |
304 | ||
305 | All killed text is recorded in the @dfn{kill ring}, a list of blocks of | |
306 | text that have been killed. There is only one kill ring, shared by all | |
307 | buffers, so you can kill text in one buffer and yank it in another buffer. | |
308 | This is the usual way to move text from one file to another. | |
309 | (@xref{Accumulating Text}, for some other ways.) | |
310 | ||
311 | @kindex C-y | |
312 | @findex yank | |
313 | The command @kbd{C-y} (@code{yank}) reinserts the text of the most recent | |
314 | kill. It leaves the cursor at the end of the text. It sets the mark at | |
315 | the beginning of the text. @xref{Mark}. | |
316 | ||
317 | @kbd{C-u C-y} leaves the cursor in front of the text, and sets the | |
318 | mark after it. This happens only if the argument is specified with just | |
319 | a @kbd{C-u}, precisely. Any other sort of argument, including @kbd{C-u} | |
320 | and digits, specifies an earlier kill to yank (@pxref{Earlier Kills}). | |
321 | ||
c1a50bee RS |
322 | @cindex yanking and text properties |
323 | @vindex yank-excluded-properties | |
324 | The yank commands discard certain text properties from the text that | |
769508c9 | 325 | is yanked, those that might lead to annoying results. For instance, |
c1a50bee RS |
326 | they discard text properties that respond to the mouse or specify key |
327 | bindings. The variable @code{yank-excluded-properties} specifies the | |
328 | properties to discard. Yanking of register contents and rectangles | |
329 | also discard these properties. | |
330 | ||
6bf7aab6 DL |
331 | @kindex M-w |
332 | @findex kill-ring-save | |
333 | To copy a block of text, you can use @kbd{M-w} | |
334 | (@code{kill-ring-save}), which copies the region into the kill ring | |
335 | without removing it from the buffer. This is approximately equivalent | |
336 | to @kbd{C-w} followed by @kbd{C-x u}, except that @kbd{M-w} does not | |
337 | alter the undo history and does not temporarily change the screen. | |
338 | ||
339 | @node Appending Kills | |
340 | @subsection Appending Kills | |
341 | ||
342 | @cindex appending kills in the ring | |
343 | @cindex television | |
344 | Normally, each kill command pushes a new entry onto the kill ring. | |
345 | However, two or more kill commands in a row combine their text into a | |
346 | single entry, so that a single @kbd{C-y} yanks all the text as a unit, | |
347 | just as it was before it was killed. | |
348 | ||
349 | Thus, if you want to yank text as a unit, you need not kill all of it | |
350 | with one command; you can keep killing line after line, or word after | |
351 | word, until you have killed it all, and you can still get it all back at | |
352 | once. | |
353 | ||
354 | Commands that kill forward from point add onto the end of the previous | |
355 | killed text. Commands that kill backward from point add text onto the | |
356 | beginning. This way, any sequence of mixed forward and backward kill | |
357 | commands puts all the killed text into one entry without rearrangement. | |
358 | Numeric arguments do not break the sequence of appending kills. For | |
359 | example, suppose the buffer contains this text: | |
360 | ||
361 | @example | |
362 | This is a line @point{}of sample text. | |
363 | @end example | |
364 | ||
365 | @noindent | |
366 | with point shown by @point{}. If you type @kbd{M-d M-@key{DEL} M-d | |
367 | M-@key{DEL}}, killing alternately forward and backward, you end up with | |
368 | @samp{a line of sample} as one entry in the kill ring, and @samp{This | |
58fa012d EZ |
369 | is@ @ text.} in the buffer. (Note the double space between @samp{is} |
370 | and @samp{text}, which you can clean up with @kbd{M-@key{SPC}} or | |
371 | @kbd{M-q}.) | |
6bf7aab6 DL |
372 | |
373 | Another way to kill the same text is to move back two words with | |
374 | @kbd{M-b M-b}, then kill all four words forward with @kbd{C-u M-d}. | |
375 | This produces exactly the same results in the buffer and in the kill | |
376 | ring. @kbd{M-f M-f C-u M-@key{DEL}} kills the same text, all going | |
377 | backward; once again, the result is the same. The text in the kill ring | |
378 | entry always has the same order that it had in the buffer before you | |
379 | killed it. | |
380 | ||
381 | @kindex C-M-w | |
382 | @findex append-next-kill | |
383 | If a kill command is separated from the last kill command by other | |
384 | commands (not just numeric arguments), it starts a new entry on the kill | |
385 | ring. But you can force it to append by first typing the command | |
386 | @kbd{C-M-w} (@code{append-next-kill}) right before it. The @kbd{C-M-w} | |
387 | tells the following command, if it is a kill command, to append the text | |
388 | it kills to the last killed text, instead of starting a new entry. With | |
389 | @kbd{C-M-w}, you can kill several separated pieces of text and | |
390 | accumulate them to be yanked back in one place.@refill | |
391 | ||
392 | A kill command following @kbd{M-w} does not append to the text that | |
393 | @kbd{M-w} copied into the kill ring. | |
394 | ||
395 | @node Earlier Kills | |
396 | @subsection Yanking Earlier Kills | |
397 | ||
398 | @cindex yanking previous kills | |
399 | @kindex M-y | |
400 | @findex yank-pop | |
401 | To recover killed text that is no longer the most recent kill, use the | |
402 | @kbd{M-y} command (@code{yank-pop}). It takes the text previously | |
403 | yanked and replaces it with the text from an earlier kill. So, to | |
404 | recover the text of the next-to-the-last kill, first use @kbd{C-y} to | |
405 | yank the last kill, and then use @kbd{M-y} to replace it with the | |
406 | previous kill. @kbd{M-y} is allowed only after a @kbd{C-y} or another | |
407 | @kbd{M-y}. | |
408 | ||
409 | You can understand @kbd{M-y} in terms of a ``last yank'' pointer which | |
410 | points at an entry in the kill ring. Each time you kill, the ``last | |
411 | yank'' pointer moves to the newly made entry at the front of the ring. | |
412 | @kbd{C-y} yanks the entry which the ``last yank'' pointer points to. | |
413 | @kbd{M-y} moves the ``last yank'' pointer to a different entry, and the | |
414 | text in the buffer changes to match. Enough @kbd{M-y} commands can move | |
415 | the pointer to any entry in the ring, so you can get any entry into the | |
416 | buffer. Eventually the pointer reaches the end of the ring; the next | |
58fa012d | 417 | @kbd{M-y} loops back around to the first entry again. |
6bf7aab6 DL |
418 | |
419 | @kbd{M-y} moves the ``last yank'' pointer around the ring, but it does | |
420 | not change the order of the entries in the ring, which always runs from | |
421 | the most recent kill at the front to the oldest one still remembered. | |
422 | ||
423 | @kbd{M-y} can take a numeric argument, which tells it how many entries | |
424 | to advance the ``last yank'' pointer by. A negative argument moves the | |
425 | pointer toward the front of the ring; from the front of the ring, it | |
426 | moves ``around'' to the last entry and continues forward from there. | |
427 | ||
428 | Once the text you are looking for is brought into the buffer, you can | |
429 | stop doing @kbd{M-y} commands and it will stay there. It's just a copy | |
430 | of the kill ring entry, so editing it in the buffer does not change | |
431 | what's in the ring. As long as no new killing is done, the ``last | |
432 | yank'' pointer remains at the same place in the kill ring, so repeating | |
433 | @kbd{C-y} will yank another copy of the same previous kill. | |
434 | ||
0ec1f115 RS |
435 | If you know how many @kbd{M-y} commands it would take to find the |
436 | text you want, you can yank that text in one step using @kbd{C-y} with | |
437 | a numeric argument. @kbd{C-y} with an argument restores the text from | |
438 | the specified kill ring entry, counting back from the most recent as | |
439 | 1. Thus, @kbd{C-u 2 C-y} gets the next-to-the-last block of killed | |
440 | text---it is equivalent to @kbd{C-y M-y}. @kbd{C-y} with a numeric | |
441 | argument starts counting from the ``last yank'' pointer, and sets the | |
442 | ``last yank'' pointer to the entry that it yanks. | |
6bf7aab6 DL |
443 | |
444 | @vindex kill-ring-max | |
445 | The length of the kill ring is controlled by the variable | |
446 | @code{kill-ring-max}; no more than that many blocks of killed text are | |
447 | saved. | |
448 | ||
449 | @vindex kill-ring | |
450 | The actual contents of the kill ring are stored in a variable named | |
451 | @code{kill-ring}; you can view the entire contents of the kill ring with | |
452 | the command @kbd{C-h v kill-ring}. | |
453 | ||
454 | @node Accumulating Text, Rectangles, Yanking, Top | |
455 | @section Accumulating Text | |
456 | @findex append-to-buffer | |
457 | @findex prepend-to-buffer | |
458 | @findex copy-to-buffer | |
459 | @findex append-to-file | |
460 | ||
461 | @cindex accumulating scattered text | |
462 | Usually we copy or move text by killing it and yanking it, but there | |
3423ce02 | 463 | are other convenient methods for copying one block of text in many |
6bf7aab6 DL |
464 | places, or for copying many scattered blocks of text into one place. To |
465 | copy one block to many places, store it in a register | |
466 | (@pxref{Registers}). Here we describe the commands to accumulate | |
467 | scattered pieces of text into a buffer or into a file. | |
468 | ||
469 | @table @kbd | |
470 | @item M-x append-to-buffer | |
0ec1f115 | 471 | Append region to the contents of a specified buffer. |
6bf7aab6 | 472 | @item M-x prepend-to-buffer |
0ec1f115 | 473 | Prepend region to the contents of a specified buffer. |
6bf7aab6 | 474 | @item M-x copy-to-buffer |
58fa012d | 475 | Copy region into a specified buffer, deleting that buffer's old contents. |
6bf7aab6 | 476 | @item M-x insert-buffer |
0ec1f115 | 477 | Insert the contents of a specified buffer into current buffer at point. |
6bf7aab6 | 478 | @item M-x append-to-file |
0ec1f115 | 479 | Append region to the contents of a specified file, at the end. |
6bf7aab6 DL |
480 | @end table |
481 | ||
482 | To accumulate text into a buffer, use @kbd{M-x append-to-buffer}. | |
483 | This reads a buffer name, then inserts a copy of the region into the | |
484 | buffer specified. If you specify a nonexistent buffer, | |
485 | @code{append-to-buffer} creates the buffer. The text is inserted | |
486 | wherever point is in that buffer. If you have been using the buffer for | |
487 | editing, the copied text goes into the middle of the text of the buffer, | |
58fa012d | 488 | starting from wherever point happens to be at that moment. |
6bf7aab6 DL |
489 | |
490 | Point in that buffer is left at the end of the copied text, so | |
491 | successive uses of @code{append-to-buffer} accumulate the text in the | |
492 | specified buffer in the same order as they were copied. Strictly | |
493 | speaking, @code{append-to-buffer} does not always append to the text | |
494 | already in the buffer---it appends only if point in that buffer is at the end. | |
495 | However, if @code{append-to-buffer} is the only command you use to alter | |
496 | a buffer, then point is always at the end. | |
497 | ||
498 | @kbd{M-x prepend-to-buffer} is just like @code{append-to-buffer} | |
499 | except that point in the other buffer is left before the copied text, so | |
500 | successive prependings add text in reverse order. @kbd{M-x | |
58fa012d | 501 | copy-to-buffer} is similar, except that any existing text in the other |
6bf7aab6 DL |
502 | buffer is deleted, so the buffer is left containing just the text newly |
503 | copied into it. | |
504 | ||
33fa6691 RS |
505 | To retrieve the accumulated text from another buffer, use the |
506 | command @kbd{M-x insert-buffer}; this too takes @var{buffername} as an | |
507 | argument. It inserts a copy of the whole text in buffer | |
0ec1f115 | 508 | @var{buffername} into the current buffer at point, and sets the mark |
33fa6691 RS |
509 | after the inserted text. Alternatively, you can select the other |
510 | buffer for editing, then copy text from it by killing. | |
511 | @xref{Buffers}, for background information on buffers. | |
6bf7aab6 DL |
512 | |
513 | Instead of accumulating text within Emacs, in a buffer, you can append | |
514 | text directly into a file with @kbd{M-x append-to-file}, which takes | |
515 | @var{filename} as an argument. It adds the text of the region to the end | |
516 | of the specified file. The file is changed immediately on disk. | |
517 | ||
518 | You should use @code{append-to-file} only with files that are | |
519 | @emph{not} being visited in Emacs. Using it on a file that you are | |
520 | editing in Emacs would change the file behind Emacs's back, which | |
521 | can lead to losing some of your editing. | |
522 | ||
523 | @node Rectangles, Registers, Accumulating Text, Top | |
524 | @section Rectangles | |
525 | @cindex rectangle | |
526 | @cindex columns (and rectangles) | |
527 | @cindex killing rectangular areas of text | |
528 | ||
529 | The rectangle commands operate on rectangular areas of the text: all | |
530 | the characters between a certain pair of columns, in a certain range of | |
531 | lines. Commands are provided to kill rectangles, yank killed rectangles, | |
532 | clear them out, fill them with blanks or text, or delete them. Rectangle | |
533 | commands are useful with text in multicolumn formats, and for changing | |
534 | text into or out of such formats. | |
535 | ||
536 | When you must specify a rectangle for a command to work on, you do it | |
537 | by putting the mark at one corner and point at the opposite corner. The | |
538 | rectangle thus specified is called the @dfn{region-rectangle} because | |
58fa012d | 539 | you control it in much the same way as the region is controlled. But |
6bf7aab6 DL |
540 | remember that a given combination of point and mark values can be |
541 | interpreted either as a region or as a rectangle, depending on the | |
542 | command that uses them. | |
543 | ||
544 | If point and the mark are in the same column, the rectangle they | |
545 | delimit is empty. If they are in the same line, the rectangle is one | |
546 | line high. This asymmetry between lines and columns comes about | |
547 | because point (and likewise the mark) is between two columns, but within | |
548 | a line. | |
549 | ||
550 | @table @kbd | |
551 | @item C-x r k | |
177c0ea7 | 552 | Kill the text of the region-rectangle, saving its contents as the |
6bf7aab6 DL |
553 | ``last killed rectangle'' (@code{kill-rectangle}). |
554 | @item C-x r d | |
555 | Delete the text of the region-rectangle (@code{delete-rectangle}). | |
556 | @item C-x r y | |
557 | Yank the last killed rectangle with its upper left corner at point | |
558 | (@code{yank-rectangle}). | |
559 | @item C-x r o | |
560 | Insert blank space to fill the space of the region-rectangle | |
561 | (@code{open-rectangle}). This pushes the previous contents of the | |
562 | region-rectangle rightward. | |
3b4d49d7 RS |
563 | @item C-x r c |
564 | Clear the region-rectangle by replacing its contents with spaces | |
565 | (@code{clear-rectangle}). | |
6bf7aab6 DL |
566 | @item M-x delete-whitespace-rectangle |
567 | Delete whitespace in each of the lines on the specified rectangle, | |
568 | starting from the left edge column of the rectangle. | |
d621caf7 | 569 | @item C-x r t @var{string} @key{RET} |
1e1e6d52 | 570 | Replace rectangle contents with @var{string} on each line. |
6bf7aab6 | 571 | (@code{string-rectangle}). |
1e1e6d52 | 572 | @item M-x string-insert-rectangle @key{RET} @var{string} @key{RET} |
e9db3bf2 | 573 | Insert @var{string} on each line of the rectangle. |
6bf7aab6 DL |
574 | @end table |
575 | ||
58fa012d EZ |
576 | The rectangle operations fall into two classes: commands for |
577 | deleting and inserting rectangles, and commands for blank rectangles. | |
6bf7aab6 DL |
578 | |
579 | @kindex C-x r k | |
580 | @kindex C-x r d | |
581 | @findex kill-rectangle | |
582 | @findex delete-rectangle | |
583 | There are two ways to get rid of the text in a rectangle: you can | |
584 | discard the text (delete it) or save it as the ``last killed'' | |
585 | rectangle. The commands for these two ways are @kbd{C-x r d} | |
586 | (@code{delete-rectangle}) and @kbd{C-x r k} (@code{kill-rectangle}). In | |
587 | either case, the portion of each line that falls inside the rectangle's | |
58fa012d | 588 | boundaries is deleted, causing any following text on the line to |
6bf7aab6 DL |
589 | move left into the gap. |
590 | ||
591 | Note that ``killing'' a rectangle is not killing in the usual sense; the | |
592 | rectangle is not stored in the kill ring, but in a special place that | |
593 | can only record the most recent rectangle killed. This is because yanking | |
594 | a rectangle is so different from yanking linear text that different yank | |
595 | commands have to be used and yank-popping is hard to make sense of. | |
596 | ||
597 | @kindex C-x r y | |
598 | @findex yank-rectangle | |
599 | To yank the last killed rectangle, type @kbd{C-x r y} | |
600 | (@code{yank-rectangle}). Yanking a rectangle is the opposite of killing | |
601 | one. Point specifies where to put the rectangle's upper left corner. | |
602 | The rectangle's first line is inserted there, the rectangle's second | |
d7d7da37 EZ |
603 | line is inserted at the same horizontal position, but one line |
604 | vertically down, and so on. The number of lines affected is determined | |
605 | by the height of the saved rectangle. | |
6bf7aab6 DL |
606 | |
607 | You can convert single-column lists into double-column lists using | |
608 | rectangle killing and yanking; kill the second half of the list as a | |
609 | rectangle and then yank it beside the first line of the list. | |
610 | @xref{Two-Column}, for another way to edit multi-column text. | |
611 | ||
612 | You can also copy rectangles into and out of registers with @kbd{C-x r | |
613 | r @var{r}} and @kbd{C-x r i @var{r}}. @xref{RegRect,,Rectangle | |
614 | Registers}. | |
615 | ||
616 | @kindex C-x r o | |
617 | @findex open-rectangle | |
3b4d49d7 | 618 | @kindex C-x r c |
6bf7aab6 DL |
619 | @findex clear-rectangle |
620 | There are two commands you can use for making blank rectangles: | |
3b4d49d7 RS |
621 | @kbd{C-x r c} (@code{clear-rectangle}) which blanks out existing text, |
622 | and @kbd{C-x r o} (@code{open-rectangle}) which inserts a blank | |
623 | rectangle. Clearing a rectangle is equivalent to deleting it and then | |
624 | inserting a blank rectangle of the same size. | |
6bf7aab6 DL |
625 | |
626 | @findex delete-whitespace-rectangle | |
627 | The command @kbd{M-x delete-whitespace-rectangle} deletes horizontal | |
628 | whitespace starting from a particular column. This applies to each of | |
629 | the lines in the rectangle, and the column is specified by the left | |
630 | edge of the rectangle. The right edge of the rectangle does not make | |
631 | any difference to this command. | |
632 | ||
633 | @kindex C-x r t | |
634 | @findex string-rectangle | |
d57211a3 | 635 | The command @kbd{C-x r t} (@code{string-rectangle}) replaces the |
1e1e6d52 GM |
636 | contents of a region-rectangle with a string on each line. The |
637 | string's width need not be the same as the width of the rectangle. If | |
638 | the string's width is less, the text after the rectangle shifts left; | |
639 | if the string is wider than the rectangle, the text after the | |
640 | rectangle shifts right. | |
641 | ||
642 | @findex string-insert-rectangle | |
177c0ea7 JB |
643 | The command @kbd{M-x string-insert-rectangle} is similar to |
644 | @code{string-rectangle}, but inserts the string on each line, | |
1e1e6d52 | 645 | shifting the original text to the right. |
ab5796a9 | 646 | |
6cca5de0 LT |
647 | @ifnottex |
648 | @lowersections | |
649 | @end ifnottex | |
650 | ||
ab5796a9 MB |
651 | @ignore |
652 | arch-tag: d8da8f96-0928-449a-816e-ff2d3497866c | |
653 | @end ignore |