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