Go to the previous, next section.
An abbrev is a word which expands, if you insert it, into some
different text. Abbrevs are defined by the user to expand in specific
ways. For example, you might define `foo' as an abbrev expanding to
`find outer otter'. With this abbrev defined, you would be able to
get `find outer otter ' into the buffer by typing f o o SPC.
Abbrevs expand only when Abbrev mode (a minor mode) is enabled.
Disabling Abbrev mode does not cause abbrev definitions to be forgotten,
but they do not expand until Abbrev mode is enabled again. The command
M-x abbrev-mode toggles Abbrev mode; with a numeric argument, it
turns Abbrev mode on if the argument is positive, off otherwise.
See section Minor Modes. abbrev-mode is also a variable; Abbrev mode is
on when the variable is non-nil. The variable abbrev-mode
automatically becomes local to the current buffer when it is set.
Abbrev definitions can be mode-specific---active only in one major mode. Abbrevs can also have global definitions that are active in all major modes. The same abbrev can have a global definition and various mode-specific definitions for different major modes. A mode specific definition for the current major mode overrides a global definition.
Abbrevs can be defined interactively during the editing session. Lists of abbrev definitions can also be saved in files and reloaded in later sessions. Some users keep extensive lists of abbrevs that they load in every session.
A second kind of abbreviation facility is called the dynamic expansion. Dynamic abbrev expansion happens only when you give an explicit command and the result of the expansion depends only on the current contents of the buffer. See section Dynamic Abbrev Expansion.
add-global-abbrev).
add-mode-abbrev).
inverse-add-global-abbrev).
inverse-add-mode-abbrev).
The usual way to define an abbrev is to enter the text you want the
abbrev to expand to, position point after it, and type C-x a g
(add-global-abbrev). This reads the abbrev itself using the
minibuffer, and then defines it as an abbrev for one or more words before
point. Use a numeric argument to say how many words before point should be
taken as the expansion. For example, to define the abbrev `foo' as
mentioned above, insert the text `find outer otter' and then type
C-u 3 C-x a g f o o RET.
An argument of zero to C-x a g means to use the contents of the
region as the expansion of the abbrev being defined.
The command C-x a l (add-mode-abbrev) is similar, but
defines a mode-specific abbrev. Mode specific abbrevs are active only in a
particular major mode. C-x a l defines an abbrev for the major mode
in effect at the time C-x a l is typed. The arguments work the same
as for C-x a g.
If the text of the abbrev you want is already in the buffer instead of
the expansion, use command C-x a i g
(inverse-add-global-abbrev) instead of C-x a g, or use
C-x a i l (inverse-add-mode-abbrev) instead of C-x a
l. These commands are called "inverse" because they invert the
meaning of the argument found in the buffer and the argument read using
the minibuffer.
To change the definition of an abbrev, just add the new definition.
You will be asked to confirm if the abbrev has a prior definition. To
remove an abbrev definition, give a negative argument to C-x a g
or C-x a l. You must choose the command to specify whether to
kill a global definition or a mode-specific definition for the current
mode, since those two definitions are independent for one abbrev.
M-x kill-all-abbrevs removes all the abbrev definitions there are.
An abbrev expands whenever it is present in the buffer just before
point and you type a self-inserting whitespace or punctuation character
(SPC, comma, etc.). More precisely, any character that is not a
word constituent expands an abbrev, and any word constituent character
can be part of an abbrev. The most common way to use an abbrev is to
insert it and then insert a punctuation character to expand it.
Abbrev expansion preserves case; thus, `foo' expands into `find
outer otter'; `Foo' into `Find outer otter', and `FOO' into
`FIND OUTER OTTER' or `Find Outer Otter' according to the
variable abbrev-all-caps (a non-nil value chooses the first
of the two expansions).
These two commands are used to control abbrev expansion:
abbrev-prefix-mark).
expand-abbrev).
This is effective even when Abbrev mode is not enabled.
You may wish to expand an abbrev with a prefix attached; for example, if
`cnst' expands into `construction', you might want to use it to
enter `reconstruction'. It does not work to type recnst,
because that is not necessarily a defined abbrev. What does work is to use
the command M-' (abbrev-prefix-mark) in between the prefix
`re' and the abbrev `cnst'. First, insert `re'. Then type
M-'; this inserts a minus sign in the buffer to indicate that it has
done its work. Then insert the abbrev `cnst'; the buffer now contains
`re-cnst'. Now insert a non-word character to expand the abbrev
`cnst' into `construction'. The minus sign is deleted at this
point, because M-' left word for this to be done. The resulting text
is the desired `reconstruction'.
If you actually want the text of the abbrev in the buffer, rather than
its expansion, you can accomplish this by inserting the following
punctuation with C-q. Thus, foo C-q - leaves `foo-' in the
buffer.
If you expand an abbrev by mistake, you can undo the expansion
(replace the expansion by the original abbrev text) with M-x
unexpand-abbrev. C-_ (undo) can also be used to undo the
expansion; but first it undoes the insertion of the following non-word
character. Therefore, if you want both the non-word character and the
unexpanded abbrev, you must reinsert the terminating character, quoting
it with C-q.
M-x expand-region-abbrevs searches through the region for defined abbrevs, and for each one found offers to replace it with its expansion. This command is useful if you have typed in text using abbrevs but forgot to turn on Abbrev mode first. It may also be useful together with a special set of abbrev definitions for making several global replacements at once. This command is effective even if Abbrev mode is not enabled.
Expanding an abbrev runs the hook pre-abbrev-expand-hook
(see section Hooks).
The output from M-x list-abbrevs looks like this:
(lisp-mode-abbrev-table) "dk" 0 "define-key" (global-abbrev-table) "dfn" 0 "definition"
(Some blank lines of no semantic significance, and some other abbrev tables, have been omitted.)
A line containing a name in parentheses is the header for abbrevs in a
particular abbrev table; global-abbrev-table contains all the global
abbrevs, and the other abbrev tables that are named after major modes
contain the mode-specific abbrevs.
Within each abbrev table, each nonblank line defines one abbrev. The
word at the beginning is the abbrev. The number that appears is the number
of times the abbrev has been expanded. Emacs keeps track of this to help
you see which abbrevs you actually use, in case you decide to eliminate
those that you don't use often. The string at the end of the line is the
expansion.
M-x edit-abbrevs allows you to add, change or kill abbrev
definitions by editing a list of them in an Emacs buffer. The list has the
same format described above. The buffer of abbrevs is called `*Abbrevs*',
and is in Edit-Abbrevs mode. This mode redefines the key C-c C-c to
install the abbrev definitions as specified in the buffer. The command
that does this is edit-abbrevs-redefine. Any abbrevs not described
in the buffer are eliminated when this is done.
The command edit-abbrevs is actually the same as
list-abbrevs except that it selects the buffer `*Abbrevs*'
whereas list-abbrevs merely displays it in another window.
These commands allow you to keep abbrev definitions between editing sessions.
M-x write-abbrev-file reads a file name using the minibuffer and
writes a description of all current abbrev definitions into that file.
This is used to save abbrev definitions for use in a later session. The
text stored in the file is a series of Lisp expressions that, when
executed, define the same abbrevs that you currently have.
M-x read-abbrev-file reads a file name using the minibuffer and
reads the file, defining abbrevs according to the contents of the file.
M-x quietly-read-abbrev-file is the same except that it does not
display a message in the echo area saying that it is doing its work; it
is actually useful primarily in the `.emacs' file. If an empty
argument is given to either of these functions, the file name used is the
value of the variable abbrev-file-name, which is by default
"~/.abbrev_defs".
Emacs will offer to save abbrevs automatically if you have changed any of
them, whenever it offers to save all files (for C-x s or C-x
C-c). This feature can be inhibited by setting the variable
save-abbrevs to nil.
The commands M-x insert-abbrevs and M-x define-abbrevs are similar to the previous commands but work on text in an Emacs buffer. M-x insert-abbrevs inserts text into the current buffer before point, describing all current abbrev definitions; M-x define-abbrevs parses the entire current buffer and defines abbrevs accordingly.
The abbrev facility described above operates automatically as you insert
text, but all abbrevs must be defined explicitly. By contrast,
dynamic abbrevs allow the meanings of abbrevs to be determined
automatically from the contents of the buffer, but dynamic abbrev expansion
happens only when you request it explicitly.
dabbrev-expand).
For example, if the buffer contains `does this follow ' and you type f o M-/, the effect is to insert `follow' because that is the last word in the buffer that starts with `fo'. A numeric argument to M-/ says to take the second, third, etc. distinct expansion found looking backward from point. Repeating M-/ searches for an alternative expansion by looking farther back. After the entire buffer before point has been considered, the buffer after point is searched.
Dynamic abbrev expansion is completely independent of Abbrev mode; the expansion of a word with M-/ is completely independent of whether it has a definition as an ordinary abbrev.
Go to the previous, next section.