@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2002, 2003,
+@c 2004, 2005, 2006 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
-@node Abbrevs, Picture, Building, Top
+@node Abbrevs, Sending Mail, Maintaining, Top
@chapter Abbrevs
@cindex abbrevs
@cindex expansion (of abbrevs)
A defined @dfn{abbrev} is a word which @dfn{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 @samp{foo} as an abbrev
-expanding to @samp{find outer otter}. Then you would be able to insert
+expanding to @samp{find outer otter}. Then you could insert
@samp{find outer otter } into the buffer by typing @kbd{f o o
@key{SPC}}.
words in the buffer that start with those letters. @xref{Dynamic
Abbrevs}.
-`Hippie' expansion generalizes abbreviation expansion.
-@xref{Hippie Expand, `Hippie' Expansion, autotype, Features for
+ ``Hippie'' expansion generalizes abbreviation expansion.
+@xref{Hippie Expand, , Hippie Expansion, autotype, Features for
Automatic Typing}.
@menu
on when the variable is non-@code{nil}. The variable @code{abbrev-mode}
automatically becomes local to the current buffer when it is set.
- Abbrev definitions can be @dfn{mode-specific}---active only in one major
+ Abbrevs can have @dfn{mode-specific} definitions, active only in one major
mode. Abbrevs can also have @dfn{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.
+ Yu can define abbrevs interactively during the editing session. You
+can also save lists of abbrev definitions in files for use in later
+sessions. Some users keep extensive lists of abbrevs that they load
+in every session.
@node Defining Abbrevs
@section Defining Abbrevs
@item C-x a i l
Define a word in the buffer as a mode-specific abbrev
(@code{inverse-add-mode-abbrev}).
+@item M-x define-global-abbrev @key{RET} @var{abbrev} @key{RET} @var{exp} @key{RET}
+Define @var{abbrev} as an abbrev expanding into @var{exp}.
+@item M-x define-mode-abbrev @key{RET} @var{abbrev} @key{RET} @var{exp} @key{RET}
+Define @var{abbrev} as a mode-specific abbrev expanding into @var{exp}.
@item M-x kill-all-abbrevs
-This command discards all abbrev definitions currently in effect,
-leaving a blank slate.
+Discard all abbrev definitions, leaving a blank slate.
@end table
@kindex C-x a g
@findex inverse-add-global-abbrev
@kindex C-x a i l
@findex inverse-add-mode-abbrev
- If the text already in the buffer is the abbrev, rather than its
-expansion, use command @kbd{C-x a i g}
-(@code{inverse-add-global-abbrev}) instead of @kbd{C-x a g}, or use
-@kbd{C-x a i l} (@code{inverse-add-mode-abbrev}) instead of @kbd{C-x a
-l}. These commands are called ``inverse'' because they invert the
-meaning of the two text strings they use (one from the buffer and one
-read with the minibuffer).
+ If the abbrev text itself is already in the buffer, you can use the
+commands @kbd{C-x a i g} (@code{inverse-add-global-abbrev}) and
+@kbd{C-x a i l} (@code{inverse-add-mode-abbrev}) to define it as an
+abbrev by specify the expansion in the minibuffer. These commands are
+called ``inverse'' because they invert the meaning of the two text
+strings they use (one from the buffer and one read with the
+minibuffer).
+
+@findex define-mode-abbrev
+@findex define-global-abbrev
+ You can define an abbrev without inserting either the abbrev or its
+expansion in the buffer using the command @code{define-global-abbrev}.
+It reads two arguments---the abbrev, and its expansion. The command
+@code{define-mode-abbrev} does likewise for a mode-specific abbrev.
To change the definition of an abbrev, just define a new definition.
When the abbrev has a prior definition, the abbrev definition commands
-ask for confirmation for replacing it.
-
- To remove an abbrev definition, give a negative argument to the abbrev
-definition command: @kbd{C-u - C-x a g} or @kbd{C-u - C-x a l}. The
-former removes a global definition, while the latter removes a
-mode-specific definition.
+ask for confirmation before replacing it.
@findex kill-all-abbrevs
- @kbd{M-x kill-all-abbrevs} removes all the abbrev definitions there
-are, both global and local.
+ To remove an abbrev definition, give a negative argument to the
+abbrev definition command: @kbd{C-u - C-x a g} or @kbd{C-u - C-x a l}.
+The former removes a global definition, while the latter removes a
+mode-specific definition. @kbd{M-x kill-all-abbrevs} removes all
+abbrev definitions, both global and local.
@node Expanding Abbrevs
@section Controlling Abbrev Expansion
(@key{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.
+insert it and then insert a punctuation or whitespace character to expand it.
@vindex abbrev-all-caps
Abbrev expansion preserves case; thus, @samp{foo} expands into @samp{find
outer otter}; @samp{Foo} into @samp{Find outer otter}, and @samp{FOO} into
@samp{FIND OUTER OTTER} or @samp{Find Outer Otter} according to the
-variable @code{abbrev-all-caps} (a non-@code{nil} value chooses the first
-of the two expansions).
+variable @code{abbrev-all-caps} (setting it non-@code{nil} specifies
+@samp{FIND OUTER OTTER}).
These commands are used to control abbrev expansion:
@kindex M-'
@findex abbrev-prefix-mark
- You may wish to expand an abbrev with a prefix attached; for example,
-if @samp{cnst} expands into @samp{construction}, you might want to use
-it to enter @samp{reconstruction}. It does not work to type
+ You may wish to expand an abbrev and attach a prefix to the expansion;
+for example, if @samp{cnst} expands into @samp{construction}, you might want
+to use it to enter @samp{reconstruction}. It does not work to type
@kbd{recnst}, because that is not necessarily a defined abbrev. What
you can do is use the command @kbd{M-'} (@code{abbrev-prefix-mark}) in
between the prefix @samp{re} and the abbrev @samp{cnst}. First, insert
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 @kbd{C-q}. Thus, @kbd{foo C-q ,} leaves @samp{foo,} in
-the buffer.
+the buffer, not expanding it.
@findex unexpand-abbrev
If you expand an abbrev by mistake, you can undo the expansion and
@table @kbd
@item M-x list-abbrevs
-Display a list of all abbrev definitions.
+Display a list of all abbrev definitions. With a numeric argument, list
+only local abbrevs.
@item M-x edit-abbrevs
Edit a list of abbrevs; you can add, alter or remove definitions.
@end table
The output from @kbd{M-x list-abbrevs} looks like this:
@example
+@var{various other tables@dots{}}
(lisp-mode-abbrev-table)
"dk" 0 "define-key"
(global-abbrev-table)
@findex read-abbrev-file
@findex quietly-read-abbrev-file
@vindex abbrev-file-name
- @kbd{M-x read-abbrev-file} reads a file name using the minibuffer and
-then reads the file, defining abbrevs according to the contents of the
-file. @kbd{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 @file{.emacs} file. If an
-empty argument is given to either of these functions, they use the file
-name specified in the variable @code{abbrev-file-name}, which is by
-default @code{"~/.abbrev_defs"}.
+ @kbd{M-x read-abbrev-file} reads a file name using the minibuffer
+and then reads the file, defining abbrevs according to the contents of
+the file. The function @code{quietly-read-abbrev-file} is similar
+except that it does not display a message in the echo area; you cannot
+invoke it interactively, and it is used primarily in the @file{.emacs}
+file. If either of these functions is called with @code{nil} as the
+argument, it uses the file name specified in the variable
+@code{abbrev-file-name}, which is by default @code{"~/.abbrev_defs"}.
+That file is your standard abbrev definition file, and Emacs loads
+abbrevs from it automatically when it starts up.
@vindex save-abbrevs
- Emacs will offer to save abbrevs automatically if you have changed any of
-them, whenever it offers to save all files (for @kbd{C-x s} or @kbd{C-x
-C-c}). This feature can be inhibited by setting the variable
-@code{save-abbrevs} to @code{nil}.
+ Emacs will offer to save abbrevs automatically if you have changed
+any of them, whenever it offers to save all files (for @kbd{C-x s} or
+@kbd{C-x C-c}). It saves them in the file specified by
+@code{abbrev-file-name}. This feature can be inhibited by setting the
+variable @code{save-abbrevs} to @code{nil}.
@findex insert-abbrevs
@findex define-abbrevs
The commands @kbd{M-x insert-abbrevs} and @kbd{M-x define-abbrevs} are
similar to the previous commands but work on text in an Emacs buffer.
-@kbd{M-x insert-abbrevs} inserts text into the current buffer before point,
+@kbd{M-x insert-abbrevs} inserts text into the current buffer after point,
describing all current abbrev definitions; @kbd{M-x define-abbrevs} parses
-the entire current buffer and defines abbrevs accordingly.@refill
+the entire current buffer and defines abbrevs accordingly.
@node Dynamic Abbrevs
@section Dynamic Abbrev Expansion
- The abbrev facility described above operates automatically as you insert
-text, but all abbrevs must be defined explicitly. By contrast,
-@dfn{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.
+ The abbrev facility described above operates automatically as you
+insert text, but all abbrevs must be defined explicitly. By contrast,
+@dfn{dynamic abbrevs} allow the meanings of abbreviations to be
+determined automatically from the contents of the buffer, but dynamic
+abbrev expansion happens only when you request it explicitly.
@kindex M-/
@kindex C-M-/
searches for an alternative expansion by looking farther back. After
scanning all the text before point, it searches the text after point.
The variable @code{dabbrev-limit}, if non-@code{nil}, specifies how far
-in the buffer to search for an expansion.
+away in the buffer to search for an expansion.
@vindex dabbrev-check-all-buffers
After scanning the current buffer, @kbd{M-/} normally searches other
buffers, unless you have set @code{dabbrev-check-all-buffers} to
@code{nil}.
-@vindex dabbrev-ignored-regexps
- A more fine control of the buffers that are scanned is possible by
-customizing the variable @code{dabbrev-ignored-regexps}, which should
-contain a list of regular expressions. Buffers matching a regular
-expression from that list are not searched.
+@vindex dabbrev-ignored-buffer-regexps
+ For finer control over which buffers to scan, customize the variable
+@code{dabbrev-ignored-buffer-regexps}. Its value is a list of regular
+expressions. If a buffer's name matches any of these regular
+expressions, dynamic abbrev expansion skips that buffer.
A negative argument to @kbd{M-/}, as in @kbd{C-u - M-/}, says to
-search first for expansions after point, and second for expansions
-before point. If you repeat the @kbd{M-/} to look for another
-expansion, do not specify an argument. This tries all the expansions
-after point and then the expansions before point.
+search first for expansions after point, then other buffers, and
+consider expansions before point only as a last resort. If you repeat
+the @kbd{M-/} to look for another expansion, do not specify an
+argument. Repeating @kbd{M-/} cycles through all the expansions after
+point and then the expansions before point.
After you have expanded a dynamic abbrev, you can copy additional
words that follow the expansion in its original context. Simply type
-@kbd{@key{SPC} M-/} for each word you want to copy. The spacing and
-punctuation between words is copied along with the words.
+@kbd{@key{SPC} M-/} for each additional word you want to copy. The
+spacing and punctuation between words is copied along with the words.
The command @kbd{C-M-/} (@code{dabbrev-completion}) performs
-completion of a dynamic abbreviation. Instead of trying the possible
-expansions one by one, it finds all of them, then inserts the text that
-they have in common. If they have nothing in common, @kbd{C-M-/}
+completion of a dynamic abbrev. Instead of trying the possible
+expansions one by one, it finds all of them, then inserts the text
+that they have in common. If they have nothing in common, @kbd{C-M-/}
displays a list of completions, from which you can select a choice in
the usual manner. @xref{Completion}.
@vindex dabbrev-case-fold-search
This feature is controlled by the variable
@code{dabbrev-case-fold-search}. If it is @code{t}, case is ignored in
-this search; if @code{nil}, the word and the expansion must match in
-case. If the value of @code{dabbrev-case-fold-search} is
+this search; if it is @code{nil}, the word and the expansion must match
+in case. If the value of @code{dabbrev-case-fold-search} is
@code{case-fold-search}, which is true by default, then the variable
@code{case-fold-search} controls whether to ignore case while searching
for expansions.
@vindex dabbrev-case-replace
- Normally, dynamic abbrev expansion preserves the case pattern @emph{of
-the abbrev you have typed}, by converting the expansion to that case
-pattern.
+ Normally, dynamic abbrev expansion preserves the case pattern
+@emph{of the dynamic abbrev you are expanding}, by converting the
+expansion to that case pattern.
@vindex dabbrev-case-fold-search
- The variable @code{dabbrev-case-replace} controls whether to preserve
-the case pattern of the abbrev. If it is @code{t}, the abbrev's case
-pattern is preserved in most cases; if @code{nil}, the expansion is
-always copied verbatim. If the value of @code{dabbrev-case-replace} is
-@code{case-replace}, which is true by default, then the variable
-@code{case-replace} controls whether to copy the expansion verbatim.
+ The variable @code{dabbrev-case-replace} controls whether to
+preserve the case pattern of the dynamic abbrev. If it is @code{t},
+the dynamic abbrev's case pattern is preserved in most cases; if it is
+@code{nil}, the expansion is always copied verbatim. If the value of
+@code{dabbrev-case-replace} is @code{case-replace}, which is true by
+default, then the variable @code{case-replace} controls whether to
+copy the expansion verbatim.
However, if the expansion contains a complex mixed case pattern, and
-the abbrev matches this pattern as far as it goes, then the expansion is
-always copied verbatim, regardless of those variables. Thus, for
-example, if the buffer contains @code{variableWithSillyCasePattern}, and
-you type @kbd{v a M-/}, it copies the expansion verbatim including its
-case pattern.
+the dynamic abbrev matches this pattern as far as it goes, then the
+expansion is always copied verbatim, regardless of those variables.
+Thus, for example, if the buffer contains
+@code{variableWithSillyCasePattern}, and you type @kbd{v a M-/}, it
+copies the expansion verbatim including its case pattern.
@vindex dabbrev-abbrev-char-regexp
The variable @code{dabbrev-abbrev-char-regexp}, if non-@code{nil},
purposes. The regular expression must match just one character, never
two or more. The same regular expression also determines which
characters are part of an expansion. The value @code{nil} has a special
-meaning: abbreviations are made of word characters, but expansions are
+meaning: dynamic abbrevs are made of word characters, but expansions are
made of word and symbol characters.
@vindex dabbrev-abbrev-skip-leading-regexp
In shell scripts and makefiles, a variable name is sometimes prefixed
with @samp{$} and sometimes not. Major modes for this kind of text can
-customize dynamic abbreviation to handle optional prefixes by setting
+customize dynamic abbrev expansion to handle optional prefixes by setting
the variable @code{dabbrev-abbrev-skip-leading-regexp}. Its value
should be a regular expression that matches the optional prefix that
-dynamic abbreviation should ignore.
+dynamic abbrev expression should ignore.
+
+@ignore
+ arch-tag: 638e0079-9540-48ec-9166-414083e16445
+@end ignore