This is ../info/emacs, produced by makeinfo version 4.0 from emacs.texi.
This is the thirteenth edition of the `GNU Emacs Manual', updated
for Emacs version 20.7.
INFO-DIR-SECTION Editors
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 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
General Public License" are included exactly as in the original, and
provided that the entire resulting derived work is distributed under the
terms of a permission notice identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the sections entitled "The GNU Manifesto",
"Distribution" and "GNU General Public License" may be included in a
translation approved by the Free Software Foundation instead of in the
original English.
File: emacs, Node: Entering Emacs, Next: Exiting, Prev: Text Characters, Up: Top
Entering and Exiting Emacs
**************************
The usual way to invoke Emacs is with the shell command `emacs'.
Emacs clears the screen and then displays an initial help message and
copyright notice. Some operating systems discard all type-ahead when
Emacs starts up; they give Emacs no way to prevent this. Therefore, it
is advisable to wait until Emacs clears the screen before typing your
first editing command.
If you run Emacs from a shell window under the X Window System, run
it in the background with `emacs&'. This way, Emacs does not tie up
the shell window, so you can use that to run other shell commands while
Emacs operates its own X windows. You can begin typing Emacs commands
as soon as you direct your keyboard input to the Emacs frame.
When Emacs starts up, it makes a buffer named `*scratch*'. That's
the buffer you start out in. The `*scratch*' buffer uses Lisp
Interaction mode; you can use it to type Lisp expressions and evaluate
them, or you can ignore that capability and simply doodle. (You can
specify a different major mode for this buffer by setting the variable
`initial-major-mode' in your init file. *Note Init File::.)
It is possible to specify files to be visited, Lisp files to be
loaded, and functions to be called, by giving Emacs arguments in the
shell command line. *Note Command Arguments::. But we don't recommend
doing this. The feature exists mainly for compatibility with other
editors.
Many other editors are designed to be started afresh each time you
want to edit. You edit one file and then exit the editor. The next
time you want to edit either another file or the same one, you must run
the editor again. With these editors, it makes sense to use a
command-line argument to say which file to edit.
But starting a new Emacs each time you want to edit a different file
does not make sense. For one thing, this would be annoyingly slow. For
another, this would fail to take advantage of Emacs's ability to visit
more than one file in a single editing session. And it would lose the
other accumulated context, such as registers, undo history, and the mark
ring.
The recommended way to use GNU Emacs is to start it only once, just
after you log in, and do all your editing in the same Emacs session.
Each time you want to edit a different file, you visit it with the
existing Emacs, which eventually comes to have many files in it ready
for editing. Usually you do not kill the Emacs until you are about to
log out. *Note Files::, for more information on visiting more than one
file.
File: emacs, Node: Exiting, Next: Basic, Prev: Entering Emacs, Up: Top
Exiting Emacs
=============
There are two commands for exiting Emacs because there are two kinds
of exiting: "suspending" Emacs and "killing" Emacs.
"Suspending" means stopping Emacs temporarily and returning control
to its parent process (usually a shell), allowing you to resume editing
later in the same Emacs job, with the same buffers, same kill ring,
same undo history, and so on. This is the usual way to exit.
"Killing" Emacs means destroying the Emacs job. You can run Emacs
again later, but you will get a fresh Emacs; there is no way to resume
the same editing session after it has been killed.
`C-z'
Suspend Emacs (`suspend-emacs') or iconify a frame
(`iconify-or-deiconify-frame').
`C-x C-c'
Kill Emacs (`save-buffers-kill-emacs').
To suspend Emacs, type `C-z' (`suspend-emacs'). This takes you back
to the shell from which you invoked Emacs. You can resume Emacs with
the shell command `%emacs' in most common shells.
On systems that do not support suspending programs, `C-z' starts an
inferior shell that communicates directly with the terminal. Emacs
waits until you exit the subshell. (The way to do that is probably
with `C-d' or `exit', but it depends on which shell you use.) The only
way on these systems to get back to the shell from which Emacs was run
(to log out, for example) is to kill Emacs.
Suspending also fails if you run Emacs under a shell that doesn't
support suspending programs, even if the system itself does support it.
In such a case, you can set the variable `cannot-suspend' to a
non-`nil' value to force `C-z' to start an inferior shell. (One might
also describe Emacs's parent shell as "inferior" for failing to support
job control properly, but that is a matter of taste.)
When Emacs communicates directly with an X server and creates its own
dedicated X windows, `C-z' has a different meaning. Suspending an
applications that uses its own X windows is not meaningful or useful.
Instead, `C-z' runs the command `iconify-or-deiconify-frame', which
temporarily closes up the selected Emacs frame (*note Frames::). The
way to get back to a shell window is with the window manager.
To kill Emacs, type `C-x C-c' (`save-buffers-kill-emacs'). A
two-character key is used for this to make it harder to type. This
command first offers to save any modified file-visiting buffers. If you
do not save them all, it asks for reconfirmation with `yes' before
killing Emacs, since any changes not saved will be lost forever. Also,
if any subprocesses are still running, `C-x C-c' asks for confirmation
about them, since killing Emacs will kill the subprocesses immediately.
There is no way to restart an Emacs session once you have killed it.
You can, however, arrange for Emacs to record certain session
information, such as which files are visited, when you kill it, so that
the next time you restart Emacs it will try to visit the same files and
so on. *Note Saving Emacs Sessions::.
The operating system usually listens for certain special characters
whose meaning is to kill or suspend the program you are running. This
operating system feature is turned off while you are in Emacs. The
meanings of `C-z' and `C-x C-c' as keys in Emacs were inspired by the
use of `C-z' and `C-c' on several operating systems as the characters
for stopping or killing a program, but that is their only relationship
with the operating system. You can customize these keys to run any
commands of your choice (*note Keymaps::).
File: emacs, Node: Basic, Next: Minibuffer, Prev: Exiting, Up: Top
Basic Editing Commands
**********************
We now give the basics of how to enter text, make corrections, and
save the text in a file. If this material is new to you, you might
learn it more easily by running the Emacs learn-by-doing tutorial. To
use the tutorial, run Emacs and type `Control-h t'
(`help-with-tutorial').
To clear the screen and redisplay, type `C-l' (`recenter').
* Menu:
* Inserting Text:: Inserting text by simply typing it.
* Moving Point:: How to move the cursor to the place where you want to
change something.
* Erasing:: Deleting and killing text.
* Undo:: Undoing recent changes in the text.
* Files: Basic Files. Visiting, creating, and saving files.
* Help: Basic Help. Asking what a character does.
* Blank Lines:: Commands to make or delete blank lines.
* Continuation Lines:: Lines too wide for the screen.
* Position Info:: What page, line, row, or column is point on?
* Arguments:: Numeric arguments for repeating a command.
* Repeating:: A short-cut for repeating the previous command.
File: emacs, Node: Inserting Text, Next: Moving Point, Up: Basic
Inserting Text
==============
To insert printing characters into the text you are editing, just
type them. This inserts the characters you type into the buffer at the
cursor (that is, at "point"; *note Point::). The cursor moves forward,
and any text after the cursor moves forward too. If the text in the
buffer is `FOOBAR', with the cursor before the `B', then if you type
`XX', you get `FOOXXBAR', with the cursor still before the `B'.
To "delete" text you have just inserted, use <DEL>. <DEL> deletes
the character _before_ the cursor (not the one that the cursor is on
top of or under; that is the character AFTER the cursor). The cursor
and all characters after it move backwards. Therefore, if you type a
printing character and then type <DEL>, they cancel out.
To end a line and start typing a new one, type <RET>. This inserts
a newline character in the buffer. If point is in the middle of a
line, <RET> splits the line. Typing <DEL> when the cursor is at the
beginning of a line deletes the preceding newline, thus joining the
line with the preceding line.
Emacs can split lines automatically when they become too long, if you
turn on a special minor mode called "Auto Fill" mode. *Note Filling::,
for how to use Auto Fill mode.
If you prefer to have text characters replace (overwrite) existing
text rather than shove it to the right, you can enable Overwrite mode,
a minor mode. *Note Minor Modes::.
Direct insertion works for printing characters and <SPC>, but other
characters act as editing commands and do not insert themselves. If you
need to insert a control character or a character whose code is above
200 octal, you must "quote" it by typing the character `Control-q'
(`quoted-insert') first. (This character's name is normally written
`C-q' for short.) There are two ways to use `C-q':
* `C-q' followed by any non-graphic character (even `C-g') inserts
that character.
* `C-q' followed by a sequence of octal digits inserts the character
with the specified octal character code. You can use any number of
octal digits; any non-digit terminates the sequence. If the
terminating character is <RET>, it serves only to terminate the
sequence; any other non-digit is itself used as input after
terminating the sequence. (The use of octal sequences is disabled
in ordinary non-binary Overwrite mode, to give you a convenient
way to insert a digit instead of overwriting with it.)
When multibyte characters are enabled, octal codes 0200 through 0377 are
not valid as characters; if you specify a code in this range, `C-q'
assumes that you intend to use some ISO Latin-N character set, and
converts the specified code to the corresponding Emacs character code.
*Note Enabling Multibyte::. You select _which_ ISO Latin character set
though your choice of language environment (*note Language
Environments::).
To use decimal or hexadecimal instead of octal, set the variable
`read-quoted-char-radix' to 10 or 16. If the radix is greater than 10,
some letters starting with `a' serve as part of a character code, just
like digits.
A numeric argument to `C-q' specifies how many copies of the quoted
character should be inserted (*note Arguments::).
Customization information: <DEL> in most modes runs the command
`delete-backward-char'; <RET> runs the command `newline', and
self-inserting printing characters run the command `self-insert', which
inserts whatever character was typed to invoke it. Some major modes
rebind <DEL> to other commands.
File: emacs, Node: Moving Point, Next: Erasing, Prev: Inserting Text, Up: Basic
Changing the Location of Point
==============================
To do more than insert characters, you have to know how to move point
(*note Point::). The simplest way to do this is with arrow keys, or by
clicking the left mouse button where you want to move to.
There are also control and meta characters for cursor motion. Some
are equivalent to the arrow keys (these date back to the days before
terminals had arrow keys, and are usable on terminals which don't have
them). Others do more sophisticated things.
`C-a'
Move to the beginning of the line (`beginning-of-line').
`C-e'
Move to the end of the line (`end-of-line').
`C-f'
Move forward one character (`forward-char').
`C-b'
Move backward one character (`backward-char').
`M-f'
Move forward one word (`forward-word').
`M-b'
Move backward one word (`backward-word').
`C-n'
Move down one line, vertically (`next-line'). This command
attempts to keep the horizontal position unchanged, so if you
start in the middle of one line, you end in the middle of the
next. When on the last line of text, `C-n' creates a new line and
moves onto it.
`C-p'
Move up one line, vertically (`previous-line').
`M-r'
Move point to left margin, vertically centered in the window
(`move-to-window-line'). Text does not move on the screen.
A numeric argument says which screen line to place point on. It
counts screen lines down from the top of the window (zero for the
top line). A negative argument counts lines from the bottom (-1
for the bottom line).
`M-<'
Move to the top of the buffer (`beginning-of-buffer'). With
numeric argument N, move to N/10 of the way from the top. *Note
Arguments::, for more information on numeric arguments.
`M->'
Move to the end of the buffer (`end-of-buffer').
`M-x goto-char'
Read a number N and move point to buffer position N. Position 1
is the beginning of the buffer.
`M-x goto-line'
Read a number N and move point to line number N. Line 1 is the
beginning of the buffer.
`C-x C-n'
Use the current column of point as the "semipermanent goal column"
for `C-n' and `C-p' (`set-goal-column'). Henceforth, those
commands always move to this column in each line moved into, or as
close as possible given the contents of the line. This goal
column remains in effect until canceled.
`C-u C-x C-n'
Cancel the goal column. Henceforth, `C-n' and `C-p' once again
try to stick to a fixed horizontal position, as usual.
If you set the variable `track-eol' to a non-`nil' value, then `C-n'
and `C-p' when at the end of the starting line move to the end of
another line. Normally, `track-eol' is `nil'. *Note Variables::, for
how to set variables such as `track-eol'.
Normally, `C-n' on the last line of a buffer appends a newline to
it. If the variable `next-line-add-newlines' is `nil', then `C-n' gets
an error instead (like `C-p' on the first line).
File: emacs, Node: Erasing, Next: Undo, Prev: Moving Point, Up: Basic
Erasing Text
============
`<DEL>'
Delete the character before point (`delete-backward-char').
`C-d'
Delete the character after point (`delete-char').
`C-k'
Kill to the end of the line (`kill-line').
`M-d'
Kill forward to the end of the next word (`kill-word').
`M-<DEL>'
Kill back to the beginning of the previous word
(`backward-kill-word').
You already know about the <DEL> key which deletes the character
before point (that is, before the cursor). Another key, `Control-d'
(`C-d' for short), deletes the character after point (that is, the
character that the cursor is on). This shifts the rest of the text on
the line to the left. If you type `C-d' at the end of a line, it joins
together that line and the next line.
To erase a larger amount of text, use the `C-k' key, which kills a
line at a time. If you type `C-k' at the beginning or middle of a
line, it kills all the text up to the end of the line. If you type
`C-k' at the end of a line, it joins that line and the next line.
*Note Killing::, for more flexible ways of killing text.
File: emacs, Node: Undo, Next: Basic Files, Prev: Erasing, Up: Basic
Undoing Changes
===============
You can undo all the recent changes in the buffer text, up to a
certain point. Each buffer records changes individually, and the undo
command always applies to the current buffer. Usually each editing
command makes a separate entry in the undo records, but some commands
such as `query-replace' make many entries, and very simple commands
such as self-inserting characters are often grouped to make undoing less
tedious.
`C-x u'
Undo one batch of changes--usually, one command worth (`undo').
`C-_'
The same.
`C-u C-x u'
Undo one batch of changes in the region.
The command `C-x u' or `C-_' is how you undo. The first time you
give this command, it undoes the last change. Point moves back to
where it was before the command that made the change.
Consecutive repetitions of `C-_' or `C-x u' undo earlier and earlier
changes, back to the limit of the undo information available. If all
recorded changes have already been undone, the undo command prints an
error message and does nothing.
Any command other than an undo command breaks the sequence of undo
commands. Starting from that moment, the previous undo commands become
ordinary changes that you can undo. Thus, to redo changes you have
undone, type `C-f' or any other command that will harmlessly break the
sequence of undoing, then type more undo commands.
Ordinary undo applies to all changes made in the current buffer. You
can also perform "selective undo", limited to the current region. To
do this, specify the region you want, then run the `undo' command with
a prefix argument (the value does not matter): `C-u C-x u' or `C-u
C-_'. This undoes the most recent change in the region. To undo
further changes in the same region, repeat the `undo' command (no
prefix argument is needed). In Transient Mark mode, any use of `undo'
when there is an active region performs selective undo; you do not need
a prefix argument.
If you notice that a buffer has been modified accidentally, the
easiest way to recover is to type `C-_' repeatedly until the stars
disappear from the front of the mode line. At this time, all the
modifications you made have been canceled. Whenever an undo command
makes the stars disappear from the mode line, it means that the buffer
contents are the same as they were when the file was last read in or
saved.
If you do not remember whether you changed the buffer deliberately,
type `C-_' once. When you see the last change you made undone, you
will see whether it was an intentional change. If it was an accident,
leave it undone. If it was deliberate, redo the change as described
above.
Not all buffers record undo information. Buffers whose names start
with spaces don't; these buffers are used internally by Emacs and its
extensions to hold text that users don't normally look at or edit.
You cannot undo mere cursor motion; only changes in the buffer
contents save undo information. However, some cursor motion commands
set the mark, so if you use these commands from time to time, you can
move back to the neighborhoods you have moved through by popping the
mark ring (*note Mark Ring::).
When the undo information for a buffer becomes too large, Emacs
discards the oldest undo information from time to time (during garbage
collection). You can specify how much undo information to keep by
setting two variables: `undo-limit' and `undo-strong-limit'. Their
values are expressed in units of bytes of space.
The variable `undo-limit' sets a soft limit: Emacs keeps undo data
for enough commands to reach this size, and perhaps exceed it, but does
not keep data for any earlier commands beyond that. Its default value
is 20000. The variable `undo-strong-limit' sets a stricter limit: the
command which pushes the size past this amount is itself forgotten.
Its default value is 30000.
Regardless of the values of those variables, the most recent change
is never discarded, so there is no danger that garbage collection
occurring right after an unintentional large change might prevent you
from undoing it.
The reason the `undo' command has two keys, `C-x u' and `C-_', set
up to run it is that it is worthy of a single-character key, but on
some keyboards it is not obvious how to type `C-_'. `C-x u' is an
alternative you can type straightforwardly on any terminal.
File: emacs, Node: Basic Files, Next: Basic Help, Prev: Undo, Up: Basic
Files
=====
The commands described above are sufficient for creating and altering
text in an Emacs buffer; the more advanced Emacs commands just make
things easier. But to keep any text permanently you must put it in a
"file". Files are named units of text which are stored by the
operating system for you to retrieve later by name. To look at or use
the contents of a file in any way, including editing the file with
Emacs, you must specify the file name.
Consider a file named `/usr/rms/foo.c'. In Emacs, to begin editing
this file, type
C-x C-f /usr/rms/foo.c <RET>
Here the file name is given as an "argument" to the command `C-x C-f'
(`find-file'). That command uses the "minibuffer" to read the
argument, and you type <RET> to terminate the argument (*note
Minibuffer::).
Emacs obeys the command by "visiting" the file: creating a buffer,
copying the contents of the file into the buffer, and then displaying
the buffer for you to edit. If you alter the text, you can "save" the
new text in the file by typing `C-x C-s' (`save-buffer'). This makes
the changes permanent by copying the altered buffer contents back into
the file `/usr/rms/foo.c'. Until you save, the changes exist only
inside Emacs, and the file `foo.c' is unaltered.
To create a file, just visit the file with `C-x C-f' as if it
already existed. This creates an empty buffer in which you can insert
the text you want to put in the file. The file is actually created when
you save this buffer with `C-x C-s'.
Of course, there is a lot more to learn about using files. *Note
Files::.
File: emacs, Node: Basic Help, Next: Blank Lines, Prev: Basic Files, Up: Basic
Help
====
If you forget what a key does, you can find out with the Help
character, which is `C-h' (or <F1>, which is an alias for `C-h'). Type
`C-h k' followed by the key you want to know about; for example, `C-h k
C-n' tells you all about what `C-n' does. `C-h' is a prefix key; `C-h
k' is just one of its subcommands (the command `describe-key'). The
other subcommands of `C-h' provide different kinds of help. Type `C-h'
twice to get a description of all the help facilities. *Note Help::.
File: emacs, Node: Blank Lines, Next: Continuation Lines, Prev: Basic Help, Up: Basic
Blank Lines
===========
Here are special commands and techniques for putting in and taking
out blank lines.
`C-o'
Insert one or more blank lines after the cursor (`open-line').
`C-x C-o'
Delete all but one of many consecutive blank lines
(`delete-blank-lines').
When you want to insert a new line of text before an existing line,
you can do it by typing the new line of text, followed by <RET>.
However, it may be easier to see what you are doing if you first make a
blank line and then insert the desired text into it. This is easy to do
using the key `C-o' (`open-line'), which inserts a newline after point
but leaves point in front of the newline. After `C-o', type the text
for the new line. `C-o F O O' has the same effect as `F O O <RET>',
except for the final location of point.
You can make several blank lines by typing `C-o' several times, or
by giving it a numeric argument to tell it how many blank lines to make.
*Note Arguments::, for how. If you have a fill prefix, then `C-o'
command inserts the fill prefix on the new line, when you use it at the
beginning of a line. *Note Fill Prefix::.
The easy way to get rid of extra blank lines is with the command
`C-x C-o' (`delete-blank-lines'). `C-x C-o' in a run of several blank
lines deletes all but one of them. `C-x C-o' on a solitary blank line
deletes that blank line. When point is on a nonblank line, `C-x C-o'
deletes any blank lines following that nonblank line.
File: emacs, Node: Continuation Lines, Next: Position Info, Prev: Blank Lines, Up: Basic
Continuation Lines
==================
If you add too many characters to one line without breaking it with
<RET>, the line will grow to occupy two (or more) lines on the screen,
with a `\' at the extreme right margin of all but the last of them.
The `\' says that the following screen line is not really a distinct
line in the text, but just the "continuation" of a line too long to fit
the screen. Continuation is also called "line wrapping".
Sometimes it is nice to have Emacs insert newlines automatically when
a line gets too long. Continuation on the screen does not do that. Use
Auto Fill mode (*note Filling::) if that's what you want.
As an alternative to continuation, Emacs can display long lines by
"truncation". This means that all the characters that do not fit in
the width of the screen or window do not appear at all. They remain in
the buffer, temporarily invisible. `$' is used in the last column
instead of `\' to inform you that truncation is in effect.
Truncation instead of continuation happens whenever horizontal
scrolling is in use, and optionally in all side-by-side windows (*note
Windows::). You can enable truncation for a particular buffer by
setting the variable `truncate-lines' to non-`nil' in that buffer.
(*Note Variables::.) Altering the value of `truncate-lines' makes it
local to the current buffer; until that time, the default value is in
effect. The default is initially `nil'. *Note Locals::.
*Note Display Vars::, for additional variables that affect how text
is displayed.
File: emacs, Node: Position Info, Next: Arguments, Prev: Continuation Lines, Up: Basic
Cursor Position Information
===========================
Here are commands to get information about the size and position of
parts of the buffer, and to count lines.
`M-x what-page'
Print page number of point, and line number within page.
`M-x what-line'
Print line number of point in the buffer.
`M-x line-number-mode'
Toggle automatic display of current line number.
`M-='
Print number of lines in the current region (`count-lines-region').
*Note Mark::, for information about the region.
`C-x ='
Print character code of character after point, character position
of point, and column of point (`what-cursor-position').
There are two commands for working with line numbers. `M-x
what-line' computes the current line number and displays it in the echo
area. To go to a given line by number, use `M-x goto-line'; it prompts
you for the number. These line numbers count from one at the beginning
of the buffer.
You can also see the current line number in the mode line; *Note
Mode Line::. If you narrow the buffer, then the line number in the
mode line is relative to the accessible portion (*note Narrowing::).
By contrast, `what-line' shows both the line number relative to the
narrowed region and the line number relative to the whole buffer.
By contrast, `M-x what-page' counts pages from the beginning of the
file, and counts lines within the page, printing both numbers. *Note
Pages::.
While on this subject, we might as well mention `M-='
(`count-lines-region'), which prints the number of lines in the region
(*note Mark::). *Note Pages::, for the command `C-x l' which counts
the lines in the current page.
The command `C-x =' (`what-cursor-position') can be used to find out
the column that the cursor is in, and other miscellaneous information
about point. It prints a line in the echo area that looks like this:
Char: c (0143, 99, 0x63) point=21044 of 26883(78%) column 53
(In fact, this is the output produced when point is before the `column'
in the example.)
The four values after `Char:' describe the character that follows
point, first by showing it and then by giving its character code in
octal, decimal and hex. For a non-ASCII multibyte character, these are
followed by `ext' and the character's representation, in hex, in the
buffer's coding system, if that coding system encodes the character
safely and with a single byte (*note Coding Systems::). If the
character's encoding is longer than one byte, Emacs shows `ext ...'.
`point=' is followed by the position of point expressed as a
character count. The front of the buffer counts as position 1, one
character later as 2, and so on. The next, larger, number is the total
number of characters in the buffer. Afterward in parentheses comes the
position expressed as a percentage of the total size.
`column' is followed by the horizontal position of point, in columns
from the left edge of the window.
If the buffer has been narrowed, making some of the text at the
beginning and the end temporarily inaccessible, `C-x =' prints
additional text describing the currently accessible range. For
example, it might display this:
Char: C (0103, 67, 0x43) point=252 of 889(28%) <231 - 599> column 0
where the two extra numbers give the smallest and largest character
position that point is allowed to assume. The characters between those
two positions are the accessible ones. *Note Narrowing::.
If point is at the end of the buffer (or the end of the accessible
part), the `C-x =' output does not describe a character after point.
The output might look like this:
point=26957 of 26956(100%) column 0
`C-u C-x =' displays additional information about a character, in
place of the buffer coordinates and column: the character set name and
the codes that identify the character within that character set; ASCII
characters are identified as belonging to the `ASCII' character set.
In addition, the full character encoding, even if it takes more than a
single byte, is shown after `ext'. Here's an example for a Latin-1
character A with a grave accent in a buffer whose coding system is
iso-2022-7bit(1):
Char: A` (04300, 2240, 0x8c0, ext ESC , A @) (latin-iso8859-1 64)
---------- Footnotes ----------
(1) On terminals that support Latin-1 characters, the character
shown after `Char:' is displayed as the actual glyph of A with grave
accent.
File: emacs, Node: Arguments, Next: Repeating, Prev: Position Info, Up: Basic
Numeric Arguments
=================
In mathematics and computer usage, the word "argument" means "data
provided to a function or operation." You can give any Emacs command a
"numeric argument" (also called a "prefix argument"). Some commands
interpret the argument as a repetition count. For example, `C-f' with
an argument of ten moves forward ten characters instead of one. With
these commands, no argument is equivalent to an argument of one.
Negative arguments tell most such commands to move or act in the
opposite direction.
If your terminal keyboard has a <META> key, the easiest way to
specify a numeric argument is to type digits and/or a minus sign while
holding down the <META> key. For example,
M-5 C-n
would move down five lines. The characters `Meta-1', `Meta-2', and so
on, as well as `Meta--', do this because they are keys bound to
commands (`digit-argument' and `negative-argument') that are defined to
contribute to an argument for the next command. Digits and `-'
modified with Control, or Control and Meta, also specify numeric
arguments.
Another way of specifying an argument is to use the `C-u'
(`universal-argument') command followed by the digits of the argument.
With `C-u', you can type the argument digits without holding down
modifier keys; `C-u' works on all terminals. To type a negative
argument, type a minus sign after `C-u'. Just a minus sign without
digits normally means -1.
`C-u' followed by a character which is neither a digit nor a minus
sign has the special meaning of "multiply by four." It multiplies the
argument for the next command by four. `C-u' twice multiplies it by
sixteen. Thus, `C-u C-u C-f' moves forward sixteen characters. This
is a good way to move forward "fast," since it moves about 1/5 of a line
in the usual size screen. Other useful combinations are `C-u C-n',
`C-u C-u C-n' (move down a good fraction of a screen), `C-u C-u C-o'
(make "a lot" of blank lines), and `C-u C-k' (kill four lines).
Some commands care only about whether there is an argument, and not
about its value. For example, the command `M-q' (`fill-paragraph') with
no argument fills text; with an argument, it justifies the text as well.
(*Note Filling::, for more information on `M-q'.) Plain `C-u' is a
handy way of providing an argument for such commands.
Some commands use the value of the argument as a repeat count, but do
something peculiar when there is no argument. For example, the command
`C-k' (`kill-line') with argument N kills N lines, including their
terminating newlines. But `C-k' with no argument is special: it kills
the text up to the next newline, or, if point is right at the end of
the line, it kills the newline itself. Thus, two `C-k' commands with
no arguments can kill a nonblank line, just like `C-k' with an argument
of one. (*Note Killing::, for more information on `C-k'.)
A few commands treat a plain `C-u' differently from an ordinary
argument. A few others may treat an argument of just a minus sign
differently from an argument of -1. These unusual cases are described
when they come up; they are always for reasons of convenience of use of
the individual command.
You can use a numeric argument to insert multiple copies of a
character. This is straightforward unless the character is a digit; for
example, `C-u 6 4 a' inserts 64 copies of the character `a'. But this
does not work for inserting digits; `C-u 6 4 1' specifies an argument
of 641, rather than inserting anything. To separate the digit to
insert from the argument, type another `C-u'; for example, `C-u 6 4 C-u
1' does insert 64 copies of the character `1'.
We use the term "prefix argument" as well as "numeric argument" to
emphasize that you type the argument before the command, and to
distinguish these arguments from minibuffer arguments that come after
the command.
File: emacs, Node: Repeating, Prev: Arguments, Up: Basic
Repeating a Command
===================
The command `C-x z' (`repeat') provides another way to repeat an
Emacs command many times. This command repeats the previous Emacs
command, whatever that was. Repeating a command uses the same arguments
that were used before; it does not read new arguments each time.
To repeat the command more than once, type additional `z''s: each
`z' repeats the command one more time. Repetition ends when you type a
character other than `z', or press a mouse button.
For example, suppose you type `C-u 2 0 C-d' to delete 20 characters.
You can repeat that command (including its argument) three additional
times, to delete a total of 80 characters, by typing `C-x z z z'. The
first `C-x z' repeats the command once, and each subsequent `z' repeats
it once again.
File: emacs, Node: Minibuffer, Next: M-x, Prev: Basic, Up: Top
The Minibuffer
**************
The "minibuffer" is the facility used by Emacs commands to read
arguments more complicated than a single number. Minibuffer arguments
can be file names, buffer names, Lisp function names, Emacs command
names, Lisp expressions, and many other things, depending on the command
reading the argument. You can use the usual Emacs editing commands in
the minibuffer to edit the argument text.
When the minibuffer is in use, it appears in the echo area, and the
terminal's cursor moves there. The beginning of the minibuffer line
displays a "prompt" which says what kind of input you should supply and
how it will be used. Often this prompt is derived from the name of the
command that the argument is for. The prompt normally ends with a
colon.
Sometimes a "default argument" appears in parentheses after the
colon; it too is part of the prompt. The default will be used as the
argument value if you enter an empty argument (for example, just type
<RET>). For example, commands that read buffer names always show a
default, which is the name of the buffer that will be used if you type
just <RET>.
The simplest way to enter a minibuffer argument is to type the text
you want, terminated by <RET> which exits the minibuffer. You can
cancel the command that wants the argument, and get out of the
minibuffer, by typing `C-g'.
Since the minibuffer uses the screen space of the echo area, it can
conflict with other ways Emacs customarily uses the echo area. Here is
how Emacs handles such conflicts:
* If a command gets an error while you are in the minibuffer, this
does not cancel the minibuffer. However, the echo area is needed
for the error message and therefore the minibuffer itself is
hidden for a while. It comes back after a few seconds, or as soon
as you type anything.
* If in the minibuffer you use a command whose purpose is to print a
message in the echo area, such as `C-x =', the message is printed
normally, and the minibuffer is hidden for a while. It comes back
after a few seconds, or as soon as you type anything.
* Echoing of keystrokes does not take place while the minibuffer is
in use.
* Menu:
* File: Minibuffer File. Entering file names with the minibuffer.
* Edit: Minibuffer Edit. How to edit in the minibuffer.
* Completion:: An abbreviation facility for minibuffer input.
* Minibuffer History:: Reusing recent minibuffer arguments.
* Repetition:: Re-executing commands that used the minibuffer.
File: emacs, Node: Minibuffer File, Next: Minibuffer Edit, Up: Minibuffer
Minibuffers for File Names
==========================
Sometimes the minibuffer starts out with text in it. For example,
when you are supposed to give a file name, the minibuffer starts out
containing the "default directory", which ends with a slash. This is
to inform you which directory the file will be found in if you do not
specify a directory.
For example, the minibuffer might start out with these contents:
Find File: /u2/emacs/src/
where `Find File: ' is the prompt. Typing `buffer.c' specifies the
file `/u2/emacs/src/buffer.c'. To find files in nearby directories,
use `..'; thus, if you type `../lisp/simple.el', you will get the file
named `/u2/emacs/lisp/simple.el'. Alternatively, you can kill with
`M-<DEL>' the directory names you don't want (*note Words::).
If you don't want any of the default, you can kill it with `C-a
C-k'. But you don't need to kill the default; you can simply ignore it.
Insert an absolute file name, one starting with a slash or a tilde,
after the default directory. For example, to specify the file
`/etc/termcap', just insert that name, giving these minibuffer contents:
Find File: /u2/emacs/src//etc/termcap
GNU Emacs gives a special meaning to a double slash (which is not
normally a useful thing to write): it means, "ignore everything before
the second slash in the pair." Thus, `/u2/emacs/src/' is ignored in
the example above, and you get the file `/etc/termcap'.
If you set `insert-default-directory' to `nil', the default
directory is not inserted in the minibuffer. This way, the minibuffer
starts out empty. But the name you type, if relative, is still
interpreted with respect to the same default directory.
File: emacs, Node: Minibuffer Edit, Next: Completion, Prev: Minibuffer File, Up: Minibuffer
Editing in the Minibuffer
=========================
The minibuffer is an Emacs buffer (albeit a peculiar one), and the
usual Emacs commands are available for editing the text of an argument
you are entering.
Since <RET> in the minibuffer is defined to exit the minibuffer, you
can't use it to insert a newline in the minibuffer. To do that, type
`C-o' or `C-q C-j'. (Recall that a newline is really the character
control-J.)
The minibuffer has its own window which always has space on the
screen but acts as if it were not there when the minibuffer is not in
use. When the minibuffer is in use, its window is just like the
others; you can switch to another window with `C-x o', edit text in
other windows and perhaps even visit more files, before returning to
the minibuffer to submit the argument. You can kill text in another
window, return to the minibuffer window, and then yank the text to use
it in the argument. *Note Windows::.
There are some restrictions on the use of the minibuffer window,
however. You cannot switch buffers in it--the minibuffer and its
window are permanently attached. Also, you cannot split or kill the
minibuffer window. But you can make it taller in the normal fashion
with `C-x ^'. If you enable Resize-Minibuffer mode, then the
minibuffer window expands vertically as necessary to hold the text that
you put in the minibuffer. Use `M-x resize-minibuffer-mode' to enable
or disable this minor mode (*note Minor Modes::).
Scrolling works specially in the minibuffer window. When the
minibuffer is just one line high, and it contains a long line of text
that won't fit on the screen, scrolling automatically maintains an
overlap of a certain number of characters from one continuation line to
the next. The variable `minibuffer-scroll-overlap' specifies how many
characters of overlap; the default is 20.
If while in the minibuffer you issue a command that displays help
text of any sort in another window, you can use the `C-M-v' command
while in the minibuffer to scroll the help text. This lasts until you
exit the minibuffer. This feature is especially useful if a completing
minibuffer gives you a list of possible completions. *Note Other
Window::.
Emacs normally disallows most commands that use the minibuffer while
the minibuffer is active. This rule is to prevent recursive minibuffers
from confusing novice users. If you want to be able to use such
commands in the minibuffer, set the variable
`enable-recursive-minibuffers' to a non-`nil' value.
File: emacs, Node: Completion, Next: Minibuffer History, Prev: Minibuffer Edit, Up: Minibuffer
Completion
==========
For certain kinds of arguments, you can use "completion" to enter
the argument value. Completion means that you type part of the
argument, then Emacs visibly fills in the rest, or as much as can be
determined from the part you have typed.
When completion is available, certain keys--<TAB>, <RET>, and
<SPC>--are rebound to complete the text present in the minibuffer into
a longer string that it stands for, by matching it against a set of
"completion alternatives" provided by the command reading the argument.
`?' is defined to display a list of possible completions of what you
have inserted.
For example, when `M-x' uses the minibuffer to read the name of a
command, it provides a list of all available Emacs command names to
complete against. The completion keys match the text in the minibuffer
against all the command names, find any additional name characters
implied by the ones already present in the minibuffer, and add those
characters to the ones you have given. This is what makes it possible
to type `M-x ins <SPC> b <RET>' instead of `M-x insert-buffer <RET>'
(for example).
Case is normally significant in completion, because it is significant
in most of the names that you can complete (buffer names, file names and
command names). Thus, `fo' does not complete to `Foo'. Completion
does ignore case distinctions for certain arguments in which case does
not matter.
* Menu:
* Example: Completion Example.
* Commands: Completion Commands.
* Strict Completion::
* Options: Completion Options.
File: emacs, Node: Completion Example, Next: Completion Commands, Up: Completion
Completion Example
------------------
A concrete example may help here. If you type `M-x au <TAB>', the
<TAB> looks for alternatives (in this case, command names) that start
with `au'. There are several, including `auto-fill-mode' and
`auto-save-mode'--but they are all the same as far as `auto-', so the
`au' in the minibuffer changes to `auto-'.
If you type <TAB> again immediately, there are multiple
possibilities for the very next character--it could be any of
`cfilrs'--so no more characters are added; instead, <TAB> displays a
list of all possible completions in another window.
If you go on to type `f <TAB>', this <TAB> sees `auto-f'. The only
command name starting this way is `auto-fill-mode', so completion fills
in the rest of that. You now have `auto-fill-mode' in the minibuffer
after typing just `au <TAB> f <TAB>'. Note that <TAB> has this effect
because in the minibuffer it is bound to the command
`minibuffer-complete' when completion is available.
File: emacs, Node: Completion Commands, Next: Strict Completion, Prev: Completion Example, Up: Completion
Completion Commands
-------------------
Here is a list of the completion commands defined in the minibuffer
when completion is available.
`<TAB>'
Complete the text in the minibuffer as much as possible
(`minibuffer-complete').
`<SPC>'
Complete the minibuffer text, but don't go beyond one word
(`minibuffer-complete-word').
`<RET>'
Submit the text in the minibuffer as the argument, possibly
completing first as described below
(`minibuffer-complete-and-exit').
`?'
Print a list of all possible completions of the text in the
minibuffer (`minibuffer-list-completions').
<SPC> completes much like <TAB>, but never goes beyond the next
hyphen or space. If you have `auto-f' in the minibuffer and type
<SPC>, it finds that the completion is `auto-fill-mode', but it stops
completing after `fill-'. This gives `auto-fill-'. Another <SPC> at
this point completes all the way to `auto-fill-mode'. <SPC> in the
minibuffer when completion is available runs the command
`minibuffer-complete-word'.
Here are some commands you can use to choose a completion from a
window that displays a list of completions:
`Mouse-2'
Clicking mouse button 2 on a completion in the list of possible
completions chooses that completion (`mouse-choose-completion').
You normally use this command while point is in the minibuffer;
but you must click in the list of completions, not in the
minibuffer itself.
`<PRIOR>'
`M-v'
Typing <PRIOR> or <PAGE-UP>, or `M-v', while in the minibuffer,
selects the window showing the completion list buffer
(`switch-to-completions'). This paves the way for using the
commands below. (Selecting that window in the usual ways has the
same effect, but this way is more convenient.)
`<RET>'
Typing <RET> _in the completion list buffer_ chooses the
completion that point is in or next to (`choose-completion'). To
use this command, you must first switch windows to the window that
shows the list of completions.
`<RIGHT>'
Typing the right-arrow key <RIGHT> _in the completion list buffer_
moves point to the following completion (`next-completion').
`<LEFT>'
Typing the left-arrow key <LEFT> _in the completion list buffer_
moves point toward the beginning of the buffer, to the previous
completion (`previous-completion').
File: emacs, Node: Strict Completion, Next: Completion Options, Prev: Completion Commands, Up: Completion
Strict Completion
-----------------
There are three different ways that <RET> can work in completing
minibuffers, depending on how the argument will be used.
* "Strict" completion is used when it is meaningless to give any
argument except one of the known alternatives. For example, when
`C-x k' reads the name of a buffer to kill, it is meaningless to
give anything but the name of an existing buffer. In strict
completion, <RET> refuses to exit if the text in the minibuffer
does not complete to an exact match.
* "Cautious" completion is similar to strict completion, except that
<RET> exits only if the text was an exact match already, not
needing completion. If the text is not an exact match, <RET> does
not exit, but it does complete the text. If it completes to an
exact match, a second <RET> will exit.
Cautious completion is used for reading file names for files that
must already exist.
* "Permissive" completion is used when any string whatever is
meaningful, and the list of completion alternatives is just a
guide. For example, when `C-x C-f' reads the name of a file to
visit, any file name is allowed, in case you want to create a
file. In permissive completion, <RET> takes the text in the
minibuffer exactly as given, without completing it.
The completion commands display a list of all possible completions in
a window whenever there is more than one possibility for the very next
character. Also, typing `?' explicitly requests such a list. If the
list of completions is long, you can scroll it with `C-M-v' (*note
Other Window::).