[Emacs-diffs] Changes to emacs/man/killing.texi [gnus-5_10-branch]

[Miles Bader]

Index: emacs/man/killing.texi
diff -c /dev/null emacs/man/killing.texi:1.33.2.1
*** /dev/null   Sat Sep  4 12:03:00 2004
--- emacs/man/killing.texi      Sat Sep  4 12:01:15 2004
***************
*** 0 ****
--- 1,661 ----
+ @c This is part of the Emacs manual.
+ @c Copyright (C) 1985,86,87,93,94,95,97,2000,2001,2004
+ @c   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 most common 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.
+ 
+   On terminals that support multiple windows for multiple applications,
+ the kill commands also provide a way to select text for other applications
+ to copy, and the Emacs yank commands can access selections made by
+ other programs.
+ 
+   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
+ 
+ @ifnottex
+ @raisesections
+ @end ifnottex
+ 
+ @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 @dfn{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}).
+ 
+ @vindex kill-read-only-ok
+ @cindex read-only text, killing
+   You cannot kill read-only text, since such text does not allow any
+ kind of modification.  But some users like to use the kill commands to
+ copy read-only text into the kill ring, without actually changing it.
+ Therefore, the kill commands work specially in a read-only buffer:
+ they move over text, and copy it to the kill ring, without actually
+ deleting it from the buffer.  Normally, Emacs beeps and prints an
+ error message when this happens.  But if you set the variable
+ @code{kill-read-only-ok} to a address@hidden value, it just prints a
+ message in the echo area, telling you what is happening.
+ 
+   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 do a kill operation instead.  The commands' names and
+ individual descriptions use the words @samp{kill} and @samp{delete} to
+ say which kind of operation they perform.
+ 
+   On window systems, the most recent kill done in Emacs is also the
+ primary selection, if it is more recent than any selection you made in
+ another program.  This means that the paste commands of other window
+ applications copy the text that you killed in Emacs.
+ 
+ @cindex Delete Selection mode
+ @cindex mode, Delete Selection
+ @findex delete-selection-mode
+   Many window systems follow the convention that insertion while text
+ is selected deletes the selected text.  You can make Emacs behave this
+ way by enabling Delete Selection mode, with @kbd{M-x
+ delete-selection-mode}, or using Custom.  Another effect of this mode
+ is that @key{DEL}, @kbd{C-d} and some other keys, when a selection
+ exists, will kill the whole selection.  It also enables Transient Mark
+ mode (@pxref{Transient Mark}).
+ 
+ @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
+ 
+ @need 1500
+ @node Deletion
+ @subsection Deletion
+ @findex delete-backward-char
+ @findex delete-char
+ 
+   Deletion means erasing text and not saving it in the kill ring.  For
+ the most part, the Emacs commands that delete text are those that
+ erase just one character or only whitespace.
+ 
+ @table @kbd
+ @item C-d
+ @itemx @key{Delete}
+ Delete next character (@code{delete-char}).  If your keyboard has a
+ @key{Delete} function key (usually located in the edit keypad), Emacs
+ binds it to @code{delete-char} as well.
+ @item @key{DEL}
+ @itemx @key{BS}
+ Delete previous character (@code{delete-backward-char}).  Some keyboards
+ refer to this key as a ``backspace key'' and label it with a left arrow.
+ @item M-\
+ Delete spaces and tabs around point (@code{delete-horizontal-space}).
+ @item address@hidden
+ 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
+ 
+ @kindex DEL
+ @kindex C-d
+   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 BACKSPACE
+ @kindex BS
+ @kindex DELETE
+   Every keyboard has a large key, labeled @key{DEL}, @key{BACKSPACE},
+ @key{BS} or @key{DELETE}, which is a short distance above the
+ @key{RET} or @key{ENTER} key and is normally used for erasing what you
+ have typed.  Regardless of the actual name on the key, in Emacs it is
+ equivalent to @key{DEL}---or it should be.
+ 
+   Many keyboards (including standard PC keyboards) have a
+ @key{BACKSPACE} key a short ways above @key{RET} or @key{ENTER}, and a
+ @key{DELETE} key elsewhere.  In that case, the @key{BACKSPACE} key is
+ @key{DEL}, and the @key{DELETE} key is equivalent to @kbd{C-d}---or it
+ should be.
+ 
+   Why do we say ``or it should be''?  When Emacs starts up using a
+ window system, it determines automatically which key or keys should be
+ equivalent to @key{DEL}.  As a result, @key{BACKSPACE} and/or @key{DELETE}
+ keys normally do the right things.  But in some unusual cases Emacs
+ gets the wrong information from the system.  If these keys don't do
+ what they ought to do, you need to tell Emacs which key to use for
+ @key{DEL}.  @xref{DEL Does Not Delete}, for how to do this.
+ 
+ @findex normal-erase-is-backspace-mode
+   On most text-only terminals, Emacs cannot tell which keys the
+ keyboard really has, so it follows a uniform plan which may or may not
+ fit your keyboard.  The uniform plan is that the @acronym{ASCII} @key{DEL}
+ character deletes, and the @acronym{ASCII} @key{BS} (backspace) character asks
+ for help (it is the same as @kbd{C-h}).  If this is not right for your
+ keyboard, such as if you find that the key which ought to delete backwards
+ enters Help instead, see @ref{DEL Does Not Delete}.
+ 
+ @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.  @address@hidden
+ (@code{just-one-space}) does likewise but leaves a single space after
+ point, regardless of the number of spaces that existed previously (even
+ if there were none before).
+ 
+   @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 not killed).  With a negative argument @address@hidden, 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 address@hidden, @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
+ 
+ @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 address@hidden
+ 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 the following balanced expression (@code{kill-sexp}).  
@xref{Expressions}.
+ @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 @address@hidden
+ and @kbd{M-d} (@pxref{Words}); balanced expressions, with @kbd{C-M-k}
+ (@pxref{Expressions}); and sentences, with @kbd{C-x @key{DEL}} and
+ @kbd{M-k} (@pxref{Sentences})address@hidden
+ 
+   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.  This is very safe
+ because Emacs remembers many recent kills, not just the last one.
+ 
+ @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
+ 
+   On window systems, if there is a current selection in some other
+ application, and you selected it more recently than you killed any
+ text in Emacs, @kbd{C-y} copies the selection instead of text
+ killed within Emacs.
+ 
+ @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}).
+ 
+ @cindex yanking and text properties
+ @vindex yank-excluded-properties
+   The yank commands discard certain text properties from the text that
+ is yanked, those that might lead to annoying results.  For instance,
+ they discard text properties that respond to the mouse or specify key
+ bindings.  The variable @code{yank-excluded-properties} specifies the
+ properties to discard.  Yanking of register contents and rectangles
+ also discard these properties.
+ 
+ @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 address@hidden M-d
+ address@hidden, 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 between @samp{is}
+ and @samp{text}, which you can clean up with @address@hidden 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 address@hidden 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 address@hidden
+ 
+   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} loops back around 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 from
+ the specified kill ring entry, counting back from the most recent as
+ 1.  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 the contents of a specified buffer.
+ @item M-x prepend-to-buffer
+ Prepend region to the contents of a specified buffer.
+ @item M-x copy-to-buffer
+ Copy region into a specified buffer, deleting that buffer's old contents.
+ @item M-x insert-buffer
+ Insert the contents of a specified buffer into current buffer at point.
+ @item M-x append-to-file
+ Append region to the contents of a 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,
+ starting from wherever point happens to be at that moment.
+ 
+   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 whole text in buffer
+ @var{buffername} into the current buffer at point, and sets the mark
+ after the inserted text.  Alternatively, you can select the other
+ buffer for editing, then copy 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 much the same way as 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 C-x r c
+ Clear the region-rectangle by replacing its contents with spaces
+ (@code{clear-rectangle}).
+ @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 @var{string} @key{RET}
+ Replace rectangle contents with @var{string} on each line.
+ (@code{string-rectangle}).
+ @item M-x string-insert-rectangle @key{RET} @var{string} @key{RET}
+ Insert @var{string} on each line of the rectangle.
+ @end table
+ 
+   The rectangle operations fall into two classes: commands for
+ 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 any following text 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 the same horizontal position, but 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
+ @kindex C-x r c
+ @findex clear-rectangle
+   There are two commands you can use for making blank rectangles:
+ @kbd{C-x r c} (@code{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{string-rectangle}) replaces the
+ contents of a region-rectangle with a string 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.
+ 
+ @findex string-insert-rectangle
+   The command @kbd{M-x string-insert-rectangle} is similar to
+ @code{string-rectangle}, but inserts the string on each line,
+ shifting the original text to the right.
+ 
+ @ifnottex
+ @lowersections
+ @end ifnottex
+ 
+ @ignore
+    arch-tag: d8da8f96-0928-449a-816e-ff2d3497866c
+ @end ignore