Mercurial > emacs
annotate man/abbrevs.texi @ 31170:84ec8b66d634
(redisplay_internal): If considering all windows on all
frames, update the display for each frame as soon as possible,
instead of first building all desired matrices for all frames, and
then updating them all.
(try_cursor_movement): Handle case that last_cursor.vpos is -1.
author | Gerd Moellmann <gerd@gnu.org> |
---|---|
date | Fri, 25 Aug 2000 13:21:21 +0000 |
parents | ace4a0e50572 |
children | 3391551391df |
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 | |
30870 | 22 `Hippie' expansion generalizes abbreviation expansion. |
27208 | 23 @xref{Hippie Expand, `Hippie' Expansion, autotype, Features for |
24 Automatic Typing}. | |
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 | |
215 Display a list of all abbrev definitions. | |
216 @item M-x edit-abbrevs | |
217 Edit a list of abbrevs; you can add, alter or remove definitions. | |
218 @end table | |
219 | |
220 @findex list-abbrevs | |
221 The output from @kbd{M-x list-abbrevs} looks like this: | |
222 | |
223 @example | |
224 (lisp-mode-abbrev-table) | |
225 "dk" 0 "define-key" | |
226 (global-abbrev-table) | |
227 "dfn" 0 "definition" | |
228 @end example | |
229 | |
230 @noindent | |
231 (Some blank lines of no semantic significance, and some other abbrev | |
232 tables, have been omitted.) | |
233 | |
234 A line containing a name in parentheses is the header for abbrevs in a | |
235 particular abbrev table; @code{global-abbrev-table} contains all the global | |
236 abbrevs, and the other abbrev tables that are named after major modes | |
237 contain the mode-specific abbrevs. | |
238 | |
239 Within each abbrev table, each nonblank line defines one abbrev. The | |
240 word at the beginning of the line is the abbrev. The number that | |
241 follows is the number of times the abbrev has been expanded. Emacs | |
242 keeps track of this to help you see which abbrevs you actually use, so | |
243 that you can eliminate those that you don't use often. The string at | |
244 the end of the line is the expansion. | |
245 | |
246 @findex edit-abbrevs | |
247 @kindex C-c C-c @r{(Edit Abbrevs)} | |
248 @kbd{M-x edit-abbrevs} allows you to add, change or kill abbrev | |
249 definitions by editing a list of them in an Emacs buffer. The list has | |
250 the same format described above. The buffer of abbrevs is called | |
251 @samp{*Abbrevs*}, and is in Edit-Abbrevs mode. Type @kbd{C-c C-c} in | |
252 this buffer to install the abbrev definitions as specified in the | |
253 buffer---and delete any abbrev definitions not listed. | |
254 | |
255 The command @code{edit-abbrevs} is actually the same as | |
256 @code{list-abbrevs} except that it selects the buffer @samp{*Abbrevs*} | |
257 whereas @code{list-abbrevs} merely displays it in another window. | |
258 | |
259 @node Saving Abbrevs | |
260 @section Saving Abbrevs | |
261 | |
262 These commands allow you to keep abbrev definitions between editing | |
263 sessions. | |
264 | |
265 @table @kbd | |
266 @item M-x write-abbrev-file @key{RET} @var{file} @key{RET} | |
267 Write a file @var{file} describing all defined abbrevs. | |
268 @item M-x read-abbrev-file @key{RET} @var{file} @key{RET} | |
269 Read the file @var{file} and define abbrevs as specified therein. | |
270 @item M-x quietly-read-abbrev-file @key{RET} @var{file} @key{RET} | |
271 Similar but do not display a message about what is going on. | |
272 @item M-x define-abbrevs | |
273 Define abbrevs from definitions in current buffer. | |
274 @item M-x insert-abbrevs | |
275 Insert all abbrevs and their expansions into current buffer. | |
276 @end table | |
277 | |
278 @findex write-abbrev-file | |
279 @kbd{M-x write-abbrev-file} reads a file name using the minibuffer and | |
280 then writes a description of all current abbrev definitions into that | |
281 file. This is used to save abbrev definitions for use in a later | |
282 session. The text stored in the file is a series of Lisp expressions | |
283 that, when executed, define the same abbrevs that you currently have. | |
284 | |
285 @findex read-abbrev-file | |
286 @findex quietly-read-abbrev-file | |
287 @vindex abbrev-file-name | |
288 @kbd{M-x read-abbrev-file} reads a file name using the minibuffer and | |
289 then reads the file, defining abbrevs according to the contents of the | |
290 file. @kbd{M-x quietly-read-abbrev-file} is the same except that it | |
291 does not display a message in the echo area saying that it is doing its | |
292 work; it is actually useful primarily in the @file{.emacs} file. If an | |
293 empty argument is given to either of these functions, they use the file | |
294 name specified in the variable @code{abbrev-file-name}, which is by | |
295 default @code{"~/.abbrev_defs"}. | |
296 | |
297 @vindex save-abbrevs | |
298 Emacs will offer to save abbrevs automatically if you have changed any of | |
299 them, whenever it offers to save all files (for @kbd{C-x s} or @kbd{C-x | |
300 C-c}). This feature can be inhibited by setting the variable | |
301 @code{save-abbrevs} to @code{nil}. | |
302 | |
303 @findex insert-abbrevs | |
304 @findex define-abbrevs | |
305 The commands @kbd{M-x insert-abbrevs} and @kbd{M-x define-abbrevs} are | |
306 similar to the previous commands but work on text in an Emacs buffer. | |
307 @kbd{M-x insert-abbrevs} inserts text into the current buffer before point, | |
308 describing all current abbrev definitions; @kbd{M-x define-abbrevs} parses | |
309 the entire current buffer and defines abbrevs accordingly.@refill | |
310 | |
311 @node Dynamic Abbrevs | |
312 @section Dynamic Abbrev Expansion | |
313 | |
314 The abbrev facility described above operates automatically as you insert | |
315 text, but all abbrevs must be defined explicitly. By contrast, | |
316 @dfn{dynamic abbrevs} allow the meanings of abbrevs to be determined | |
317 automatically from the contents of the buffer, but dynamic abbrev expansion | |
318 happens only when you request it explicitly. | |
319 | |
320 @kindex M-/ | |
321 @kindex C-M-/ | |
322 @findex dabbrev-expand | |
323 @findex dabbrev-completion | |
324 @table @kbd | |
325 @item M-/ | |
326 Expand the word in the buffer before point as a @dfn{dynamic abbrev}, | |
327 by searching in the buffer for words starting with that abbreviation | |
328 (@code{dabbrev-expand}). | |
329 | |
330 @item C-M-/ | |
331 Complete the word before point as a dynamic abbrev | |
332 (@code{dabbrev-completion}). | |
333 @end table | |
334 | |
335 @vindex dabbrev-limit | |
336 For example, if the buffer contains @samp{does this follow } and you | |
337 type @kbd{f o M-/}, the effect is to insert @samp{follow} because that | |
338 is the last word in the buffer that starts with @samp{fo}. A numeric | |
339 argument to @kbd{M-/} says to take the second, third, etc.@: distinct | |
340 expansion found looking backward from point. Repeating @kbd{M-/} | |
341 searches for an alternative expansion by looking farther back. After | |
342 scanning all the text before point, it searches the text after point. | |
343 The variable @code{dabbrev-limit}, if non-@code{nil}, specifies how far | |
344 in the buffer to search for an expansion. | |
345 | |
346 @vindex dabbrev-check-all-buffers | |
347 After scanning the current buffer, @kbd{M-/} normally searches other | |
348 buffers, unless you have set @code{dabbrev-check-all-buffers} to | |
349 @code{nil}. | |
350 | |
31079 | 351 @vindex dabbrev-ignored-regexps |
31069
8cbeffd70393
Document dabbrev-ignore-regexps.
Eli Zaretskii <eliz@gnu.org>
parents:
30870
diff
changeset
|
352 A more fine control on which buffers are scanned is possible by |
31079 | 353 customizing the variable @code{dabbrev-ignored-regexps}, whch should |
31069
8cbeffd70393
Document dabbrev-ignore-regexps.
Eli Zaretskii <eliz@gnu.org>
parents:
30870
diff
changeset
|
354 contain a list of regular expressions. Buffers matching a regular |
8cbeffd70393
Document dabbrev-ignore-regexps.
Eli Zaretskii <eliz@gnu.org>
parents:
30870
diff
changeset
|
355 expression from that list are not searched. |
8cbeffd70393
Document dabbrev-ignore-regexps.
Eli Zaretskii <eliz@gnu.org>
parents:
30870
diff
changeset
|
356 |
25829 | 357 A negative argument to @kbd{M-/}, as in @kbd{C-u - M-/}, says to |
358 search first for expansions after point, and second for expansions | |
359 before point. If you repeat the @kbd{M-/} to look for another | |
360 expansion, do not specify an argument. This tries all the expansions | |
361 after point and then the expansions before point. | |
362 | |
363 After you have expanded a dynamic abbrev, you can copy additional | |
364 words that follow the expansion in its original context. Simply type | |
365 @kbd{@key{SPC} M-/} for each word you want to copy. The spacing and | |
366 punctuation between words is copied along with the words. | |
367 | |
368 The command @kbd{C-M-/} (@code{dabbrev-completion}) performs | |
369 completion of a dynamic abbreviation. Instead of trying the possible | |
370 expansions one by one, it finds all of them, then inserts the text that | |
371 they have in common. If they have nothing in common, @kbd{C-M-/} | |
372 displays a list of completions, from which you can select a choice in | |
373 the usual manner. @xref{Completion}. | |
374 | |
375 Dynamic abbrev expansion is completely independent of Abbrev mode; the | |
376 expansion of a word with @kbd{M-/} is completely independent of whether | |
377 it has a definition as an ordinary abbrev. | |
378 | |
379 @node Dabbrev Customization | |
380 @section Customizing Dynamic Abbreviation | |
381 | |
382 Normally, dynamic abbrev expansion ignores case when searching for | |
383 expansions. That is, the expansion need not agree in case with the word | |
384 you are expanding. | |
385 | |
386 @vindex dabbrev-case-fold-search | |
387 This feature is controlled by the variable | |
388 @code{dabbrev-case-fold-search}. If it is @code{t}, case is ignored in | |
389 this search; if @code{nil}, the word and the expansion must match in | |
390 case. If the value of @code{dabbrev-case-fold-search} is | |
391 @code{case-fold-search}, which is true by default, then the variable | |
392 @code{case-fold-search} controls whether to ignore case while searching | |
393 for expansions. | |
394 | |
395 @vindex dabbrev-case-replace | |
396 Normally, dynamic abbrev expansion preserves the case pattern @emph{of | |
397 the abbrev you have typed}, by converting the expansion to that case | |
398 pattern. | |
399 | |
400 @vindex dabbrev-case-fold-search | |
401 The variable @code{dabbrev-case-replace} controls whether to preserve | |
402 the case pattern of the abbrev. If it is @code{t}, the abbrev's case | |
403 pattern is preserved in most cases; if @code{nil}, the expansion is | |
404 always copied verbatim. If the value of @code{dabbrev-case-replace} is | |
405 @code{case-replace}, which is true by default, then the variable | |
406 @code{case-replace} controls whether to copy the expansion verbatim. | |
407 | |
408 However, if the expansion contains a complex mixed case pattern, and | |
409 the abbrev matches this pattern as far as it goes, then the expansion is | |
410 always copied verbatim, regardless of those variables. Thus, for | |
411 example, if the buffer contains @code{variableWithSillyCasePattern}, and | |
412 you type @kbd{v a M-/}, it copies the expansion verbatim including its | |
413 case pattern. | |
414 | |
415 @vindex dabbrev-abbrev-char-regexp | |
416 The variable @code{dabbrev-abbrev-char-regexp}, if non-@code{nil}, | |
417 controls which characters are considered part of a word, for dynamic expansion | |
418 purposes. The regular expression must match just one character, never | |
419 two or more. The same regular expression also determines which | |
420 characters are part of an expansion. The value @code{nil} has a special | |
421 meaning: abbreviations are made of word characters, but expansions are | |
422 made of word and symbol characters. | |
423 | |
424 @vindex dabbrev-abbrev-skip-leading-regexp | |
425 In shell scripts and makefiles, a variable name is sometimes prefixed | |
426 with @samp{$} and sometimes not. Major modes for this kind of text can | |
427 customize dynamic abbreviation to handle optional prefixes by setting | |
428 the variable @code{dabbrev-abbrev-skip-leading-regexp}. Its value | |
429 should be a regular expression that matches the optional prefix that | |
430 dynamic abbreviation should ignore. |