This is ../info/emacs, produced by makeinfo version 4.0f from
emacs.texi.
This is the Fourteenth edition of the `GNU Emacs Manual', updated
for Emacs version 21.2.
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: 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'
Display the page number of point, and the line number within the
page.
`M-x what-line'
Display the line number of point in the buffer.
`M-x line-number-mode'
`M-x column-number-mode'
Toggle automatic display of current line number or column number.
*Note Optional Mode Line::.
`M-='
Display the number of lines in the current region
(`count-lines-region'). *Note Mark::, for information about the
region.
`C-x ='
Display the character code of character after point, character
position of point, and column of point (`what-cursor-position').
`M-x hl-line-mode'
Enable or disable highlighting of the current line. *Note Cursor
Display::.
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; see *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.
`M-x what-page' counts pages from the beginning of the file, and
counts lines within the page, showing both numbers in the echo area.
*Note Pages::.
While on this subject, we might as well mention `M-='
(`count-lines-region'), which displays 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 displays 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 =' displays
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. `Meta--' without
digits normally means -1. 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
===================
Many simple commands, such as those invoked with a single key or
with `M-x COMMAND-NAME <RET>', can be repeated by invoking them with a
numeric argument that serves as a repeat count (*note Arguments::).
However, if the command you want to repeat prompts for some input, or
uses a numeric argument in another way, repetition using a numeric
argument might be problematical.
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 (that is, 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 display
a message in the echo area, such as `C-x =', the message hides the
minibuffer for a while. The minibuffer contents come 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 ^'.
The minibuffer window expands vertically as necessary to hold the
text that you put in the minibuffer, if `resize-mini-windows' is
non-`nil'. If `resize-mini-windows' is `t', the window is always
resized to fit the size of the text it displays. If
`resize-mini-windows' is the symbol `grow-only', the window grows when
the size of displayed text increases, but shrinks (back to the normal
size) only when the minibuffer becomes inactive.
The variable `max-mini-window-height' controls the maximum height
for resizing the minibuffer window: a floating-point number specifies a
fraction of the frame's height; an integer specifies the maximum number
of lines; `nil' means do not resize the minibuffer window
automatically. The default value is 0.25.
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 when you display
a buffer listing 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').
`?'
Display 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'. The command that
implements this behavior is called `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::).
File: emacs, Node: Completion Options, Prev: Strict Completion, Up: Completion
Completion Options
------------------
When completion is done on file names, certain file names are usually
ignored. The variable `completion-ignored-extensions' contains a list
of strings; a file whose name ends in any of those strings is ignored
as a possible completion. The standard value of this variable has
several elements including `".o"', `".elc"', `".dvi"' and `"~"'. The
effect is that, for example, `foo' can complete to `foo.c' even though
`foo.o' exists as well. However, if _all_ the possible completions end
in "ignored" strings, then they are not ignored. Ignored extensions do
not apply to lists of completions--those always mention all possible
completions.
Normally, a completion command that cannot determine even one
additional character automatically displays a list of all possible
completions. If the variable `completion-auto-help' is set to `nil',
this automatic display is disabled, so you must type `?' to display the
list of completions.
Partial Completion mode implements a more powerful kind of
completion that can complete multiple words in parallel. For example,
it can complete the command name abbreviation `p-b' into
`print-buffer', because no other command starts with two words whose
initials are `p' and `b'.
Partial completion of directories in file names uses `*' to indicate
the places for completion; thus, `/u*/b*/f*' might complete to
`/usr/bin/foo'.
To enable this mode, use the command `M-x partial-completion-mode',
or customize the option `partial-completion-mode'. This binds the
partial completion commands to <TAB>, <SPC>, <RET>, and `?'. The usual
completion commands are available on `M-<TAB>', `M-<SPC>', `M-<RET>'
and `M-?'.
Another feature of Partial Completion mode is to extend `find-file'
so that the `<INCLUDE>' stands for the file named INCLUDE in some
directory in the path `PC-include-file-path'. If you set
`PC-disable-includes' to non-`nil', this feature is disabled.
Icomplete mode presents a constantly-updated display that tells you
what completions are available for the text you've entered so far. The
command to enable or disable this minor mode is `M-x icomplete-mode'.
File: emacs, Node: Minibuffer History, Next: Repetition, Prev: Completion, Up: Minibuffer
Minibuffer History
==================
Every argument that you enter with the minibuffer is saved on a
"minibuffer history list" so that you can use it again later in another
argument. Special commands load the text of an earlier argument in the
minibuffer. They discard the old minibuffer contents, so you can think
of them as moving through the history of previous arguments.
`<UP>'
`M-p'
Move to the next earlier argument string saved in the minibuffer
history (`previous-history-element').
`<DOWN>'
`M-n'
Move to the next later argument string saved in the minibuffer
history (`next-history-element').
`M-r REGEXP <RET>'
Move to an earlier saved argument in the minibuffer history that
has a match for REGEXP (`previous-matching-history-element').
`M-s REGEXP <RET>'
Move to a later saved argument in the minibuffer history that has a
match for REGEXP (`next-matching-history-element').
The simplest way to reuse the saved arguments in the history list is
to move through the history list one element at a time. While in the
minibuffer, use `M-p' or up-arrow (`previous-history-element') to "move
to" the next earlier minibuffer input, and use `M-n' or down-arrow
(`next-history-element') to "move to" the next later input.
The previous input that you fetch from the history entirely replaces
the contents of the minibuffer. To use it as the argument, exit the
minibuffer as usual with <RET>. You can also edit the text before you
reuse it; this does not change the history element that you "moved" to,
but your new argument does go at the end of the history list in its own
right.
For many minibuffer arguments there is a "default" value. In some
cases, the minibuffer history commands know the default value. Then you
can insert the default value into the minibuffer as text by using `M-n'
to move "into the future" in the history. Eventually we hope to make
this feature available whenever the minibuffer has a default value.
There are also commands to search forward or backward through the
history; they search for history elements that match a regular
expression that you specify with the minibuffer. `M-r'
(`previous-matching-history-element') searches older elements in the
history, while `M-s' (`next-matching-history-element') searches newer
elements. By special dispensation, these commands can use the
minibuffer to read their arguments even though you are already in the
minibuffer when you issue them. As with incremental searching, an
upper-case letter in the regular expression makes the search
case-sensitive (*note Search Case::).
All uses of the minibuffer record your input on a history list, but
there are separate history lists for different kinds of arguments. For
example, there is a list for file names, used by all the commands that
read file names. (As a special feature, this history list records the
absolute file name, no more and no less, even if that is not how you
entered the file name.)
There are several other very specific history lists, including one
for command names read by `M-x', one for buffer names, one for arguments
of commands like `query-replace', and one for compilation commands read
by `compile'. Finally, there is one "miscellaneous" history list that
most minibuffer arguments use.
The variable `history-length' specifies the maximum length of a
minibuffer history list; once a list gets that long, the oldest element
is deleted each time an element is added. If the value of
`history-length' is `t', though, there is no maximum length and
elements are never deleted.
File: emacs, Node: Repetition, Prev: Minibuffer History, Up: Minibuffer
Repeating Minibuffer Commands
=============================
Every command that uses the minibuffer at least once is recorded on a
special history list, together with the values of its arguments, so that
you can repeat the entire command. In particular, every use of `M-x'
is recorded there, since `M-x' uses the minibuffer to read the command
name.
`C-x <ESC> <ESC>'
Re-execute a recent minibuffer command (`repeat-complex-command').
`M-x list-command-history'
Display the entire command history, showing all the commands `C-x
<ESC> <ESC>' can repeat, most recent first.
`C-x <ESC> <ESC>' is used to re-execute a recent minibuffer-using
command. With no argument, it repeats the last such command. A
numeric argument specifies which command to repeat; one means the last
one, and larger numbers specify earlier ones.
`C-x <ESC> <ESC>' works by turning the previous command into a Lisp
expression and then entering a minibuffer initialized with the text for
that expression. If you type just <RET>, the command is repeated as
before. You can also change the command by editing the Lisp
expression. Whatever expression you finally submit is what will be
executed. The repeated command is added to the front of the command
history unless it is identical to the most recently executed command
already there.
Even if you don't understand Lisp syntax, it will probably be obvious
which command is displayed for repetition. If you do not change the
text, it will repeat exactly as before.
Once inside the minibuffer for `C-x <ESC> <ESC>', you can use the
minibuffer history commands (`M-p', `M-n', `M-r', `M-s'; *note
Minibuffer History::) to move through the history list of saved entire
commands. After finding the desired previous command, you can edit its
expression as usual and then resubmit it by typing <RET> as usual.
The list of previous minibuffer-using commands is stored as a Lisp
list in the variable `command-history'. Each element is a Lisp
expression which describes one command and its arguments. Lisp programs
can re-execute a command by calling `eval' with the `command-history'
element.
File: emacs, Node: M-x, Next: Help, Prev: Minibuffer, Up: Top
Running Commands by Name
************************
Every Emacs command has a name that you can use to run it. Commands
that are used often, or that must be quick to type, are also bound to
keys--short sequences of characters--for convenient use. You can run
them by name if you don't remember the keys. Other Emacs commands that
do not need to be quick are not bound to keys; the only way to run them
is by name. *Note Key Bindings::, for the description of how to bind
commands to keys.
By convention, a command name consists of one or more words,
separated by hyphens; for example, `auto-fill-mode' or `manual-entry'.
The use of English words makes the command name easier to remember than
a key made up of obscure characters, even though it is more characters
to type.
The way to run a command by name is to start with `M-x', type the
command name, and finish it with <RET>. `M-x' uses the minibuffer to
read the command name. <RET> exits the minibuffer and runs the
command. The string `M-x' appears at the beginning of the minibuffer
as a "prompt" to remind you to enter the name of a command to be run.
*Note Minibuffer::, for full information on the features of the
minibuffer.
You can use completion to enter the command name. For example, you
can invoke the command `forward-char' by name by typing either
M-x forward-char <RET>
or
M-x forw <TAB> c <RET>
Note that `forward-char' is the same command that you invoke with the
key `C-f'. You can run any Emacs command by name using `M-x', whether
or not any keys are bound to it.
If you type `C-g' while the command name is being read, you cancel
the `M-x' command and get out of the minibuffer, ending up at top level.
To pass a numeric argument to the command you are invoking with
`M-x', specify the numeric argument before the `M-x'. `M-x' passes the
argument along to the command it runs. The argument value appears in
the prompt while the command name is being read.
If the command you type has a key binding of its own, Emacs mentions
this in the echo area, two seconds after the command finishes (if you
don't type anything else first). For example, if you type `M-x
forward-word', the message says that you can run the same command more
easily by typing `M-f'. You can turn off these messages by setting
`suggest-key-bindings' to `nil'.
Normally, when describing in this manual a command that is run by
name, we omit the <RET> that is needed to terminate the name. Thus we
might speak of `M-x auto-fill-mode' rather than `M-x auto-fill-mode
<RET>'. We mention the <RET> only when there is a need to emphasize
its presence, such as when we show the command together with following
arguments.
`M-x' works by running the command `execute-extended-command', which
is responsible for reading the name of another command and invoking it.
File: emacs, Node: Help, Next: Mark, Prev: M-x, Up: Top
Help
****
Emacs provides extensive help features accessible through a single
character, `C-h'. `C-h' is a prefix key that is used for commands that
display documentation. The characters that you can type after `C-h'
are called "help options". One help option is `C-h'; that is how you
ask for help about using `C-h'. To cancel, type `C-g'. The function
key <F1> is equivalent to `C-h'.
`C-h C-h' (`help-for-help') displays a list of the possible help
options, each with a brief description. Before you type a help option,
you can use <SPC> or <DEL> to scroll through the list.
`C-h' or <F1> means "help" in various other contexts as well. For
example, in the middle of `query-replace', it describes the options
available for how to operate on the current match. After a prefix key,
it displays a list of the alternatives that can follow the prefix key.
(A few prefix keys don't support `C-h', because they define other
meanings for it, but they all support <F1>.)
Most help buffers use a special major mode, Help mode, which lets you
scroll conveniently with <SPC> and <DEL>. It also offers hyperlinks to
further help regarding cross-referenced names, Info nodes,
customization buffers and the like. *Note Help Mode::.
If you are looking for a certain feature, but don't know where
exactly it is documented, and aren't sure of the name of a related
command or option, we recommend trying these methods. Usually it is
best to start with an apropos command, then try searching the manual
index, then finally look in the FAQ and the package keywords.
`C-h a TOPIC <RET>'
This searches for commands whose names match TOPIC, which should
be a regular expression (*note Regexps::). Browse the buffer that
this command displays to find what you are looking for. *Note
Apropos::.
`M-x apropos <RET> TOPIC <RET>'
This works like `C-h a', but it also searches for user options and
other variables, in case the feature you are looking for is
controlled by an option, not a command. *Note Apropos::.
`M-x apropos-documentation <RET> TOPIC <RET>'
This searches the _documentation strings_ (the built-in short
descriptions) of all variables and functions (not their names) for
a match for TOPIC, a regular expression. *Note Apropos::.
`C-h i d m emacs <RET> i TOPIC <RET>'
This looks up TOPIC in the indices of the Emacs on-line manual.
If there are several matches, Emacs displays the first one. You
can then press <,> to move to other matches, until you find what
you are looking for.
`C-h i d m emacs <RET> s TOPIC <RET>'
Similar, but searches for TOPIC (which can be a regular
expression) in the _text_ of the manual rather than in its indices.
`C-h F'
This brings up the Emacs FAQ, where you can use the usual search
commands (*note Search::) to find the information.
`C-h p'
Finally, you can try looking up a suitable package using keywords
pertinent to the feature you need. *Note Library Keywords::.
To find the documentation of a key sequence or a menu item, type
`C-h C-k' and then type that key sequence or select the menu item.
This looks up the description of the command invoked by the key or the
menu in the appropriate manual (not necessarily the Emacs manual).
Likewise, use `C-h C-f' for reading documentation of a command.
* Menu:
* Help Summary:: Brief list of all Help commands.
* Key Help:: Asking what a key does in Emacs.
* Name Help:: Asking about a command, variable or function name.
* Apropos:: Asking what pertains to a given topic.
* Library Keywords:: Finding Lisp libraries by keywords (topics).
* Language Help:: Help relating to international language support.
* Help Mode:: Special features of Help mode and Help buffers.
* Misc Help:: Other help commands.
* Help Echo:: Help on active text and tooltips (`balloon help')
File: emacs, Node: Help Summary, Next: Key Help, Up: Help
Help Summary
============
Here is a summary of the defined help commands.
`C-h a REGEXP <RET>'
Display a list of commands whose names match REGEXP
(`apropos-command').
`C-h b'
Display a table of all key bindings in effect now, in this order:
minor mode bindings, major mode bindings, and global bindings
(`describe-bindings').
`C-h c KEY'
Show the name of the command that KEY runs
(`describe-key-briefly'). Here `c' stands for "character." For
more extensive information on KEY, use `C-h k'.
`C-h f FUNCTION <RET>'
Display documentation on the Lisp function named FUNCTION
(`describe-function'). Since commands are Lisp functions, a
command name may be used.
`C-h h'
Display the `HELLO' file, which shows examples of various character
sets.
`C-h i'
Run Info, the program for browsing documentation files (`info').
The complete Emacs manual is available on-line in Info.
`C-h k KEY'
Display the name and documentation of the command that KEY runs
(`describe-key').
`C-h l'
Display a description of the last 100 characters you typed
(`view-lossage').
`C-h m'
Display documentation of the current major mode (`describe-mode').
`C-h n'
Display documentation of Emacs changes, most recent first
(`view-emacs-news').
`C-h P'
Display info on known problems with Emacs and possible workarounds
(`view-emacs-problems').
`C-h p'
Find packages by topic keyword (`finder-by-keyword').
`C-h s'
Display the current contents of the syntax table, plus an
explanation of what they mean (`describe-syntax'). *Note Syntax::.
`C-h t'
Enter the Emacs interactive tutorial (`help-with-tutorial').
`C-h v VAR <RET>'
Display the documentation of the Lisp variable VAR
(`describe-variable').
`C-h w COMMAND <RET>'
Show which keys run the command named COMMAND (`where-is').
`C-h C CODING <RET>'
Describe coding system CODING (`describe-coding-system').
`C-h C <RET>'
Describe the coding systems currently in use.
`C-h I METHOD <RET>'
Describe an input method (`describe-input-method').
`C-h L LANGUAGE-ENV <RET>'
Display information on the character sets, coding systems, and
input methods used for language environment LANGUAGE-ENV
(`describe-language-environment').
`C-h C-c'
Display the copying conditions for GNU Emacs.
`C-h C-d'
Display information about getting new versions of GNU Emacs.
`C-h C-f FUNCTION <RET>'
Enter Info and go to the node documenting the Emacs function
FUNCTION (`Info-goto-emacs-command-node').
`C-h C-k KEY'
Enter Info and go to the node where the key sequence KEY is
documented (`Info-goto-emacs-key-command-node').
`C-h C-p'
Display information about the GNU Project.
`C-h <TAB> SYMBOL <RET>'
Display the Info documentation on symbol SYMBOL according to the
programming language you are editing (`info-lookup-symbol').
File: emacs, Node: Key Help, Next: Name Help, Prev: Help Summary, Up: Help
Documentation for a Key
=======================
The most basic `C-h' options are `C-h c' (`describe-key-briefly')
and `C-h k' (`describe-key'). `C-h c KEY' displays in the echo area
the name of the command that KEY is bound to. For example, `C-h c C-f'
displays `forward-char'. Since command names are chosen to describe
what the commands do, this is a good way to get a very brief
description of what KEY does.
`C-h k KEY' is similar but gives more information: it displays the
documentation string of the command as well as its name. This is too
big for the echo area, so a window is used for the display.
`C-h c' and `C-h k' work for any sort of key sequences, including
function keys and mouse events.
File: emacs, Node: Name Help, Next: Apropos, Prev: Key Help, Up: Help
Help by Command or Variable Name
================================
`C-h f' (`describe-function') reads the name of a Lisp function
using the minibuffer, then displays that function's documentation string
in a window. Since commands are Lisp functions, you can use this to get
the documentation of a command that you know by name. For example,
C-h f auto-fill-mode <RET>
displays the documentation of `auto-fill-mode'. This is the only way
to get the documentation of a command that is not bound to any key (one
which you would normally run using `M-x').
`C-h f' is also useful for Lisp functions that you are planning to
use in a Lisp program. For example, if you have just written the
expression `(make-vector len)' and want to check that you are using
`make-vector' properly, type `C-h f make-vector <RET>'. Because `C-h
f' allows all function names, not just command names, you may find that
some of your favorite abbreviations that work in `M-x' don't work in
`C-h f'. An abbreviation may be unique among command names yet fail to
be unique when other function names are allowed.
The default function name for `C-h f' to describe, if you type just
<RET>, is the name of the function called by the innermost Lisp
expression in the buffer around point, _provided_ that is a valid,
defined Lisp function name. For example, if point is located following
the text `(make-vector (car x)', the innermost list containing point is
the one that starts with `(make-vector', so the default is to describe
the function `make-vector'.
`C-h f' is often useful just to verify that you have the right
spelling for the function name. If `C-h f' mentions a name from the
buffer as the default, that name must be defined as a Lisp function. If
that is all you want to know, just type `C-g' to cancel the `C-h f'
command, then go on editing.
`C-h w COMMAND <RET>' tells you what keys are bound to COMMAND. It
displays a list of the keys in the echo area. If it says the command
is not on any key, you must use `M-x' to run it. `C-h w' runs the
command `where-is'.
`C-h v' (`describe-variable') is like `C-h f' but describes Lisp
variables instead of Lisp functions. Its default is the Lisp symbol
around or before point, but only if that is the name of a known Lisp
variable. *Note Variables::.
Help buffers describing variables or functions defined in Lisp
normally have hyperlinks to the Lisp definition, if you have the Lisp
source files installed. If you know Lisp, this provides the ultimate
documentation. If you don't know Lisp, you should learn it. If you
are treating Emacs as an object file, then you are just _using_ Emacs.
For real intimacy with Emacs, you must read the source code.
File: emacs, Node: Apropos, Next: Library Keywords, Prev: Name Help, Up: Help
Apropos
=======
A more sophisticated sort of question to ask is, "What are the
commands for working with files?" To ask this question, type `C-h a
file <RET>', which displays a list of all command names that contain
`file', including `copy-file', `find-file', and so on. With each
command name appears a brief description of how to use the command, and
what keys you can currently invoke it with. For example, it would say
that you can invoke `find-file' by typing `C-x C-f'. The `a' in `C-h
a' stands for "Apropos"; `C-h a' runs the command `apropos-command'.
This command normally checks only commands (interactive functions); if
you specify a prefix argument, it checks noninteractive functions as
well.
Because `C-h a' looks only for functions whose names contain the
string you specify, you must use ingenuity in choosing the string. If
you are looking for commands for killing backwards and `C-h a
kill-backwards <RET>' doesn't reveal any, don't give up. Try just
`kill', or just `backwards', or just `back'. Be persistent. Also note
that you can use a regular expression as the argument, for more
flexibility (*note Regexps::).
Here is a set of arguments to give to `C-h a' that covers many
classes of Emacs commands, since there are strong conventions for naming
the standard Emacs commands. By giving you a feel for the naming
conventions, this set should also serve to aid you in developing a
technique for picking `apropos' strings.
char, line, word, sentence, paragraph, region, page, sexp, list,
defun, rect, buffer, frame, window, face, file, dir, register,
mode, beginning, end, forward, backward, next, previous, up, down,
search, goto, kill, delete, mark, insert, yank, fill, indent,
case, change, set, what, list, find, view, describe, default.
To list all user variables that match a regexp, use the command `M-x
apropos-variable'. This command shows only user variables and
customization options by default; if you specify a prefix argument, it
checks all variables.
To list all Lisp symbols that contain a match for a regexp, not just
the ones that are defined as commands, use the command `M-x apropos'
instead of `C-h a'. This command does not check key bindings by
default; specify a numeric argument if you want it to check them.
The `apropos-documentation' command is like `apropos' except that it
searches documentation strings as well as symbol names for matches for
the specified regular expression.
The `apropos-value' command is like `apropos' except that it
searches symbols' values for matches for the specified regular
expression. This command does not check function definitions or
property lists by default; specify a numeric argument if you want it to
check them.
If the variable `apropos-do-all' is non-`nil', the commands above
all behave as if they had been given a prefix argument.
If you want more information about a function definition, variable or
symbol property listed in the Apropos buffer, you can click on it with
`Mouse-2' or move there and type <RET>.