428
+ − 1
444
+ − 2 @node Abbrevs, Picture, Running, Top
428
+ − 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)
440
+ − 189 "dk" 0 "define-key"
428
+ − 190 (global-abbrev-table)
440
+ − 191 "dfn" 0 "definition"
428
+ − 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
442
+ − 260 in the init file. @xref{Init File}. If you give an empty argument to
+ − 261 either of these functions, the file name Emacs uses is the value of the
+ − 262 variable @code{abbrev-file-name}, which is by default
+ − 263 @code{"~/.abbrev_defs"}.
428
+ − 264
+ − 265 @vindex save-abbrevs
+ − 266 Emacs offers to save abbrevs automatically if you have changed any of
+ − 267 them, whenever it offers to save all files (for @kbd{C-x s} or @kbd{C-x
+ − 268 C-c}). Set the variable @code{save-abbrevs} to @code{nil} to inhibit
+ − 269 this feature.
+ − 270
+ − 271 @findex insert-abbrevs
+ − 272 @findex define-abbrevs
+ − 273 The commands @kbd{M-x insert-abbrevs} and @kbd{M-x define-abbrevs} are
+ − 274 similar to the previous commands but work on text in an Emacs buffer.
+ − 275 @kbd{M-x insert-abbrevs} inserts text into the current buffer before point,
+ − 276 describing all current abbrev definitions; @kbd{M-x define-abbrevs} parses
+ − 277 the entire current buffer and defines abbrevs accordingly.@refill
+ − 278
+ − 279 @node Dynamic Abbrevs,, Saving Abbrevs, Abbrevs
+ − 280 @section Dynamic Abbrev Expansion
+ − 281
+ − 282 The abbrev facility described above operates automatically as you insert
+ − 283 text, but all abbrevs must be defined explicitly. By contrast,
+ − 284 @dfn{dynamic abbrevs} allow the meanings of abbrevs to be determined
+ − 285 automatically from the contents of the buffer, but dynamic abbrev expansion
+ − 286 happens only when you request it explicitly.
+ − 287
+ − 288 @kindex M-/
+ − 289 @findex dabbrev-expand
+ − 290 @table @kbd
+ − 291 @item M-/
+ − 292 Expand the word in the buffer before point as a @dfn{dynamic abbrev},
+ − 293 by searching in the buffer for words starting with that abbreviation
+ − 294 (@code{dabbrev-expand}).
+ − 295 @end table
+ − 296
+ − 297 For example, if the buffer contains @samp{does this follow } and you type
+ − 298 @kbd{f o M-/}, the effect is to insert @samp{follow} because that is the
+ − 299 last word in the buffer that starts with @samp{fo}. A numeric argument to
+ − 300 @kbd{M-/} says to take the second, third, etc.@: distinct expansion found
+ − 301 looking backward from point. Repeating @kbd{M-/} searches for an
+ − 302 alternative expansion by looking farther back. After the entire buffer
+ − 303 before point has been considered, the buffer after point is searched.
+ − 304
+ − 305 Dynamic abbrev expansion is completely independent of Abbrev mode; the
+ − 306 expansion of a word with @kbd{M-/} is completely independent of whether it
+ − 307 has a definition as an ordinary abbrev.
