root/branches/2.1/info/emacs-5

This is ../info/emacs, produced by makeinfo version 4.3 from emacs.texi.

   This is the Fourteenth edition of the `GNU Emacs Manual', updated
for Emacs version 21.3.

INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* Emacs: (emacs).       The extensible self-documenting text editor.
END-INFO-DIR-ENTRY

   Published by the Free Software Foundation 59 Temple Place, Suite 330
Boston, MA  02111-1307 USA

   Copyright (C)
1985,1986,1987,1993,1994,1995,1996,1997,1998,1999,2000,2001,2002
Free Software Foundation, Inc.

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "The GNU Manifesto", "Distribution" and "GNU
GENERAL PUBLIC LICENSE", with the Front-Cover texts being "A GNU
Manual," and with the Back-Cover Texts as in (a) below.  A copy of the
license is included in the section entitled "GNU Free Documentation
License."

   (a) The FSF's Back-Cover Text is: "You have freedom to copy and
modify this GNU Manual, like GNU software.  Copies published by the Free
Software Foundation raise funds for GNU development."


File: emacs,  Node: Library Keywords,  Next: Language Help,  Prev: Apropos,  Up: Help

Keyword Search for Lisp Libraries
=================================

   The `C-h p' command lets you search the standard Emacs Lisp
libraries by topic keywords.  Here is a partial list of keywords you can
use:

     abbrev --- abbreviation handling, typing shortcuts, macros.
     bib --- support for the bibliography processor `bib'.
     c --- C and C++ language support.
     calendar --- calendar and time management support.
     comm --- communications, networking, remote access to files.
     data --- support for editing files of data.
     docs --- support for Emacs documentation.
     emulations --- emulations of other editors.
     extensions --- Emacs Lisp language extensions.
     faces --- support for using faces (fonts and colors; *note Faces::).
     frames --- support for Emacs frames and window systems.
     games --- games, jokes and amusements.
     hardware --- support for interfacing with exotic hardware.
     help --- support for on-line help systems.
     hypermedia --- support for links within text, or other media types.
     i18n --- internationalization and alternate character-set support.
     internal --- code for Emacs internals, build process, defaults.
     languages --- specialized modes for editing programming languages.
     lisp --- support for using Lisp (including Emacs Lisp).
     local --- libraries local to your site.
     maint --- maintenance aids for the Emacs development group.
     mail --- modes for electronic-mail handling.
     matching --- searching and matching.
     news --- support for netnews reading and posting.
     non-text --- support for editing files that are not ordinary text.
     oop --- support for object-oriented programming.
     outlines --- hierarchical outlining.
     processes --- process, subshell, compilation, and job control support.
     terminals --- support for terminal types.
     tex --- support for the TeX formatter.
     tools --- programming tools.
     unix --- front-ends/assistants for, or emulators of, system features.
     vms --- support code for VMS.
     wp --- word processing.


File: emacs,  Node: Language Help,  Next: Help Mode,  Prev: Library Keywords,  Up: Help

Help for International Language Support
=======================================

   You can use the command `C-h L' (`describe-language-environment') to
find out information about the support for a specific language
environment.  *Note Language Environments::.  This tells you which
languages this language environment is useful for, and lists the
character sets, coding systems, and input methods that go with it.  It
also shows some sample text to illustrate scripts.

   The command `C-h h' (`view-hello-file') displays the file
`etc/HELLO', which shows how to say "hello" in many languages.

   The command `C-h I' (`describe-input-method') describes information
about input methods--either a specified input method, or by default the
input method in use.  *Note Input Methods::.

   The command `C-h C' (`describe-coding-system') describes information
about coding systems--either a specified coding system, or the ones
currently in use.  *Note Coding Systems::.


File: emacs,  Node: Help Mode,  Next: Misc Help,  Prev: Language Help,  Up: Help

Help Mode Commands
==================

   Help buffers provide the same commands as View mode (*note Misc File
Ops::), plus a few special commands of their own.

`<SPC>'
     Scroll forward.

`<DEL>'
`<BS>'
     Scroll backward.  On some keyboards, this key is known as <BS> or
     <backspace>.

`<RET>'
     Follow a cross reference at point.

`<TAB>'
     Move point forward to the next cross reference.

`S-<TAB>'
     Move point back to the previous cross reference.

`Mouse-2'
     Follow a cross reference that you click on.

   When a command name (*note Running Commands by Name: M-x.) or
variable name (*note Variables::) appears in the documentation, it
normally appears inside paired single-quotes.  You can click on the name
with `Mouse-2', or move point there and type <RET>, to view the
documentation of that command or variable.  Use `C-c C-b' to retrace
your steps.

   There are convenient commands for moving point to cross references in
the help text.  <TAB> (`help-next-ref') moves point down to the next
cross reference.  Use `S-<TAB>' to move point up to the previous cross
reference (`help-previous-ref').


File: emacs,  Node: Misc Help,  Next: Help Echo,  Prev: Help Mode,  Up: Help

Other Help Commands
===================

   `C-h i' (`info') runs the Info program, which is used for browsing
through structured documentation files.  The entire Emacs manual is
available within Info.  Eventually all the documentation of the GNU
system will be available.  Type `h' after entering Info to run a
tutorial on using Info.

   If you specify a numeric argument, `C-h i' prompts for the name of a
documentation file.  This way, you can browse a file which doesn't have
an entry in the top-level Info menu.  It is also handy when you need to
get to the documentation quickly, and you know the exact name of the
file.

   There are two special help commands for accessing Emacs documentation
through Info.  `C-h C-f FUNCTION <RET>' enters Info and goes straight
to the documentation of the Emacs function FUNCTION.  `C-h C-k KEY'
enters Info and goes straight to the documentation of the key KEY.
These two keys run the commands `Info-goto-emacs-command-node' and
`Info-goto-emacs-key-command-node'.  You can use `C-h C-k' to find the
documentation of a menu item: just select that menu item when `C-h C-k'
prompts for a key.

   `C-h C-f' and `C-h C-k' know about commands and keys described in
manuals other than the Emacs manual.  Thus, they make it easier to find
the documentation of commands and keys when you are not sure which
manual describes them, like when using some specialized mode.

   When editing a program, if you have an Info version of the manual for
the programming language, you can use the command `C-h C-i' to refer to
the manual documentation for a symbol (keyword, function or variable).
The details of how this command works depend on the major mode.

   If something surprising happens, and you are not sure what commands
you typed, use `C-h l' (`view-lossage').  `C-h l' displays the last 100
command characters you typed in.  If you see commands that you don't
know, you can use `C-h c' to find out what they do.

   Emacs has numerous major modes, each of which redefines a few keys
and makes a few other changes in how editing works.  `C-h m'
(`describe-mode') displays documentation on the current major mode,
which normally describes all the commands that are changed in this mode.

   `C-h b' (`describe-bindings') and `C-h s' (`describe-syntax')
present other information about the current Emacs mode.  `C-h b'
displays a list of all the key bindings now in effect, showing the
local bindings defined by the current minor modes first, then the local
bindings defined by the current major mode, and finally the global
bindings (*note Key Bindings::).  `C-h s' displays the contents of the
syntax table, with explanations of each character's syntax (*note
Syntax::).

   You can get a similar list for a particular prefix key by typing
`C-h' after the prefix key.  (There are a few prefix keys for which
this does not work--those that provide their own bindings for `C-h'.
One of these is <ESC>, because `<ESC> C-h' is actually `C-M-h', which
marks a defun.)

   The other `C-h' options display various files containing useful
information.  `C-h C-w' displays the full details on the complete
absence of warranty for GNU Emacs.  `C-h n' (`view-emacs-news')
displays the file `emacs/etc/NEWS', which contains documentation on
Emacs changes arranged chronologically.  `C-h F' (`view-emacs-FAQ')
displays the Emacs frequently-answered-questions list.  `C-h t'
(`help-with-tutorial') displays the learn-by-doing Emacs tutorial.
`C-h C-c' (`describe-copying') displays the file `emacs/etc/COPYING',
which tells you the conditions you must obey in distributing copies of
Emacs.  `C-h C-d' (`describe-distribution') displays the file
`emacs/etc/DISTRIB', which tells you how you can order a copy of the
latest version of Emacs.  `C-h C-p' (`describe-project') displays
general information about the GNU Project.  `C-h P'
(`view-emacs-problems') displays the file `emacs/etc/PROBLEMS', which
lists known problems with Emacs in various situations with solutions or
workarounds in many cases.


File: emacs,  Node: Help Echo,  Prev: Misc Help,  Up: Help

Help on Active Text and Tooltips
================================

   When a region of text is "active," so that you can select it with
the mouse or a key like `RET', it often has associated help text.
Areas of the mode line are examples.  This help will normally be shown
in the echo area when you move point into the active text.  In a window
system you can display the help text as a "tooltip" (sometimes known as
"balloon help").  *Note Tooltips::.


File: emacs,  Node: Mark,  Next: Killing,  Prev: Help,  Up: Top

The Mark and the Region
***********************

   Many Emacs commands operate on an arbitrary contiguous part of the
current buffer.  To specify the text for such a command to operate on,
you set "the mark" at one end of it, and move point to the other end.
The text between point and the mark is called "the region".  Emacs
highlights the region whenever there is one, if you enable Transient
Mark mode (*note Transient Mark::).

   Certain Emacs commands set the mark; other editing commands do not
affect it, so the mark remains where you set it last.  Each Emacs
buffer has its own mark, and setting the mark in one buffer has no
effect on other buffers' marks.  When you return to a buffer that was
current earlier, its mark is at the same place as before.

   The ends of the region are always point and the mark.  It doesn't
matter which of them was put in its current place first, or which one
comes earlier in the text--the region starts from point or the mark
(whichever comes first), and ends at point or the mark (whichever comes
last).  Every time you move point, or set the mark in a new place, the
region changes.

   Many commands that insert text, such as `C-y' (`yank') and `M-x
insert-buffer', position point and the mark at opposite ends of the
inserted text, so that the region consists of the text just inserted.

   Aside from delimiting the region, the mark is also useful for
remembering a spot that you may want to go back to.  To make this
feature more useful, each buffer remembers 16 previous locations of the
mark in the "mark ring".

* Menu:

* Setting Mark::        Commands to set the mark.
* Transient Mark::      How to make Emacs highlight the region--
                          when there is one.
* Using Region::        Summary of ways to operate on contents of the region.
* Marking Objects::     Commands to put region around textual units.
* Mark Ring::           Previous mark positions saved so you can go back there.
* Global Mark Ring::    Previous mark positions in various buffers.


File: emacs,  Node: Setting Mark,  Next: Transient Mark,  Up: Mark

Setting the Mark
================

   Here are some commands for setting the mark:

`C-<SPC>'
     Set the mark where point is (`set-mark-command').

`C-@'
     The same.

`C-x C-x'
     Interchange mark and point (`exchange-point-and-mark').

`Drag-Mouse-1'
     Set point and the mark around the text you drag across.

`Mouse-3'
     Set the mark where point is, then move point to where you click
     (`mouse-save-then-kill').

   For example, suppose you wish to convert part of the buffer to upper
case, using the `C-x C-u' (`upcase-region') command, which operates on
the text in the region.  You can first go to the beginning of the text
to be capitalized, type `C-<SPC>' to put the mark there, move to the
end, and then type `C-x C-u'.  Or, you can set the mark at the end of
the text, move to the beginning, and then type `C-x C-u'.

   The most common way to set the mark is with the `C-<SPC>' command
(`set-mark-command').  This sets the mark where point is.  Then you can
move point away, leaving the mark behind.

   There are two ways to set the mark with the mouse.  You can drag
mouse button one across a range of text; that puts point where you
release the mouse button, and sets the mark at the other end of that
range.  Or you can click mouse button three, which sets the mark at
point (like `C-<SPC>') and then moves point (like `Mouse-1').  Both of
these methods copy the region into the kill ring in addition to setting
the mark; that gives behavior consistent with other window-driven
applications, but if you don't want to modify the kill ring, you must
use keyboard commands to set the mark.  *Note Mouse Commands::.

   Ordinary terminals have only one cursor, so there is no way for Emacs
to show you where the mark is located.  You have to remember.  The usual
solution to this problem is to set the mark and then use it soon, before
you forget where it is.  Alternatively, you can see where the mark is
with the command `C-x C-x' (`exchange-point-and-mark') which puts the
mark where point was and point where the mark was.  The extent of the
region is unchanged, but the cursor and point are now at the previous
position of the mark.  In Transient Mark mode, this command reactivates
the mark.

   `C-x C-x' is also useful when you are satisfied with the position of
point but want to move the other end of the region (where the mark is);
do `C-x C-x' to put point at that end of the region, and then move it.
Using `C-x C-x' a second time, if necessary, puts the mark at the new
position with point back at its original position.

   For more facilities that allow you to go to previously set marks, see
*Note Mark Ring::.

   There is no such character as `C-<SPC>' in ASCII; when you type
<SPC> while holding down <CTRL>, what you get on most ordinary
terminals is the character `C-@'.  This key is actually bound to
`set-mark-command'.  But unless you are unlucky enough to have a
terminal where typing `C-<SPC>' does not produce `C-@', you might as
well think of this character as `C-<SPC>'.  Under X, `C-<SPC>' is
actually a distinct character, but its binding is still
`set-mark-command'.


File: emacs,  Node: Transient Mark,  Next: Using Region,  Prev: Setting Mark,  Up: Mark

Transient Mark Mode
===================

   On a terminal that supports colors, Emacs can highlight the current
region.  But normally it does not.  Why not?

   Highlighting the region whenever it exists would not be desirable in
Emacs, because once you have set a mark, there is _always_ a region (in
that buffer).  And highlighting the region all the time would be a
nuisance.  So normally Emacs highlights the region only immediately
after you have selected one with the mouse.

   You can turn on region highlighting by enabling Transient Mark mode.
This is a more rigid mode of operation in which the region "lasts" only
temporarily, so you must set up a region for each command that uses
one.  In Transient Mark mode, most of the time there is no region;
therefore, highlighting the region when it exists is useful and not
annoying.

   To enable Transient Mark mode, type `M-x transient-mark-mode'.  This
command toggles the mode, so you can repeat the command to turn off the
mode.

   Here are the details of Transient Mark mode:

   * To set the mark, type `C-<SPC>' (`set-mark-command').  This makes
     the mark active and thus begins highlighting of the region.  As
     you move point, you will see the highlighted region grow and
     shrink.

   * The mouse commands for specifying the mark also make it active.
     So do keyboard commands whose purpose is to specify a region,
     including `M-@', `C-M-@', `M-h', `C-M-h', `C-x C-p', and `C-x h'.

   * When the mark is active, you can execute commands that operate on
     the region, such as killing, indenting, or writing to a file.

   * Any change to the buffer, such as inserting or deleting a
     character, deactivates the mark.  This means any subsequent
     command that operates on a region will get an error and refuse to
     operate.  You can make the region active again by typing `C-x C-x'.

   * Commands like `M->' and `C-s', that "leave the mark behind" in
     addition to some other primary purpose, do not activate the new
     mark.  You can activate the new region by executing `C-x C-x'
     (`exchange-point-and-mark').

   * `C-s' when the mark is active does not alter the mark.

   * Quitting with `C-g' deactivates the mark.

   * Some commands operate on the region whenever it is active.  For
     instance, `C-x u' in Transient Mark mode operates on the region
     when there is a region.  Outside Transient Mark mode, you must type
     `C-u C-x u' if you want it to operate on the region.  *Note
     Undo::.   Other commands that act this way are identified in their
     own documentation.

   The highlighting of the region uses the `region' face; you can
customize the appearance of the highlighted region by changing this
face.  *Note Face Customization::.

   When multiple windows show the same buffer, they can have different
regions, because they can have different values of point (though they
all share one common mark position).  Ordinarily, only the selected
window highlights its region (*note Windows::).  However, if the
variable `highlight-nonselected-windows' is non-`nil', then each window
highlights its own region (provided that Transient Mark mode is enabled
and the mark in the window's buffer is active).

   When Transient Mark mode is not enabled, every command that sets the
mark also activates it, and nothing ever deactivates it.

   If the variable `mark-even-if-inactive' is non-`nil' in Transient
Mark mode, then commands can use the mark and the region even when it
is inactive.  Region highlighting appears and disappears just as it
normally does in Transient Mark mode, but the mark doesn't really go
away when the highlighting disappears.

   Transient Mark mode is also sometimes known as "Zmacs mode" because
the Zmacs editor on the MIT Lisp Machine handled the mark in a similar
way.


File: emacs,  Node: Using Region,  Next: Marking Objects,  Prev: Transient Mark,  Up: Mark

Operating on the Region
=======================

   Once you have a region and the mark is active, here are some of the
ways you can operate on the region:

   * Kill it with `C-w' (*note Killing::).

   * Save it in a register with `C-x r s' (*note Registers::).

   * Save it in a buffer or a file (*note Accumulating Text::).

   * Convert case with `C-x C-l' or `C-x C-u' (*note Case::).

   * Indent it with `C-x <TAB>' or `C-M-\' (*note Indentation::).

   * Fill it as text with `M-x fill-region' (*note Filling::).

   * Print hardcopy with `M-x print-region' (*note Hardcopy::).

   * Evaluate it as Lisp code with `M-x eval-region' (*note Lisp
     Eval::).

   Most commands that operate on the text in the region have the word
`region' in their names.


File: emacs,  Node: Marking Objects,  Next: Mark Ring,  Prev: Using Region,  Up: Mark

Commands to Mark Textual Objects
================================

   Here are the commands for placing point and the mark around a textual
object such as a word, list, paragraph or page.

`M-@'
     Set mark after end of next word (`mark-word').  This command and
     the following one do not move point.

`C-M-@'
     Set mark after end of following balanced expression (`mark-sexp').

`M-h'
     Put region around current paragraph (`mark-paragraph').

`C-M-h'
     Put region around current defun (`mark-defun').

`C-x h'
     Put region around the entire buffer (`mark-whole-buffer').

`C-x C-p'
     Put region around current page (`mark-page').

   `M-@' (`mark-word') puts the mark at the end of the next word, while
`C-M-@' (`mark-sexp') puts it at the end of the next balanced
expression (*note Expressions::).  These commands handle arguments just
like `M-f' and `C-M-f'.

   Other commands set both point and mark, to delimit an object in the
buffer.  For example, `M-h' (`mark-paragraph') moves point to the
beginning of the paragraph that surrounds or follows point, and puts
the mark at the end of that paragraph (*note Paragraphs::).  It prepares
the region so you can indent, case-convert, or kill a whole paragraph.

   `C-M-h' (`mark-defun') similarly puts point before, and the mark
after, the current (or following) major top-level definition, or defun
(*note Moving by Defuns::).  `C-x C-p' (`mark-page') puts point before
the current page, and mark at the end (*note Pages::).  The mark goes
after the terminating page delimiter (to include it in the region),
while point goes after the preceding page delimiter (to exclude it).  A
numeric argument specifies a later page (if positive) or an earlier
page (if negative) instead of the current page.

   Finally, `C-x h' (`mark-whole-buffer') sets up the entire buffer as
the region, by putting point at the beginning and the mark at the end.

   In Transient Mark mode, all of these commands activate the mark.


File: emacs,  Node: Mark Ring,  Next: Global Mark Ring,  Prev: Marking Objects,  Up: Mark

The Mark Ring
=============

   Aside from delimiting the region, the mark is also useful for
remembering a spot that you may want to go back to.  To make this
feature more useful, each buffer remembers 16 previous locations of the
mark, in the "mark ring".  Commands that set the mark also push the old
mark onto this ring.  To return to a marked location, use `C-u C-<SPC>'
(or `C-u C-@'); this is the command `set-mark-command' given a numeric
argument.  It moves point to where the mark was, and restores the mark
from the ring of former marks.  Thus, repeated use of this command
moves point to all of the old marks on the ring, one by one.  The mark
positions you move through in this way are not lost; they go to the end
of the ring.

   Each buffer has its own mark ring.  All editing commands use the
current buffer's mark ring.  In particular, `C-u C-<SPC>' always stays
in the same buffer.

   Many commands that can move long distances, such as `M-<'
(`beginning-of-buffer'), start by setting the mark and saving the old
mark on the mark ring.  This is to make it easier for you to move back
later.  Searches set the mark if they move point.  You can tell when a
command sets the mark because it displays `Mark set' in the echo area.

   If you want to move back to the same place over and over, the mark
ring may not be convenient enough.  If so, you can record the position
in a register for later retrieval (*note Saving Positions in Registers:
RegPos.).

   The variable `mark-ring-max' specifies the maximum number of entries
to keep in the mark ring.  If that many entries exist and another one
is pushed, the earliest one in the list is discarded.  Repeating `C-u
C-<SPC>' cycles through the positions currently in the ring.

   The variable `mark-ring' holds the mark ring itself, as a list of
marker objects, with the most recent first.  This variable is local in
every buffer.


File: emacs,  Node: Global Mark Ring,  Prev: Mark Ring,  Up: Mark

The Global Mark Ring
====================

   In addition to the ordinary mark ring that belongs to each buffer,
Emacs has a single "global mark ring".  It records a sequence of
buffers in which you have recently set the mark, so you can go back to
those buffers.

   Setting the mark always makes an entry on the current buffer's mark
ring.  If you have switched buffers since the previous mark setting, the
new mark position makes an entry on the global mark ring also.  The
result is that the global mark ring records a sequence of buffers that
you have been in, and, for each buffer, a place where you set the mark.

   The command `C-x C-<SPC>' (`pop-global-mark') jumps to the buffer
and position of the latest entry in the global ring.  It also rotates
the ring, so that successive uses of `C-x C-<SPC>' take you to earlier
and earlier buffers.


File: emacs,  Node: Killing,  Next: Yanking,  Prev: Mark,  Up: Top

Deletion and Killing
====================

   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 "kill" commands.  The rest of the commands
that erase text do not save it in the kill ring; they are known as
"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 `C-x u' (`undo') command to undo it (*note Undo::).

   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.
If you set the variable `kill-read-only-ok' to a non-`nil' value, 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.  When this happens, a message in the echo area tells you
what is happening.

   The delete commands include `C-d' (`delete-char') and <DEL>
(`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 `kill' and `delete' to say which kind of operation they
perform.

   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 `M-x
delete-selection-mode', or using Custom.  Another effect of this mode
is that <DEL>, `C-d' and some other keys, when a selection exists, will
kill the whole selection.  It also enables Transient Mark mode (*note
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.


File: emacs,  Node: Deletion,  Next: Killing by Lines,  Up: Killing

Deletion
--------

   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.

`C-d'
`<Delete>'
     Delete next character (`delete-char').  If your keyboard has a
     <Delete> function key (usually located in the edit keypad), Emacs
     binds it to `delete-char' as well.

`<DEL>'
`<BS>'
     Delete previous character (`delete-backward-char').  Some keyboards
     refer to this key as a "backspace key" and label it with a left
     arrow.

`M-\'
     Delete spaces and tabs around point (`delete-horizontal-space').

`M-<SPC>'
     Delete spaces and tabs around point, leaving one space
     (`just-one-space').

`C-x C-o'
     Delete blank lines around the current line (`delete-blank-lines').

`M-^'
     Join two lines by deleting the intervening newline, along with any
     indentation following it (`delete-indentation').

   The most basic delete commands are `C-d' (`delete-char') and <DEL>
(`delete-backward-char').  `C-d' deletes the character after point, the
one the cursor is "on top of."  This doesn't move point.  <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, `C-d' and <DEL> aren't always delete
commands; when given arguments, they kill instead, since they can erase
more than one character this way.

   Every keyboard has a large key, labeled <DEL>, <BACKSPACE>, <BS> or
<DELETE>, which is a short distance above the <RET> or <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 <DEL>--or it
should be.

   Many keyboards (including standard PC keyboards) have a <BACKSPACE>
key a short ways above <RET> or <ENTER>, and a <DELETE> key elsewhere.
In that case, the <BACKSPACE> key is <DEL>, and the <DELETE> key is
equivalent to `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 <DEL>.  As a result, <BACKSPACE> and/or <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 <DEL>.  *Note
DEL Does Not Delete::, for how to do this.

   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 ASCII <DEL> character
deletes, and the ASCII <BS> (backspace) character asks for help (it is
the same as `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 *Note DEL Does Not Delete::.

   The other delete commands are those which delete only whitespace
characters: spaces, tabs and newlines.  `M-\'
(`delete-horizontal-space') deletes all the spaces and tab characters
before and after point.  `M-<SPC>' (`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).

   `C-x C-o' (`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).

   `M-^' (`delete-indentation') joins the current line and the previous
line, by deleting a newline and all surrounding spaces, usually leaving
a single space.  *Note M-^: Indentation.


File: emacs,  Node: Killing by Lines,  Next: Other Kill Commands,  Prev: Deletion,  Up: Killing

Killing by Lines
----------------

`C-k'
     Kill rest of line or one or more lines (`kill-line').

   The simplest kill command is `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 `C-k' twice.

   More generally, `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 `C-k' will kill the newline.

   When `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 -N, it kills N
lines preceding the current line (together with the text on the current
line before point).  Thus, `C-u - 2 C-k' at the front of a line kills
the two previous lines.

   `C-k' with an argument of zero kills the text before point on the
current line.

   If the variable `kill-whole-line' is non-`nil', `C-k' at the very
beginning of a line kills the entire line including the following
newline.  This variable is normally `nil'.


File: emacs,  Node: Other Kill Commands,  Prev: Killing by Lines,  Up: Killing

Other Kill Commands
-------------------

`C-w'
     Kill region (from point to the mark) (`kill-region').

`M-d'
     Kill word (`kill-word').  *Note Words::.

`M-<DEL>'
     Kill word backwards (`backward-kill-word').

`C-x <DEL>'
     Kill back to beginning of sentence (`backward-kill-sentence').
     *Note Sentences::.

`M-k'
     Kill to end of sentence (`kill-sentence').

`C-M-k'
     Kill the following balanced expression (`kill-sexp').  *Note
     Expressions::.

`M-z CHAR'
     Kill through the next occurrence of CHAR (`zap-to-char').

   A kill command which is very general is `C-w' (`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.

   A convenient way of killing is combined with searching: `M-z'
(`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 `M-<DEL>' and `M-d'
(*note Words::); balanced expressions, with `C-M-k' (*note
Expressions::); and sentences, with `C-x <DEL>' and `M-k' (*note
Sentences::).

   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.


File: emacs,  Node: Yanking,  Next: Accumulating Text,  Prev: Killing,  Up: Top

Yanking
=======

   "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.

`C-y'
     Yank last killed text (`yank').

`M-y'
     Replace text just yanked with an earlier batch of killed text
     (`yank-pop').

`M-w'
     Save region as last killed text without actually killing it
     (`kill-ring-save').

`C-M-w'
     Append next kill to last batch of killed text (`append-next-kill').

* 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.


File: emacs,  Node: Kill Ring,  Next: Appending Kills,  Up: Yanking

The Kill Ring
-------------

   All killed text is recorded in the "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.
(*Note Accumulating Text::, for some other ways.)

   The command `C-y' (`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.  *Note Mark::.

   `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
`C-u', precisely.  Any other sort of argument, including `C-u' and
digits, specifies an earlier kill to yank (*note Earlier Kills::).

   To copy a block of text, you can use `M-w' (`kill-ring-save'), which
copies the region into the kill ring without removing it from the
buffer.  This is approximately equivalent to `C-w' followed by `C-x u',
except that `M-w' does not alter the undo history and does not
temporarily change the screen.


File: emacs,  Node: Appending Kills,  Next: Earlier Kills,  Prev: Kill Ring,  Up: Yanking

Appending Kills
---------------

   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 `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:

     This is a line -!-of sample text.

with point shown by -!-.  If you type `M-d M-<DEL> M-d M-<DEL>',
killing alternately forward and backward, you end up with `a line of
sample' as one entry in the kill ring, and `This is  text.' in the
buffer.  (Note the double space between `is' and `text', which you can
clean up with `M-<SPC>' or `M-q'.)

   Another way to kill the same text is to move back two words with
`M-b M-b', then kill all four words forward with `C-u M-d'.  This
produces exactly the same results in the buffer and in the kill ring.
`M-f M-f C-u M-<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.

   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
`C-M-w' (`append-next-kill') right before it.  The `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
`C-M-w', you can kill several separated pieces of text and accumulate
them to be yanked back in one place.

   A kill command following `M-w' does not append to the text that
`M-w' copied into the kill ring.


File: emacs,  Node: Earlier Kills,  Prev: Appending Kills,  Up: Yanking

Yanking Earlier Kills
---------------------

   To recover killed text that is no longer the most recent kill, use
the `M-y' command (`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 `C-y' to yank the last
kill, and then use `M-y' to replace it with the previous kill.  `M-y'
is allowed only after a `C-y' or another `M-y'.

   You can understand `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.
`C-y' yanks the entry which the "last yank" pointer points to.  `M-y'
moves the "last yank" pointer to a different entry, and the text in the
buffer changes to match.  Enough `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 `M-y'
loops back around to the first entry again.

   `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.

   `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 `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 `C-y'
will yank another copy of the same previous kill.

   If you know how many `M-y' commands it would take to find the text
you want, you can yank that text in one step using `C-y' with a numeric
argument.  `C-y' with an argument restores the text from the specified
kill ring entry, counting back from the most recent as 1.  Thus, `C-u 2
C-y' gets the next-to-the-last block of killed text--it is equivalent
to `C-y M-y'.  `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.

   The length of the kill ring is controlled by the variable
`kill-ring-max'; no more than that many blocks of killed text are saved.

   The actual contents of the kill ring are stored in a variable named
`kill-ring'; you can view the entire contents of the kill ring with the
command `C-h v kill-ring'.


File: emacs,  Node: Accumulating Text,  Next: Rectangles,  Prev: Yanking,  Up: Top

Accumulating 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 (*note
Registers::).  Here we describe the commands to accumulate scattered
pieces of text into a buffer or into a file.

`M-x append-to-buffer'
     Append region to the contents of a specified buffer.

`M-x prepend-to-buffer'
     Prepend region to the contents of a specified buffer.

`M-x copy-to-buffer'
     Copy region into a specified buffer, deleting that buffer's old
     contents.

`M-x insert-buffer'
     Insert the contents of a specified buffer into current buffer at
     point.

`M-x append-to-file'
     Append region to the contents of a specified file, at the end.

   To accumulate text into a buffer, use `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, `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 `append-to-buffer' accumulate the text in the
specified buffer in the same order as they were copied.  Strictly
speaking, `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 `append-to-buffer' is the only command you use to alter a
buffer, then point is always at the end.

   `M-x prepend-to-buffer' is just like `append-to-buffer' except that
point in the other buffer is left before the copied text, so successive
prependings add text in reverse order.  `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 `M-x insert-buffer'; this too takes BUFFERNAME as an argument.
It inserts a copy of the whole text in buffer 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.  *Note Buffers::, for background information
on buffers.

   Instead of accumulating text within Emacs, in a buffer, you can
append text directly into a file with `M-x append-to-file', which takes
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 `append-to-file' only with files that are _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.


File: emacs,  Node: Rectangles,  Next: Registers,  Prev: Accumulating Text,  Up: Top

Rectangles
==========

   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 "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.

`C-x r k'
     Kill the text of the region-rectangle, saving its contents as the
     "last killed rectangle" (`kill-rectangle').

`C-x r d'
     Delete the text of the region-rectangle (`delete-rectangle').

`C-x r y'
     Yank the last killed rectangle with its upper left corner at point
     (`yank-rectangle').

`C-x r o'
     Insert blank space to fill the space of the region-rectangle
     (`open-rectangle').  This pushes the previous contents of the
     region-rectangle rightward.

`M-x clear-rectangle'
     Clear the region-rectangle by replacing its contents with spaces.

`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.

`C-x r t STRING <RET>'
     Replace rectangle contents with STRING on each line.
     (`string-rectangle').

`M-x string-insert-rectangle <RET> STRING <RET>'
     Insert STRING on each line of the rectangle.

   The rectangle operations fall into two classes: commands for
deleting and inserting rectangles, and commands for blank rectangles.

   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 `C-x r d' (`delete-rectangle') and
`C-x r k' (`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.

   To yank the last killed rectangle, type `C-x r y'
(`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.  *Note
Two-Column::, for another way to edit multi-column text.

   You can also copy rectangles into and out of registers with `C-x r r
R' and `C-x r i R'.  *Note Rectangle Registers: RegRect.

   There are two commands you can use for making blank rectangles: `M-x
clear-rectangle' which blanks out existing text, and `C-x r o'
(`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.

   The command `M-x delete-whitespace-rectangle' deletes horizontal
whi