Mercurial > hg > xemacs-beta

comparison man/xemacs/abbrevs.texi @ 0:376386a54a3c r19-14

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r19-14
author cvs
date Mon, 13 Aug 2007 08:45:50 +0200
parents
children 5a79be0ef6a8
comparison
equal deleted inserted replaced
-1:000000000000 0:376386a54a3c
1
2 @node Abbrevs, Picture, Running, Top
3 @chapter Abbrevs
4 @cindex abbrevs
5 @cindex expansion (of abbrevs)
6
7 An @dfn{abbrev} is a word which @dfn{expands} into some
8 different text. Abbrevs are defined by the user to expand in specific
9 ways. For example, you might define @samp{foo} as an abbrev expanding to
10 @samp{find outer otter}. With this abbrev defined, you would be able to
11 get @samp{find outer otter } into the buffer by typing @kbd{f o o @key{SPC}}.
12
13 @findex abbrev-mode
14 @vindex abbrev-mode
15 Abbrevs expand only when Abbrev mode (a minor mode) is enabled.
16 Disabling Abbrev mode does not cause abbrev definitions to be discarded,
17 but they do not expand until Abbrev mode is enabled again. The command
18 @kbd{M-x abbrev-mode} toggles Abbrev mode; with a numeric argument, it
19 turns Abbrev mode on if the argument is positive, off otherwise.
20 @xref{Minor Modes}. @code{abbrev-mode} is also a variable; Abbrev mode is
21 on when the variable is non-@code{nil}. The variable @code{abbrev-mode}
22 automatically becomes local to the current buffer when it is set.
23
24 Abbrev definitions can be @dfn{mode-specific}---active only in one major
25 mode. Abbrevs can also have @dfn{global} definitions that are active in
26 all major modes. The same abbrev can have a global definition and various
27 mode-specific definitions for different major modes. A mode-specific
28 definition for the current major mode overrides a global definition.
29
30 You can define Abbrevs interactively during an editing session. You
31 can also save lists of abbrev definitions in files and reload them in later
32 sessions. Some users keep extensive lists of abbrevs that they load in
33 every session.
34
35 A second kind of abbreviation facility is called the @dfn{dynamic
36 expansion}. Dynamic abbrev expansion happens only when you give an
37 explicit command and the result of the expansion depends only on the
38 current contents of the buffer. @xref{Dynamic Abbrevs}.
39
40 @menu
41 * Defining Abbrevs:: Defining an abbrev, so it will expand when typed.
42 * Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion.
43 * Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs.
44 * Saving Abbrevs:: Saving the entire list of abbrevs for another session.
45 * Dynamic Abbrevs:: Abbreviations for words already in the buffer.
46 @end menu
47
48 @node Defining Abbrevs, Expanding Abbrevs, Abbrevs, Abbrevs
49 @section Defining Abbrevs
50
51 @table @kbd
52 @item C-x a g
53 Define an abbrev to expand into some text before point
54 (@code{add-global-abbrev}).
55 @item C-x a l
56 Similar, but define an abbrev available only in the current major mode
57 (@code{add-mode-abbrev}).
58 @item C-x a i g
59 Define a word in the buffer as an abbrev (@code{inverse-add-global-abbrev}).
60 @item C-x a i l
61 Define a word in the buffer as a mode-specific abbrev
62 (@code{inverse-add-mode-abbrev}).
63 @item M-x kill-all-abbrevs
64 After this command, no abbrev definitions remain in effect.
65 @end table
66
67 @kindex C-x a g
68 @findex add-global-abbrev
69 The usual way to define an abbrev is to enter the text you want the
70 abbrev to expand to, position point after it, and type @kbd{C-x a g}
71 (@code{add-global-abbrev}). This reads the abbrev itself using the
72 minibuffer, and then defines it as an abbrev for one or more words
73 before point. Use a numeric argument to say how many words before point
74 should be taken as the expansion. For example, to define the abbrev
75 @samp{foo} as in the example above, insert the text @samp{find outer
76 otter}, then type @*@kbd{C-u 3 C-x a g f o o @key{RET}}.
77
78 An argument of zero to @kbd{C-x a g} means to use the contents of the
79 region as the expansion of the abbrev being defined.
80
81 @kindex C-x a l
82 @findex add-mode-abbrev
83 The command @kbd{C-x a l} (@code{add-mode-abbrev}) is similar, but
84 defines a mode-specific abbrev. Mode-specific abbrevs are active only in a
85 particular major mode. @kbd{C-x a l} defines an abbrev for the major mode
86 in effect at the time @kbd{C-x a l} is typed. The arguments work the
87 same way they do for @kbd{C-x a g}.
88
89 @kindex C-x a i g
90 @findex inverse-add-global-abbrev
91 @kindex C-x a i l
92 @findex inverse-add-mode-abbrev
93 If the text of an abbrev you want is already in the buffer instead of
94 the expansion, use command @kbd{C-x a i g} (@code{inverse-add-global-abbrev})
95 instead of @kbd{C-x a g}, or use @kbd{C-x a i l}
96 (@code{inverse-add-mode-abbrev}) instead of @kbd{C-x a l}. These commands
97 are called ``inverse'' because they invert the meaning of the argument
98 found in the buffer and the argument read using the minibuffer.@refill
99
100 To change the definition of an abbrev, just add the new definition. You
101 will be asked to confirm if the abbrev has a prior definition. To remove
102 an abbrev definition, give a negative argument to @kbd{C-x a g} or @kbd{C-x
103 a l}. You must choose the command to specify whether to kill a global
104 definition or a mode-specific definition for the current mode, since those
105 two definitions are independent for one abbrev.
106
107 @findex kill-all-abbrevs
108 @kbd{M-x kill-all-abbrevs} removes all existing abbrev definitions.
109
110 @node Expanding Abbrevs, Editing Abbrevs, Defining Abbrevs, Abbrevs
111 @section Controlling Abbrev Expansion
112
113 An abbrev expands whenever it is in a buffer just before point and you
114 type a self-inserting punctuation character (@key{SPC}, comma,
115 etc.@:). Most often an abbrev is used by inserting the abbrev followed
116 by punctuation.
117
118 @vindex abbrev-all-caps
119 Abbrev expansion preserves case; thus, @samp{foo} expands into @samp{find
120 outer otter}, @samp{Foo} into @samp{Find outer otter}, and @samp{FOO} into
121 @samp{FIND OUTER OTTER} or @samp{Find Outer Otter} according to the
122 variable @code{abbrev-all-caps} (a non-@code{nil} value chooses the first
123 of the two expansions).@refill
124
125 Two commands are available to control abbrev expansion:
126
127 @table @kbd
128 @item M-'
129 Separate a prefix from a following abbrev to be expanded
130 (@code{abbrev-prefix-mark}).
131 @item C-x a e
132 @findex expand-abbrev
133 Expand the abbrev before point (@code{expand-abbrev}).
134 This is effective even when Abbrev mode is not enabled.
135 @item M-x unexpand-abbrev
136 Undo last abbrev expansion.
137 @item M-x expand-region-abbrevs
138 Expand some or all abbrevs found in the region.
139 @end table
140
141 @kindex M-'
142 @findex abbrev-prefix-mark
143 You may wish to expand an abbrev with a prefix attached. For example,
144 if @samp{cnst} expands into @samp{construction}, you may want to use it
145 to enter @samp{reconstruction}. It does not work to type @kbd{recnst},
146 because that is not necessarily a defined abbrev. Instead, you can use
147 the command @kbd{M-'} (@code{abbrev-prefix-mark}) between the prefix
148 @samp{re} and the abbrev @samp{cnst}. First, insert @samp{re}. Then
149 type @kbd{M-'}; this inserts a minus sign in the buffer to indicate that
150 it has done its work. Then insert the abbrev @samp{cnst}. The buffer
151 now contains @samp{re-cnst}. Now insert a punctuation character to
152 expand the abbrev @samp{cnst} into @samp{construction}. The minus sign
153 is deleted at this point by @kbd{M-'}. The resulting text is the
154 desired @samp{reconstruction}.@refill
155
156 If you actually want the text of the abbrev in the buffer, rather than
157 its expansion, insert the following punctuation with @kbd{C-q}. Thus,
158 @kbd{foo C-q -} leaves @samp{foo-} in the buffer.
159
160 @findex unexpand-abbrev
161 If you expand an abbrev by mistake, you can undo the expansion (replace
162 the expansion by the original abbrev text) with @kbd{M-x unexpand-abbrev}.
163 You can also use @kbd{C-_} (@code{undo}) to undo the expansion; but that
164 will first undo the insertion of the punctuation character.
165
166 @findex expand-region-abbrevs
167 @kbd{M-x expand-region-abbrevs} searches through the region for defined
168 abbrevs, and offers to replace each one it finds with its expansion.
169 This command is useful if you have typed text using abbrevs but forgot
170 to turn on Abbrev mode first. It may also be useful together with a
171 special set of abbrev definitions for making several global replacements at
172 once. The command is effective even if Abbrev mode is not enabled.
173
174 @node Editing Abbrevs, Saving Abbrevs, Expanding Abbrevs, Abbrevs
175 @section Examining and Editing Abbrevs
176
177 @table @kbd
178 @item M-x list-abbrevs
179 Print a list of all abbrev definitions.
180 @item M-x edit-abbrevs
181 Edit a list of abbrevs; you can add, alter, or remove definitions.
182 @end table
183
184 @findex list-abbrevs
185 The output from @kbd{M-x list-abbrevs} looks like this:
186
187 @example
188 (lisp-mode-abbrev-table)
189 "dk" 0 "define-key"
190 (global-abbrev-table)
191 "dfn" 0 "definition"
192 @end example
193
194 @noindent
195 (Some blank lines of no semantic significance, and some other abbrev
196 tables, have been omitted.)
197
198 A line containing a name in parentheses is the header for abbrevs in a
199 particular abbrev table; @code{global-abbrev-table} contains all the global
200 abbrevs, and the other abbrev tables that are named after major modes
201 contain the mode-specific abbrevs.
202
203 Within each abbrev table, each non-blank line defines one abbrev. The
204 word at the beginning is the abbrev. The number that appears is the number
205 of times the abbrev has been expanded. Emacs keeps track of this to help
206 you see which abbrevs you actually use, in case you want to eliminate
207 those that you don't use often. The string at the end of the line is the
208 expansion.
209
210 @findex edit-abbrevs
211 @kindex C-c C-c (Edit Abbrevs)
212 @findex edit-abbrevs-redefine
213 @kbd{M-x edit-abbrevs} allows you to add, change or kill abbrev
214 definitions by editing a list of them in an Emacs buffer. The list has
215 the format described above. The buffer of abbrevs is called
216 @samp{*Abbrevs*}, and is in Edit-Abbrevs mode. This mode redefines the
217 key @kbd{C-c C-c} to install the abbrev definitions as specified in the
218 buffer. The @code{edit-abbrevs-redefine} command does this.
219 Any abbrevs not described in the buffer are eliminated when this is
220 done.
221
222 @code{edit-abbrevs} is actually the same as @code{list-abbrevs}, except
223 that it selects the buffer @samp{*Abbrevs*} whereas @code{list-abbrevs}
224 merely displays it in another window.
225
226 @node Saving Abbrevs, Dynamic Abbrevs, Editing Abbrevs, Abbrevs
227 @section Saving Abbrevs
228
229 These commands allow you to keep abbrev definitions between editing
230 sessions.
231
232 @table @kbd
233 @item M-x write-abbrev-file
234 Write a file describing all defined abbrevs.
235 @item M-x read-abbrev-file
236 Read such an abbrev file and define abbrevs as specified there.
237 @item M-x quietly-read-abbrev-file
238 Similar, but do not display a message about what is going on.
239 @item M-x define-abbrevs
240 Define abbrevs from buffer.
241 @item M-x insert-abbrevs
242 Insert all abbrevs and their expansions into the buffer.
243 @end table
244
245 @findex write-abbrev-file
246 Use @kbd{M-x write-abbrev-file} to save abbrev definitions for use in
247 a later session. The command reads a file name using the minibuffer and
248 writes a description of all current abbrev definitions into the
249 specified file. The text stored in the file looks like the output of
250 @kbd{M-x list-abbrevs}.
251
252
253 @findex read-abbrev-file
254 @findex quietly-read-abbrev-file
255 @vindex abbrev-file-name
256 @kbd{M-x read-abbrev-file} prompts for a file name using the
257 minibuffer and reads the specified file, defining abbrevs according to
258 its contents. @kbd{M-x quietly-read-abbrev-file} is the same but does
259 not display a message in the echo area; it is actually useful primarily
260 in the @file{.emacs} file. If you give an empty argument to either of
261 these functions, the file name Emacs uses is the value of the variable
262 @code{abbrev-file-name}, which is by default @code{"~/.abbrev_defs"}.
263
264 @vindex save-abbrevs
265 Emacs offers to save abbrevs automatically if you have changed any of
266 them, whenever it offers to save all files (for @kbd{C-x s} or @kbd{C-x
267 C-c}). Set the variable @code{save-abbrevs} to @code{nil} to inhibit
268 this feature.
269
270 @findex insert-abbrevs
271 @findex define-abbrevs
272 The commands @kbd{M-x insert-abbrevs} and @kbd{M-x define-abbrevs} are
273 similar to the previous commands but work on text in an Emacs buffer.
274 @kbd{M-x insert-abbrevs} inserts text into the current buffer before point,
275 describing all current abbrev definitions; @kbd{M-x define-abbrevs} parses
276 the entire current buffer and defines abbrevs accordingly.@refill
277
278 @node Dynamic Abbrevs,, Saving Abbrevs, Abbrevs
279 @section Dynamic Abbrev Expansion
280
281 The abbrev facility described above operates automatically as you insert
282 text, but all abbrevs must be defined explicitly. By contrast,
283 @dfn{dynamic abbrevs} allow the meanings of abbrevs to be determined
284 automatically from the contents of the buffer, but dynamic abbrev expansion
285 happens only when you request it explicitly.
286
287 @kindex M-/
288 @findex dabbrev-expand
289 @table @kbd
290 @item M-/
291 Expand the word in the buffer before point as a @dfn{dynamic abbrev},
292 by searching in the buffer for words starting with that abbreviation
293 (@code{dabbrev-expand}).
294 @end table
295
296 For example, if the buffer contains @samp{does this follow } and you type
297 @kbd{f o M-/}, the effect is to insert @samp{follow} because that is the
298 last word in the buffer that starts with @samp{fo}. A numeric argument to
299 @kbd{M-/} says to take the second, third, etc.@: distinct expansion found
300 looking backward from point. Repeating @kbd{M-/} searches for an
301 alternative expansion by looking farther back. After the entire buffer
302 before point has been considered, the buffer after point is searched.
303
304 Dynamic abbrev expansion is completely independent of Abbrev mode; the
305 expansion of a word with @kbd{M-/} is completely independent of whether it
306 has a definition as an ordinary abbrev.