(Fx_popup_menu): Add `else' to set Vmenu_updating_frame to nil
[emacs.git] / man / abbrevs.texi
blob2272b2ba133a6cd18b34ffe395edbd1992faf701
1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2002, 2003,
3 @c   2004, 2005 Free Software Foundation, Inc.
4 @c See file emacs.texi for copying conditions.
5 @node Abbrevs, Picture, Maintaining, Top
6 @chapter Abbrevs
7 @cindex abbrevs
8 @cindex expansion (of abbrevs)
10   A defined @dfn{abbrev} is a word which @dfn{expands}, if you insert
11 it, into some different text.  Abbrevs are defined by the user to expand
12 in specific ways.  For example, you might define @samp{foo} as an abbrev
13 expanding to @samp{find outer otter}.  Then you would be able to insert
14 @samp{find outer otter } into the buffer by typing @kbd{f o o
15 @key{SPC}}.
17   A second kind of abbreviation facility is called @dfn{dynamic abbrev
18 expansion}.  You use dynamic abbrev expansion with an explicit command
19 to expand the letters in the buffer before point by looking for other
20 words in the buffer that start with those letters.  @xref{Dynamic
21 Abbrevs}.
23 ``Hippie'' expansion generalizes abbreviation expansion.  @xref{Hippie
24 Expand, , Hippie Expansion, autotype, Features for Automatic
25 Typing}.
27 @menu
28 * Abbrev Concepts::   Fundamentals of defined abbrevs.
29 * Defining Abbrevs::  Defining an abbrev, so it will expand when typed.
30 * Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion.
31 * Editing Abbrevs::   Viewing or editing the entire list of defined abbrevs.
32 * Saving Abbrevs::    Saving the entire list of abbrevs for another session.
33 * Dynamic Abbrevs::   Abbreviations for words already in the buffer.
34 * Dabbrev Customization:: What is a word, for dynamic abbrevs.  Case handling.
35 @end menu
37 @node Abbrev Concepts
38 @section Abbrev Concepts
40   An @dfn{abbrev} is a word which has been defined to @dfn{expand} into
41 a specified @dfn{expansion}.  When you insert a word-separator character
42 following the abbrev, that expands the abbrev---replacing the abbrev
43 with its expansion.  For example, if @samp{foo} is defined as an abbrev
44 expanding to @samp{find outer otter}, then you can insert @samp{find
45 outer otter.} into the buffer by typing @kbd{f o o .}.
47 @findex abbrev-mode
48 @vindex abbrev-mode
49 @cindex Abbrev mode
50 @cindex mode, Abbrev
51   Abbrevs expand only when Abbrev mode (a minor mode) is enabled.
52 Disabling Abbrev mode does not cause abbrev definitions to be forgotten,
53 but they do not expand until Abbrev mode is enabled again.  The command
54 @kbd{M-x abbrev-mode} toggles Abbrev mode; with a numeric argument, it
55 turns Abbrev mode on if the argument is positive, off otherwise.
56 @xref{Minor Modes}.  @code{abbrev-mode} is also a variable; Abbrev mode is
57 on when the variable is non-@code{nil}.  The variable @code{abbrev-mode}
58 automatically becomes local to the current buffer when it is set.
60   Abbrev definitions can be @dfn{mode-specific}---active only in one major
61 mode.  Abbrevs can also have @dfn{global} definitions that are active in
62 all major modes.  The same abbrev can have a global definition and various
63 mode-specific definitions for different major modes.  A mode-specific
64 definition for the current major mode overrides a global definition.
66   Abbrevs can be defined interactively during the editing session.  Lists
67 of abbrev definitions can also be saved in files and reloaded in later
68 sessions.  Some users keep extensive lists of abbrevs that they load in
69 every session.
71 @node Defining Abbrevs
72 @section Defining Abbrevs
74 @table @kbd
75 @item C-x a g
76 Define an abbrev, using one or more words before point as its expansion
77 (@code{add-global-abbrev}).
78 @item C-x a l
79 Similar, but define an abbrev specific to the current major mode
80 (@code{add-mode-abbrev}).
81 @item C-x a i g
82 Define a word in the buffer as an abbrev (@code{inverse-add-global-abbrev}).
83 @item C-x a i l
84 Define a word in the buffer as a mode-specific abbrev
85 (@code{inverse-add-mode-abbrev}).
86 @item M-x define-global-abbrev @key{RET} @var{abbrev} @key{RET} @var{exp} @key{RET}
87 Define @var{abbrev} as an abbrev expanding into @var{exp}.
88 @item M-x define-mode-abbrev @key{RET} @var{abbrev} @key{RET} @var{exp} @key{RET}
89 Define @var{abbrev} as a mode-specific abbrev expanding into @var{exp}.
90 @item M-x kill-all-abbrevs
91 This command discards all abbrev definitions currently in effect,
92 leaving a blank slate.
93 @end table
95 @kindex C-x a g
96 @findex add-global-abbrev
97   The usual way to define an abbrev is to enter the text you want the
98 abbrev to expand to, position point after it, and type @kbd{C-x a g}
99 (@code{add-global-abbrev}).  This reads the abbrev itself using the
100 minibuffer, and then defines it as an abbrev for one or more words before
101 point.  Use a numeric argument to say how many words before point should be
102 taken as the expansion.  For example, to define the abbrev @samp{foo} as
103 mentioned above, insert the text @samp{find outer otter} and then type
104 @kbd{C-u 3 C-x a g f o o @key{RET}}.
106   An argument of zero to @kbd{C-x a g} means to use the contents of the
107 region as the expansion of the abbrev being defined.
109 @kindex C-x a l
110 @findex add-mode-abbrev
111   The command @kbd{C-x a l} (@code{add-mode-abbrev}) is similar, but
112 defines a mode-specific abbrev.  Mode-specific abbrevs are active only in a
113 particular major mode.  @kbd{C-x a l} defines an abbrev for the major mode
114 in effect at the time @kbd{C-x a l} is typed.  The arguments work the same
115 as for @kbd{C-x a g}.
117 @kindex C-x a i g
118 @findex inverse-add-global-abbrev
119 @kindex C-x a i l
120 @findex inverse-add-mode-abbrev
121   If the text already in the buffer is the abbrev, rather than its
122 expansion, use command @kbd{C-x a i g}
123 (@code{inverse-add-global-abbrev}) instead of @kbd{C-x a g}, or use
124 @kbd{C-x a i l} (@code{inverse-add-mode-abbrev}) instead of @kbd{C-x a
125 l}.  These commands are called ``inverse'' because they invert the
126 meaning of the two text strings they use (one from the buffer and one
127 read with the minibuffer).
129 @findex define-mode-abbrev
130 @findex define-global-abbrev
131   You can define an abbrev without inserting either the abbrev or its
132 expansion in the buffer using the command @code{define-global-abbrev}.
133 It reads two arguments---the abbrev, and its expansion.  The command
134 @code{define-mode-abbrev} does likewise for a mode-specific abbrev.
136   To change the definition of an abbrev, just define a new definition.
137 When the abbrev has a prior definition, the abbrev definition commands
138 ask for confirmation before replacing it.
140   To remove an abbrev definition, give a negative argument to the abbrev
141 definition command: @kbd{C-u - C-x a g} or @kbd{C-u - C-x a l}.  The
142 former removes a global definition, while the latter removes a
143 mode-specific definition.
145 @findex kill-all-abbrevs
146   @kbd{M-x kill-all-abbrevs} removes all the abbrev definitions there
147 are, both global and local.
149 @node Expanding Abbrevs
150 @section Controlling Abbrev Expansion
152   An abbrev expands whenever it is present in the buffer just before
153 point and you type a self-inserting whitespace or punctuation character
154 (@key{SPC}, comma, etc.@:).  More precisely, any character that is not a
155 word constituent expands an abbrev, and any word-constituent character
156 can be part of an abbrev.  The most common way to use an abbrev is to
157 insert it and then insert a punctuation or whitespace character to expand it.
159 @vindex abbrev-all-caps
160   Abbrev expansion preserves case; thus, @samp{foo} expands into @samp{find
161 outer otter}; @samp{Foo} into @samp{Find outer otter}, and @samp{FOO} into
162 @samp{FIND OUTER OTTER} or @samp{Find Outer Otter} according to the
163 variable @code{abbrev-all-caps} (setting it non-@code{nil} specifies
164 @samp{FIND OUTER OTTER}).
166   These commands are used to control abbrev expansion:
168 @table @kbd
169 @item M-'
170 Separate a prefix from a following abbrev to be expanded
171 (@code{abbrev-prefix-mark}).
172 @item C-x a e
173 @findex expand-abbrev
174 Expand the abbrev before point (@code{expand-abbrev}).
175 This is effective even when Abbrev mode is not enabled.
176 @item M-x expand-region-abbrevs
177 Expand some or all abbrevs found in the region.
178 @end table
180 @kindex M-'
181 @findex abbrev-prefix-mark
182   You may wish to expand an abbrev with a prefix attached; for example,
183 if @samp{cnst} expands into @samp{construction}, you might want to use
184 it to enter @samp{reconstruction}.  It does not work to type
185 @kbd{recnst}, because that is not necessarily a defined abbrev.  What
186 you can do is use the command @kbd{M-'} (@code{abbrev-prefix-mark}) in
187 between the prefix @samp{re} and the abbrev @samp{cnst}.  First, insert
188 @samp{re}.  Then type @kbd{M-'}; this inserts a hyphen in the buffer to
189 indicate that it has done its work.  Then insert the abbrev @samp{cnst};
190 the buffer now contains @samp{re-cnst}.  Now insert a non-word character
191 to expand the abbrev @samp{cnst} into @samp{construction}.  This
192 expansion step also deletes the hyphen that indicated @kbd{M-'} had been
193 used.  The result is the desired @samp{reconstruction}.
195   If you actually want the text of the abbrev in the buffer, rather than
196 its expansion, you can accomplish this by inserting the following
197 punctuation with @kbd{C-q}.  Thus, @kbd{foo C-q ,} leaves @samp{foo,} in
198 the buffer.
200 @findex unexpand-abbrev
201   If you expand an abbrev by mistake, you can undo the expansion and
202 bring back the abbrev itself by typing @kbd{C-_} to undo (@pxref{Undo}).
203 This also undoes the insertion of the non-word character that expanded
204 the abbrev.  If the result you want is the terminating non-word
205 character plus the unexpanded abbrev, you must reinsert the terminating
206 character, quoting it with @kbd{C-q}.  You can also use the command
207 @kbd{M-x unexpand-abbrev} to cancel the last expansion without
208 deleting the terminating character.
210 @findex expand-region-abbrevs
211   @kbd{M-x expand-region-abbrevs} searches through the region for defined
212 abbrevs, and for each one found offers to replace it with its expansion.
213 This command is useful if you have typed in text using abbrevs but forgot
214 to turn on Abbrev mode first.  It may also be useful together with a
215 special set of abbrev definitions for making several global replacements at
216 once.  This command is effective even if Abbrev mode is not enabled.
218   Expanding an abbrev runs the hook @code{pre-abbrev-expand-hook}
219 (@pxref{Hooks}).
221 @need 1500
222 @node Editing Abbrevs
223 @section Examining and Editing Abbrevs
225 @table @kbd
226 @item M-x list-abbrevs
227 Display a list of all abbrev definitions.  With a numeric argument, list
228 only local abbrevs.
229 @item M-x edit-abbrevs
230 Edit a list of abbrevs; you can add, alter or remove definitions.
231 @end table
233 @findex list-abbrevs
234   The output from @kbd{M-x list-abbrevs} looks like this:
236 @example
237 (lisp-mode-abbrev-table)
238 "dk"           0    "define-key"
239 (global-abbrev-table)
240 "dfn"          0    "definition"
241 @end example
243 @noindent
244 (Some blank lines of no semantic significance, and some other abbrev
245 tables, have been omitted.)
247   A line containing a name in parentheses is the header for abbrevs in a
248 particular abbrev table; @code{global-abbrev-table} contains all the global
249 abbrevs, and the other abbrev tables that are named after major modes
250 contain the mode-specific abbrevs.
252   Within each abbrev table, each nonblank line defines one abbrev.  The
253 word at the beginning of the line is the abbrev.  The number that
254 follows is the number of times the abbrev has been expanded.  Emacs
255 keeps track of this to help you see which abbrevs you actually use, so
256 that you can eliminate those that you don't use often.  The string at
257 the end of the line is the expansion.
259 @findex edit-abbrevs
260 @kindex C-c C-c @r{(Edit Abbrevs)}
261   @kbd{M-x edit-abbrevs} allows you to add, change or kill abbrev
262 definitions by editing a list of them in an Emacs buffer.  The list has
263 the same format described above.  The buffer of abbrevs is called
264 @samp{*Abbrevs*}, and is in Edit-Abbrevs mode.  Type @kbd{C-c C-c} in
265 this buffer to install the abbrev definitions as specified in the
266 buffer---and delete any abbrev definitions not listed.
268   The command @code{edit-abbrevs} is actually the same as
269 @code{list-abbrevs} except that it selects the buffer @samp{*Abbrevs*}
270 whereas @code{list-abbrevs} merely displays it in another window.
272 @node Saving Abbrevs
273 @section Saving Abbrevs
275   These commands allow you to keep abbrev definitions between editing
276 sessions.
278 @table @kbd
279 @item M-x write-abbrev-file @key{RET} @var{file} @key{RET}
280 Write a file @var{file} describing all defined abbrevs.
281 @item M-x read-abbrev-file @key{RET} @var{file} @key{RET}
282 Read the file @var{file} and define abbrevs as specified therein.
283 @item M-x quietly-read-abbrev-file @key{RET} @var{file} @key{RET}
284 Similar but do not display a message about what is going on.
285 @item M-x define-abbrevs
286 Define abbrevs from definitions in current buffer.
287 @item M-x insert-abbrevs
288 Insert all abbrevs and their expansions into current buffer.
289 @end table
291 @findex write-abbrev-file
292   @kbd{M-x write-abbrev-file} reads a file name using the minibuffer and
293 then writes a description of all current abbrev definitions into that
294 file.  This is used to save abbrev definitions for use in a later
295 session.  The text stored in the file is a series of Lisp expressions
296 that, when executed, define the same abbrevs that you currently have.
298 @findex read-abbrev-file
299 @findex quietly-read-abbrev-file
300 @vindex abbrev-file-name
301   @kbd{M-x read-abbrev-file} reads a file name using the minibuffer
302 and then reads the file, defining abbrevs according to the contents of
303 the file.  The function @code{quietly-read-abbrev-file} is similar
304 except that it does not display a message in the echo area; you cannot
305 invoke it interactively, and it is used primarily in the @file{.emacs}
306 file.  If either of these functions is called with @code{nil} as the
307 argument, it uses the file name specified in the variable
308 @code{abbrev-file-name}, which is by default @code{"~/.abbrev_defs"}.
309 That file is your standard abbrev definition file, and Emacs loads
310 abbrevs from it automatically when it starts up.
312 @vindex save-abbrevs
313   Emacs will offer to save abbrevs automatically if you have changed
314 any of them, whenever it offers to save all files (for @kbd{C-x s} or
315 @kbd{C-x C-c}).  It saves them in the file specified by
316 @code{abbrev-file-name}.  This feature can be inhibited by setting the
317 variable @code{save-abbrevs} to @code{nil}.
319 @findex insert-abbrevs
320 @findex define-abbrevs
321   The commands @kbd{M-x insert-abbrevs} and @kbd{M-x define-abbrevs} are
322 similar to the previous commands but work on text in an Emacs buffer.
323 @kbd{M-x insert-abbrevs} inserts text into the current buffer after point,
324 describing all current abbrev definitions; @kbd{M-x define-abbrevs} parses
325 the entire current buffer and defines abbrevs accordingly.@refill
327 @node Dynamic Abbrevs
328 @section Dynamic Abbrev Expansion
330   The abbrev facility described above operates automatically as you insert
331 text, but all abbrevs must be defined explicitly.  By contrast,
332 @dfn{dynamic abbrevs} allow the meanings of abbrevs to be determined
333 automatically from the contents of the buffer, but dynamic abbrev expansion
334 happens only when you request it explicitly.
336 @kindex M-/
337 @kindex C-M-/
338 @findex dabbrev-expand
339 @findex dabbrev-completion
340 @table @kbd
341 @item M-/
342 Expand the word in the buffer before point as a @dfn{dynamic abbrev},
343 by searching in the buffer for words starting with that abbreviation
344 (@code{dabbrev-expand}).
346 @item C-M-/
347 Complete the word before point as a dynamic abbrev
348 (@code{dabbrev-completion}).
349 @end table
351 @vindex dabbrev-limit
352   For example, if the buffer contains @samp{does this follow } and you
353 type @kbd{f o M-/}, the effect is to insert @samp{follow} because that
354 is the last word in the buffer that starts with @samp{fo}.  A numeric
355 argument to @kbd{M-/} says to take the second, third, etc.@: distinct
356 expansion found looking backward from point.  Repeating @kbd{M-/}
357 searches for an alternative expansion by looking farther back.  After
358 scanning all the text before point, it searches the text after point.
359 The variable @code{dabbrev-limit}, if non-@code{nil}, specifies how far
360 in the buffer to search for an expansion.
362 @vindex dabbrev-check-all-buffers
363   After scanning the current buffer, @kbd{M-/} normally searches other
364 buffers, unless you have set @code{dabbrev-check-all-buffers} to
365 @code{nil}.
367 @vindex dabbrev-ignored-buffer-regexps
368   For finer control over which buffers to scan, customize the variable
369 @code{dabbrev-ignored-buffer-regexps}.  Its value is a list of regular
370 expressions.  If a buffer's name matches any of these regular
371 expressions, dynamic abbrev expansion skips that buffer.
373   A negative argument to @kbd{M-/}, as in @kbd{C-u - M-/}, says to
374 search first for expansions after point, then other buffers, and
375 consider expansions before point only as a last resort.
377   If you repeat the @kbd{M-/} to look for another expansion, do not
378 specify an argument.  This tries all the expansions after point and
379 then the expansions before point.
381   After you have expanded a dynamic abbrev, you can copy additional
382 words that follow the expansion in its original context.  Simply type
383 @kbd{@key{SPC} M-/} for each word you want to copy.  The spacing and
384 punctuation between words is copied along with the words.
386   The command @kbd{C-M-/} (@code{dabbrev-completion}) performs
387 completion of a dynamic abbreviation.  Instead of trying the possible
388 expansions one by one, it finds all of them, then inserts the text that
389 they have in common.  If they have nothing in common, @kbd{C-M-/}
390 displays a list of completions, from which you can select a choice in
391 the usual manner.  @xref{Completion}.
393   Dynamic abbrev expansion is completely independent of Abbrev mode; the
394 expansion of a word with @kbd{M-/} is completely independent of whether
395 it has a definition as an ordinary abbrev.
397 @node Dabbrev Customization
398 @section Customizing Dynamic Abbreviation
400   Normally, dynamic abbrev expansion ignores case when searching for
401 expansions.  That is, the expansion need not agree in case with the word
402 you are expanding.
404 @vindex dabbrev-case-fold-search
405   This feature is controlled by the variable
406 @code{dabbrev-case-fold-search}.  If it is @code{t}, case is ignored in
407 this search; if it is @code{nil}, the word and the expansion must match
408 in case.  If the value of @code{dabbrev-case-fold-search} is
409 @code{case-fold-search}, which is true by default, then the variable
410 @code{case-fold-search} controls whether to ignore case while searching
411 for expansions.
413 @vindex dabbrev-case-replace
414   Normally, dynamic abbrev expansion preserves the case pattern @emph{of
415 the abbrev you have typed}, by converting the expansion to that case
416 pattern.
418 @vindex dabbrev-case-fold-search
419   The variable @code{dabbrev-case-replace} controls whether to preserve
420 the case pattern of the abbrev.  If it is @code{t}, the abbrev's case
421 pattern is preserved in most cases; if it is @code{nil}, the expansion is
422 always copied verbatim.  If the value of @code{dabbrev-case-replace} is
423 @code{case-replace}, which is true by default, then the variable
424 @code{case-replace} controls whether to copy the expansion verbatim.
426   However, if the expansion contains a complex mixed case pattern, and
427 the abbrev matches this pattern as far as it goes, then the expansion is
428 always copied verbatim, regardless of those variables.  Thus, for
429 example, if the buffer contains @code{variableWithSillyCasePattern}, and
430 you type @kbd{v a M-/}, it copies the expansion verbatim including its
431 case pattern.
433 @vindex dabbrev-abbrev-char-regexp
434   The variable @code{dabbrev-abbrev-char-regexp}, if non-@code{nil},
435 controls which characters are considered part of a word, for dynamic expansion
436 purposes.  The regular expression must match just one character, never
437 two or more.  The same regular expression also determines which
438 characters are part of an expansion.  The value @code{nil} has a special
439 meaning: abbreviations are made of word characters, but expansions are
440 made of word and symbol characters.
442 @vindex dabbrev-abbrev-skip-leading-regexp
443   In shell scripts and makefiles, a variable name is sometimes prefixed
444 with @samp{$} and sometimes not.  Major modes for this kind of text can
445 customize dynamic abbreviation to handle optional prefixes by setting
446 the variable @code{dabbrev-abbrev-skip-leading-regexp}.  Its value
447 should be a regular expression that matches the optional prefix that
448 dynamic abbreviation should ignore.
450 @ignore
451    arch-tag: 638e0079-9540-48ec-9166-414083e16445
452 @end ignore