diff options
Diffstat (limited to 'man/killing.texi')
| -rw-r--r-- | man/killing.texi | 548 |
1 files changed, 548 insertions, 0 deletions
diff --git a/man/killing.texi b/man/killing.texi new file mode 100644 index 00000000000..ef5e51a14a0 --- /dev/null +++ b/man/killing.texi @@ -0,0 +1,548 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@iftex +@chapter Killing and Moving Text + + @dfn{Killing} means erasing text and copying it into the @dfn{kill +ring}, from which it can be retrieved by @dfn{yanking} it. Some systems +use the terms ``cutting'' and ``pasting'' for these operations. + + The commonest way of moving or copying text within Emacs is to kill it +and later yank it elsewhere in one or more places. This is very safe +because Emacs remembers several recent kills, not just the last one. It +is versatile, because the many commands for killing syntactic units can +also be used for moving those units. But there are other ways of +copying text for special purposes. + + Emacs has only one kill ring for all buffers, so you can kill text in +one buffer and yank it in another buffer. + +@end iftex + +@node Killing, Yanking, Mark, Top +@section Deletion and Killing + +@cindex killing text +@cindex cutting text +@cindex deletion + Most commands which erase text from the buffer save it in the kill +ring so that you can move or copy it to other parts of the buffer. +These commands are known as @dfn{kill} commands. The rest of the +commands that erase text do not save it in the kill ring; they are known +as @dfn{delete} commands. (This distinction is made only for erasure of +text in the buffer.) If you do a kill or delete command by mistake, you +can use the @kbd{C-x u} (@code{undo}) command to undo it +(@pxref{Undo}). + + The delete commands include @kbd{C-d} (@code{delete-char}) and +@key{DEL} (@code{delete-backward-char}), which delete only one character at +a time, and those commands that delete only spaces or newlines. Commands +that can destroy significant amounts of nontrivial data generally kill. +The commands' names and individual descriptions use the words @samp{kill} +and @samp{delete} to say which they do. + +@menu +* Deletion:: Commands for deleting small amounts of text and + blank areas. +* Killing by Lines:: How to kill entire lines of text at one time. +* Other Kill Commands:: Commands to kill large regions of text and + syntactic units such as words and sentences. +@end menu + +@node Deletion +@subsection Deletion +@c ??? Should be backward-delete-char +@findex delete-backward-char +@findex delete-char +@kindex DEL +@kindex C-d + +@table @kbd +@item C-d +Delete next character (@code{delete-char}). +@item @key{DEL} +Delete previous character (@code{delete-backward-char}). +@item M-\ +Delete spaces and tabs around point (@code{delete-horizontal-space}). +@item M-@key{SPC} +Delete spaces and tabs around point, leaving one space +(@code{just-one-space}). +@item C-x C-o +Delete blank lines around the current line (@code{delete-blank-lines}). +@item M-^ +Join two lines by deleting the intervening newline, along with any +indentation following it (@code{delete-indentation}). +@end table + + The most basic delete commands are @kbd{C-d} (@code{delete-char}) and +@key{DEL} (@code{delete-backward-char}). @kbd{C-d} deletes the +character after point, the one the cursor is ``on top of.'' This +doesn't move point. @key{DEL} deletes the character before the cursor, +and moves point back. You can delete newlines like any other characters +in the buffer; deleting a newline joins two lines. Actually, @kbd{C-d} +and @key{DEL} aren't always delete commands; when given arguments, they +kill instead, since they can erase more than one character this way. + +@kindex M-\ +@findex delete-horizontal-space +@kindex M-SPC +@findex just-one-space + The other delete commands are those which delete only whitespace +characters: spaces, tabs and newlines. @kbd{M-\} +(@code{delete-horizontal-space}) deletes all the spaces and tab +characters before and after point. @kbd{M-@key{SPC}} +(@code{just-one-space}) does likewise but leaves a single space after +point, regardless of the number of spaces that existed previously (even +zero). + + @kbd{C-x C-o} (@code{delete-blank-lines}) deletes all blank lines +after the current line. If the current line is blank, it deletes all +blank lines preceding the current line as well (leaving one blank line, +the current line). + + @kbd{M-^} (@code{delete-indentation}) joins the current line and the +previous line, by deleting a newline and all surrounding spaces, usually +leaving a single space. @xref{Indentation,M-^}. + +@node Killing by Lines +@subsection Killing by Lines + +@table @kbd +@item C-k +Kill rest of line or one or more lines (@code{kill-line}). +@end table + +@kindex C-k +@findex kill-line + The simplest kill command is @kbd{C-k}. If given at the beginning of +a line, it kills all the text on the line, leaving it blank. When used +on a blank line, it kills the whole line including its newline. To kill +an entire non-blank line, go to the beginning and type @kbd{C-k} twice. + + More generally, @kbd{C-k} kills from point up to the end of the line, +unless it is at the end of a line. In that case it kills the newline +following point, thus merging the next line into the current one. +Spaces and tabs that you can't see at the end of the line are ignored +when deciding which case applies, so if point appears to be at the end +of the line, you can be sure @kbd{C-k} will kill the newline. + + When @kbd{C-k} is given a positive argument, it kills that many lines +and the newlines that follow them (however, text on the current line +before point is spared). With a negative argument @minus{}@var{n}, it +kills @var{n} lines preceding the current line (together with the text +on the current line before point). Thus, @kbd{C-u - 2 C-k} at the front +of a line kills the two previous lines. + + @kbd{C-k} with an argument of zero kills the text before point on the +current line. + +@vindex kill-whole-line + If the variable @code{kill-whole-line} is non-@code{nil}, @kbd{C-k} at +the very beginning of a line kills the entire line including the +following newline. This variable is normally @code{nil}. + +@node Other Kill Commands +@subsection Other Kill Commands +@findex kill-region +@kindex C-w + +@c DoubleWideCommands +@table @kbd +@item C-w +Kill region (from point to the mark) (@code{kill-region}). +@item M-d +Kill word (@code{kill-word}). @xref{Words}. +@item M-@key{DEL} +Kill word backwards (@code{backward-kill-word}). +@item C-x @key{DEL} +Kill back to beginning of sentence (@code{backward-kill-sentence}). +@xref{Sentences}. +@item M-k +Kill to end of sentence (@code{kill-sentence}). +@item C-M-k +Kill sexp (@code{kill-sexp}). @xref{Lists}. +@item M-z @var{char} +Kill through the next occurrence of @var{char} (@code{zap-to-char}). +@end table + + A kill command which is very general is @kbd{C-w} +(@code{kill-region}), which kills everything between point and the +mark. With this command, you can kill any contiguous sequence of +characters, if you first set the region around them. + +@kindex M-z +@findex zap-to-char + A convenient way of killing is combined with searching: @kbd{M-z} +(@code{zap-to-char}) reads a character and kills from point up to (and +including) the next occurrence of that character in the buffer. A +numeric argument acts as a repeat count. A negative argument means to +search backward and kill text before point. + + Other syntactic units can be killed: words, with @kbd{M-@key{DEL}} and +@kbd{M-d} (@pxref{Words}); sexps, with @kbd{C-M-k} (@pxref{Lists}); and +sentences, with @kbd{C-x @key{DEL}} and @kbd{M-k} +(@pxref{Sentences}).@refill + + You can use kill commands in read-only buffers. They don't actually +change the buffer, and they beep to warn you of that, but they do copy +the text you tried to kill into the kill ring, so you can yank it into +other buffers. Most of the kill commands move point across the text +they copy in this way, so that successive kill commands build up a +single kill ring entry as usual. + +@node Yanking, Accumulating Text, Killing, Top +@section Yanking +@cindex moving text +@cindex copying text +@cindex kill ring +@cindex yanking +@cindex pasting + + @dfn{Yanking} means reinserting text previously killed. This is what +some systems call ``pasting.'' The usual way to move or copy text is to +kill it and then yank it elsewhere one or more times. + +@table @kbd +@item C-y +Yank last killed text (@code{yank}). +@item M-y +Replace text just yanked with an earlier batch of killed text +(@code{yank-pop}). +@item M-w +Save region as last killed text without actually killing it +(@code{kill-ring-save}). +@item C-M-w +Append next kill to last batch of killed text (@code{append-next-kill}). +@end table + +@menu +* Kill Ring:: Where killed text is stored. Basic yanking. +* Appending Kills:: Several kills in a row all yank together. +* Earlier Kills:: Yanking something killed some time ago. +@end menu + +@node Kill Ring +@subsection The Kill Ring + + All killed text is recorded in the @dfn{kill ring}, a list of blocks of +text that have been killed. There is only one kill ring, shared by all +buffers, so you can kill text in one buffer and yank it in another buffer. +This is the usual way to move text from one file to another. +(@xref{Accumulating Text}, for some other ways.) + +@kindex C-y +@findex yank + The command @kbd{C-y} (@code{yank}) reinserts the text of the most recent +kill. It leaves the cursor at the end of the text. It sets the mark at +the beginning of the text. @xref{Mark}. + + @kbd{C-u C-y} leaves the cursor in front of the text, and sets the +mark after it. This happens only if the argument is specified with just +a @kbd{C-u}, precisely. Any other sort of argument, including @kbd{C-u} +and digits, specifies an earlier kill to yank (@pxref{Earlier Kills}). + +@kindex M-w +@findex kill-ring-save + To copy a block of text, you can use @kbd{M-w} +(@code{kill-ring-save}), which copies the region into the kill ring +without removing it from the buffer. This is approximately equivalent +to @kbd{C-w} followed by @kbd{C-x u}, except that @kbd{M-w} does not +alter the undo history and does not temporarily change the screen. + +@node Appending Kills +@subsection Appending Kills + +@cindex appending kills in the ring +@cindex television + Normally, each kill command pushes a new entry onto the kill ring. +However, two or more kill commands in a row combine their text into a +single entry, so that a single @kbd{C-y} yanks all the text as a unit, +just as it was before it was killed. + + Thus, if you want to yank text as a unit, you need not kill all of it +with one command; you can keep killing line after line, or word after +word, until you have killed it all, and you can still get it all back at +once. + + Commands that kill forward from point add onto the end of the previous +killed text. Commands that kill backward from point add text onto the +beginning. This way, any sequence of mixed forward and backward kill +commands puts all the killed text into one entry without rearrangement. +Numeric arguments do not break the sequence of appending kills. For +example, suppose the buffer contains this text: + +@example +This is a line @point{}of sample text. +@end example + +@noindent +with point shown by @point{}. If you type @kbd{M-d M-@key{DEL} M-d +M-@key{DEL}}, killing alternately forward and backward, you end up with +@samp{a line of sample} as one entry in the kill ring, and @samp{This +is@ @ text.} in the buffer. (Note the double space, which you can clean +up with @kbd{M-@key{SPC}} or @kbd{M-q}.) + + Another way to kill the same text is to move back two words with +@kbd{M-b M-b}, then kill all four words forward with @kbd{C-u M-d}. +This produces exactly the same results in the buffer and in the kill +ring. @kbd{M-f M-f C-u M-@key{DEL}} kills the same text, all going +backward; once again, the result is the same. The text in the kill ring +entry always has the same order that it had in the buffer before you +killed it. + +@kindex C-M-w +@findex append-next-kill + If a kill command is separated from the last kill command by other +commands (not just numeric arguments), it starts a new entry on the kill +ring. But you can force it to append by first typing the command +@kbd{C-M-w} (@code{append-next-kill}) right before it. The @kbd{C-M-w} +tells the following command, if it is a kill command, to append the text +it kills to the last killed text, instead of starting a new entry. With +@kbd{C-M-w}, you can kill several separated pieces of text and +accumulate them to be yanked back in one place.@refill + + A kill command following @kbd{M-w} does not append to the text that +@kbd{M-w} copied into the kill ring. + +@node Earlier Kills +@subsection Yanking Earlier Kills + +@cindex yanking previous kills +@kindex M-y +@findex yank-pop + To recover killed text that is no longer the most recent kill, use the +@kbd{M-y} command (@code{yank-pop}). It takes the text previously +yanked and replaces it with the text from an earlier kill. So, to +recover the text of the next-to-the-last kill, first use @kbd{C-y} to +yank the last kill, and then use @kbd{M-y} to replace it with the +previous kill. @kbd{M-y} is allowed only after a @kbd{C-y} or another +@kbd{M-y}. + + You can understand @kbd{M-y} in terms of a ``last yank'' pointer which +points at an entry in the kill ring. Each time you kill, the ``last +yank'' pointer moves to the newly made entry at the front of the ring. +@kbd{C-y} yanks the entry which the ``last yank'' pointer points to. +@kbd{M-y} moves the ``last yank'' pointer to a different entry, and the +text in the buffer changes to match. Enough @kbd{M-y} commands can move +the pointer to any entry in the ring, so you can get any entry into the +buffer. Eventually the pointer reaches the end of the ring; the next +@kbd{M-y} moves it to the first entry again. + + @kbd{M-y} moves the ``last yank'' pointer around the ring, but it does +not change the order of the entries in the ring, which always runs from +the most recent kill at the front to the oldest one still remembered. + + @kbd{M-y} can take a numeric argument, which tells it how many entries +to advance the ``last yank'' pointer by. A negative argument moves the +pointer toward the front of the ring; from the front of the ring, it +moves ``around'' to the last entry and continues forward from there. + + Once the text you are looking for is brought into the buffer, you can +stop doing @kbd{M-y} commands and it will stay there. It's just a copy +of the kill ring entry, so editing it in the buffer does not change +what's in the ring. As long as no new killing is done, the ``last +yank'' pointer remains at the same place in the kill ring, so repeating +@kbd{C-y} will yank another copy of the same previous kill. + + If you know how many @kbd{M-y} commands it would take to find the text +you want, you can yank that text in one step using @kbd{C-y} with a +numeric argument. @kbd{C-y} with an argument restores the text the +specified number of entries back in the kill ring. Thus, @kbd{C-u 2 +C-y} gets the next-to-the-last block of killed text. It is equivalent +to @kbd{C-y M-y}. @kbd{C-y} with a numeric argument starts counting +from the ``last yank'' pointer, and sets the ``last yank'' pointer to +the entry that it yanks. + +@vindex kill-ring-max + The length of the kill ring is controlled by the variable +@code{kill-ring-max}; no more than that many blocks of killed text are +saved. + +@vindex kill-ring + The actual contents of the kill ring are stored in a variable named +@code{kill-ring}; you can view the entire contents of the kill ring with +the command @kbd{C-h v kill-ring}. + +@node Accumulating Text, Rectangles, Yanking, Top +@section Accumulating Text +@findex append-to-buffer +@findex prepend-to-buffer +@findex copy-to-buffer +@findex append-to-file + +@cindex accumulating scattered text + Usually we copy or move text by killing it and yanking it, but there +are other methods convenient for copying one block of text in many +places, or for copying many scattered blocks of text into one place. To +copy one block to many places, store it in a register +(@pxref{Registers}). Here we describe the commands to accumulate +scattered pieces of text into a buffer or into a file. + +@table @kbd +@item M-x append-to-buffer +Append region to contents of specified buffer. +@item M-x prepend-to-buffer +Prepend region to contents of specified buffer. +@item M-x copy-to-buffer +Copy region into specified buffer, deleting that buffer's old contents. +@item M-x insert-buffer +Insert contents of specified buffer into current buffer at point. +@item M-x append-to-file +Append region to contents of specified file, at the end. +@end table + + To accumulate text into a buffer, use @kbd{M-x append-to-buffer}. +This reads a buffer name, then inserts a copy of the region into the +buffer specified. If you specify a nonexistent buffer, +@code{append-to-buffer} creates the buffer. The text is inserted +wherever point is in that buffer. If you have been using the buffer for +editing, the copied text goes into the middle of the text of the buffer, +wherever point happens to be in it. + + Point in that buffer is left at the end of the copied text, so +successive uses of @code{append-to-buffer} accumulate the text in the +specified buffer in the same order as they were copied. Strictly +speaking, @code{append-to-buffer} does not always append to the text +already in the buffer---it appends only if point in that buffer is at the end. +However, if @code{append-to-buffer} is the only command you use to alter +a buffer, then point is always at the end. + + @kbd{M-x prepend-to-buffer} is just like @code{append-to-buffer} +except that point in the other buffer is left before the copied text, so +successive prependings add text in reverse order. @kbd{M-x +copy-to-buffer} is similar except that any existing text in the other +buffer is deleted, so the buffer is left containing just the text newly +copied into it. + + To retrieve the accumulated text from another buffer, use the command +@kbd{M-x insert-buffer}; this too takes @var{buffername} as an argument. +It inserts a copy of the text in buffer @var{buffername} into the +selected buffer. You can alternatively select the other buffer for +editing, then optionally move text from it by killing. @xref{Buffers}, +for background information on buffers. + + Instead of accumulating text within Emacs, in a buffer, you can append +text directly into a file with @kbd{M-x append-to-file}, which takes +@var{filename} as an argument. It adds the text of the region to the end +of the specified file. The file is changed immediately on disk. + + You should use @code{append-to-file} only with files that are +@emph{not} being visited in Emacs. Using it on a file that you are +editing in Emacs would change the file behind Emacs's back, which +can lead to losing some of your editing. + +@node Rectangles, Registers, Accumulating Text, Top +@section Rectangles +@cindex rectangle +@cindex columns (and rectangles) +@cindex killing rectangular areas of text + + The rectangle commands operate on rectangular areas of the text: all +the characters between a certain pair of columns, in a certain range of +lines. Commands are provided to kill rectangles, yank killed rectangles, +clear them out, fill them with blanks or text, or delete them. Rectangle +commands are useful with text in multicolumn formats, and for changing +text into or out of such formats. + + When you must specify a rectangle for a command to work on, you do it +by putting the mark at one corner and point at the opposite corner. The +rectangle thus specified is called the @dfn{region-rectangle} because +you control it in about the same way the region is controlled. But +remember that a given combination of point and mark values can be +interpreted either as a region or as a rectangle, depending on the +command that uses them. + + If point and the mark are in the same column, the rectangle they +delimit is empty. If they are in the same line, the rectangle is one +line high. This asymmetry between lines and columns comes about +because point (and likewise the mark) is between two columns, but within +a line. + +@table @kbd +@item C-x r k +Kill the text of the region-rectangle, saving its contents as the +``last killed rectangle'' (@code{kill-rectangle}). +@item C-x r d +Delete the text of the region-rectangle (@code{delete-rectangle}). +@item C-x r y +Yank the last killed rectangle with its upper left corner at point +(@code{yank-rectangle}). +@item C-x r o +Insert blank space to fill the space of the region-rectangle +(@code{open-rectangle}). This pushes the previous contents of the +region-rectangle rightward. +@item M-x clear-rectangle +Clear the region-rectangle by replacing its contents with spaces. +@item M-x delete-whitespace-rectangle +Delete whitespace in each of the lines on the specified rectangle, +starting from the left edge column of the rectangle. +@item C-x r t @key{RET} @var{string} @key{RET} +Insert @var{string} on each line of the region-rectangle +(@code{string-rectangle}). +@end table + + The rectangle operations fall into two classes: commands deleting and +inserting rectangles, and commands for blank rectangles. + +@kindex C-x r k +@kindex C-x r d +@findex kill-rectangle +@findex delete-rectangle + There are two ways to get rid of the text in a rectangle: you can +discard the text (delete it) or save it as the ``last killed'' +rectangle. The commands for these two ways are @kbd{C-x r d} +(@code{delete-rectangle}) and @kbd{C-x r k} (@code{kill-rectangle}). In +either case, the portion of each line that falls inside the rectangle's +boundaries is deleted, causing following text (if any) on the line to +move left into the gap. + + Note that ``killing'' a rectangle is not killing in the usual sense; the +rectangle is not stored in the kill ring, but in a special place that +can only record the most recent rectangle killed. This is because yanking +a rectangle is so different from yanking linear text that different yank +commands have to be used and yank-popping is hard to make sense of. + +@kindex C-x r y +@findex yank-rectangle + To yank the last killed rectangle, type @kbd{C-x r y} +(@code{yank-rectangle}). Yanking a rectangle is the opposite of killing +one. Point specifies where to put the rectangle's upper left corner. +The rectangle's first line is inserted there, the rectangle's second +line is inserted at a position one line vertically down, and so on. The +number of lines affected is determined by the height of the saved +rectangle. + + You can convert single-column lists into double-column lists using +rectangle killing and yanking; kill the second half of the list as a +rectangle and then yank it beside the first line of the list. +@xref{Two-Column}, for another way to edit multi-column text. + + You can also copy rectangles into and out of registers with @kbd{C-x r +r @var{r}} and @kbd{C-x r i @var{r}}. @xref{RegRect,,Rectangle +Registers}. + +@kindex C-x r o +@findex open-rectangle +@findex clear-rectangle + There are two commands you can use for making blank rectangles: +@kbd{M-x clear-rectangle} which blanks out existing text, and @kbd{C-x r +o} (@code{open-rectangle}) which inserts a blank rectangle. Clearing a +rectangle is equivalent to deleting it and then inserting a blank +rectangle of the same size. + +@findex delete-whitespace-rectangle + The command @kbd{M-x delete-whitespace-rectangle} deletes horizontal +whitespace starting from a particular column. This applies to each of +the lines in the rectangle, and the column is specified by the left +edge of the rectangle. The right edge of the rectangle does not make +any difference to this command. + +@kindex C-x r t +@findex string-rectangle + The command @kbd{C-x r t} (@code{M-x string-rectangle}) replaces the +rectangle with a specified string (inserted once on each line). The +string's width need not be the same as the width of the rectangle. If +the string's width is less, the text after the rectangle shifts left; if +the string is wider than the rectangle, the text after the rectangle +shifts right. |