diff man/killing.texi @ 25829:ac7e9e5e2ccb

#

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/man/killing.texi	Wed Sep 29 15:17:24 1999 +0000
@@ -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.