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