# HG changeset patch # User Glenn Morris # Date 1189053198 0 # Node ID e63412272a449a0ab4f1e27924c49333dc705034 # Parent 2d390f81907d78e900ccd2dd343e7f72431ccc06 Move to ../doc/emacs/, misc/ diff -r 2d390f81907d -r e63412272a44 man/abbrevs.texi --- a/man/abbrevs.texi Thu Sep 06 04:33:12 2007 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,457 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, 2003, -@c 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Abbrevs -@chapter Abbrevs -@cindex abbrevs -@cindex expansion (of abbrevs) - - A defined @dfn{abbrev} is a word which @dfn{expands}, if you insert -it, into some different text. Abbrevs are defined by the user to expand -in specific ways. For example, you might define @samp{foo} as an abbrev -expanding to @samp{find outer otter}. Then you could insert -@samp{find outer otter } into the buffer by typing @kbd{f o o -@key{SPC}}. - - A second kind of abbreviation facility is called @dfn{dynamic abbrev -expansion}. You use dynamic abbrev expansion with an explicit command -to expand the letters in the buffer before point by looking for other -words in the buffer that start with those letters. @xref{Dynamic -Abbrevs}. - - ``Hippie'' expansion generalizes abbreviation expansion. -@xref{Hippie Expand, , Hippie Expansion, autotype, Features for -Automatic Typing}. - -@menu -* Abbrev Concepts:: Fundamentals of defined abbrevs. -* Defining Abbrevs:: Defining an abbrev, so it will expand when typed. -* Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion. -* Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs. -* Saving Abbrevs:: Saving the entire list of abbrevs for another session. -* Dynamic Abbrevs:: Abbreviations for words already in the buffer. -* Dabbrev Customization:: What is a word, for dynamic abbrevs. Case handling. -@end menu - -@node Abbrev Concepts -@section Abbrev Concepts - - An @dfn{abbrev} is a word which has been defined to @dfn{expand} into -a specified @dfn{expansion}. When you insert a word-separator character -following the abbrev, that expands the abbrev---replacing the abbrev -with its expansion. For example, if @samp{foo} is defined as an abbrev -expanding to @samp{find outer otter}, then you can insert @samp{find -outer otter.} into the buffer by typing @kbd{f o o .}. - -@findex abbrev-mode -@vindex abbrev-mode -@cindex Abbrev mode -@cindex mode, Abbrev - Abbrevs expand only when Abbrev mode (a minor mode) is enabled. -Disabling Abbrev mode does not cause abbrev definitions to be forgotten, -but they do not expand until Abbrev mode is enabled again. The command -@kbd{M-x abbrev-mode} toggles Abbrev mode; with a numeric argument, it -turns Abbrev mode on if the argument is positive, off otherwise. -@xref{Minor Modes}. @code{abbrev-mode} is also a variable; Abbrev mode is -on when the variable is non-@code{nil}. The variable @code{abbrev-mode} -automatically becomes local to the current buffer when it is set. - - Abbrevs can have @dfn{mode-specific} definitions, active only in one major -mode. Abbrevs can also have @dfn{global} definitions that are active in -all major modes. The same abbrev can have a global definition and various -mode-specific definitions for different major modes. A mode-specific -definition for the current major mode overrides a global definition. - - You can define abbrevs interactively during the editing session. You -can also save lists of abbrev definitions in files for use in later -sessions. Some users keep extensive lists of abbrevs that they load -in every session. - -@node Defining Abbrevs -@section Defining Abbrevs - -@table @kbd -@item C-x a g -Define an abbrev, using one or more words before point as its expansion -(@code{add-global-abbrev}). -@item C-x a l -Similar, but define an abbrev specific to the current major mode -(@code{add-mode-abbrev}). -@item C-x a i g -Define a word in the buffer as an abbrev (@code{inverse-add-global-abbrev}). -@item C-x a i l -Define a word in the buffer as a mode-specific abbrev -(@code{inverse-add-mode-abbrev}). -@item M-x define-global-abbrev @key{RET} @var{abbrev} @key{RET} @var{exp} @key{RET} -Define @var{abbrev} as an abbrev expanding into @var{exp}. -@item M-x define-mode-abbrev @key{RET} @var{abbrev} @key{RET} @var{exp} @key{RET} -Define @var{abbrev} as a mode-specific abbrev expanding into @var{exp}. -@item M-x kill-all-abbrevs -Discard all abbrev definitions, leaving a blank slate. -@end table - -@kindex C-x a g -@findex add-global-abbrev - The usual way to define an abbrev is to enter the text you want the -abbrev to expand to, position point after it, and type @kbd{C-x a g} -(@code{add-global-abbrev}). This reads the abbrev itself using the -minibuffer, and then defines it as an abbrev for one or more words before -point. Use a numeric argument to say how many words before point should be -taken as the expansion. For example, to define the abbrev @samp{foo} as -mentioned above, insert the text @samp{find outer otter} and then type -@kbd{C-u 3 C-x a g f o o @key{RET}}. - - An argument of zero to @kbd{C-x a g} means to use the contents of the -region as the expansion of the abbrev being defined. - -@kindex C-x a l -@findex add-mode-abbrev - The command @kbd{C-x a l} (@code{add-mode-abbrev}) is similar, but -defines a mode-specific abbrev. Mode-specific abbrevs are active only in a -particular major mode. @kbd{C-x a l} defines an abbrev for the major mode -in effect at the time @kbd{C-x a l} is typed. The arguments work the same -as for @kbd{C-x a g}. - -@kindex C-x a i g -@findex inverse-add-global-abbrev -@kindex C-x a i l -@findex inverse-add-mode-abbrev - If the abbrev text itself is already in the buffer, you can use the -commands @kbd{C-x a i g} (@code{inverse-add-global-abbrev}) and -@kbd{C-x a i l} (@code{inverse-add-mode-abbrev}) to define it as an -abbrev by specify the expansion in the minibuffer. These commands are -called ``inverse'' because they invert the meaning of the two text -strings they use (one from the buffer and one read with the -minibuffer). - -@findex define-mode-abbrev -@findex define-global-abbrev - You can define an abbrev without inserting either the abbrev or its -expansion in the buffer using the command @code{define-global-abbrev}. -It reads two arguments---the abbrev, and its expansion. The command -@code{define-mode-abbrev} does likewise for a mode-specific abbrev. - - To change the definition of an abbrev, just define a new definition. -When the abbrev has a prior definition, the abbrev definition commands -ask for confirmation before replacing it. - -@findex kill-all-abbrevs - To remove an abbrev definition, give a negative argument to the -abbrev definition command: @kbd{C-u - C-x a g} or @kbd{C-u - C-x a l}. -The former removes a global definition, while the latter removes a -mode-specific definition. @kbd{M-x kill-all-abbrevs} removes all -abbrev definitions, both global and local. - -@node Expanding Abbrevs -@section Controlling Abbrev Expansion - - When Abbrev mode is enabled, an abbrev expands whenever it is -present in the buffer just before point and you type a self-inserting -whitespace or punctuation character (@key{SPC}, comma, etc.@:). More -precisely, any character that is not a word constituent expands an -abbrev, and any word-constituent character can be part of an abbrev. -The most common way to use an abbrev is to insert it and then insert a -punctuation or whitespace character to expand it. - -@vindex abbrev-all-caps - Abbrev expansion preserves case; thus, @samp{foo} expands into @samp{find -outer otter}; @samp{Foo} into @samp{Find outer otter}, and @samp{FOO} into -@samp{FIND OUTER OTTER} or @samp{Find Outer Otter} according to the -variable @code{abbrev-all-caps} (setting it non-@code{nil} specifies -@samp{FIND OUTER OTTER}). - - These commands are used to control abbrev expansion: - -@table @kbd -@item M-' -Separate a prefix from a following abbrev to be expanded -(@code{abbrev-prefix-mark}). -@item C-x a e -@findex expand-abbrev -Expand the abbrev before point (@code{expand-abbrev}). -This is effective even when Abbrev mode is not enabled. -@item M-x expand-region-abbrevs -Expand some or all abbrevs found in the region. -@end table - -@kindex M-' -@findex abbrev-prefix-mark - You may wish to expand an abbrev and attach a prefix to the expansion; -for example, if @samp{cnst} expands into @samp{construction}, you might want -to use it to enter @samp{reconstruction}. It does not work to type -@kbd{recnst}, because that is not necessarily a defined abbrev. What -you can do is use the command @kbd{M-'} (@code{abbrev-prefix-mark}) in -between the prefix @samp{re} and the abbrev @samp{cnst}. First, insert -@samp{re}. Then type @kbd{M-'}; this inserts a hyphen in the buffer to -indicate that it has done its work. Then insert the abbrev @samp{cnst}; -the buffer now contains @samp{re-cnst}. Now insert a non-word character -to expand the abbrev @samp{cnst} into @samp{construction}. This -expansion step also deletes the hyphen that indicated @kbd{M-'} had been -used. The result is the desired @samp{reconstruction}. - - If you actually want the text of the abbrev in the buffer, rather than -its expansion, you can accomplish this by inserting the following -punctuation with @kbd{C-q}. Thus, @kbd{foo C-q ,} leaves @samp{foo,} in -the buffer, not expanding it. - -@findex unexpand-abbrev - If you expand an abbrev by mistake, you can undo the expansion and -bring back the abbrev itself by typing @kbd{C-_} to undo (@pxref{Undo}). -This also undoes the insertion of the non-word character that expanded -the abbrev. If the result you want is the terminating non-word -character plus the unexpanded abbrev, you must reinsert the terminating -character, quoting it with @kbd{C-q}. You can also use the command -@kbd{M-x unexpand-abbrev} to cancel the last expansion without -deleting the terminating character. - -@findex expand-region-abbrevs - @kbd{M-x expand-region-abbrevs} searches through the region for defined -abbrevs, and for each one found offers to replace it with its expansion. -This command is useful if you have typed in text using abbrevs but forgot -to turn on Abbrev mode first. It may also be useful together with a -special set of abbrev definitions for making several global replacements at -once. This command is effective even if Abbrev mode is not enabled. - - Expanding any abbrev first runs the hook @code{pre-abbrev-expand-hook} -(@pxref{Hooks}). - -@need 1500 -@node Editing Abbrevs -@section Examining and Editing Abbrevs - -@table @kbd -@item M-x list-abbrevs -Display a list of all abbrev definitions. With a numeric argument, list -only local abbrevs. -@item M-x edit-abbrevs -Edit a list of abbrevs; you can add, alter or remove definitions. -@end table - -@findex list-abbrevs - The output from @kbd{M-x list-abbrevs} looks like this: - -@example -@var{various other tables@dots{}} -(lisp-mode-abbrev-table) -"dk" 0 "define-key" -(global-abbrev-table) -"dfn" 0 "definition" -@end example - -@noindent -(Some blank lines of no semantic significance, and some other abbrev -tables, have been omitted.) - - A line containing a name in parentheses is the header for abbrevs in a -particular abbrev table; @code{global-abbrev-table} contains all the global -abbrevs, and the other abbrev tables that are named after major modes -contain the mode-specific abbrevs. - - Within each abbrev table, each nonblank line defines one abbrev. The -word at the beginning of the line is the abbrev. The number that -follows is the number of times the abbrev has been expanded. Emacs -keeps track of this to help you see which abbrevs you actually use, so -that you can eliminate those that you don't use often. The string at -the end of the line is the expansion. - - Some abbrevs are marked with @samp{(sys)}. These ``system'' abbrevs -(@pxref{Abbrevs,,, elisp, The Emacs Lisp Reference Manual}) are -pre-defined by various modes, and are not saved to your abbrev file. -To disable a ``system'' abbrev, define an abbrev of the same name that -expands to itself, and save it to your abbrev file. - -@findex edit-abbrevs -@kindex C-c C-c @r{(Edit Abbrevs)} - @kbd{M-x edit-abbrevs} allows you to add, change or kill abbrev -definitions by editing a list of them in an Emacs buffer. The list has -the same format described above. The buffer of abbrevs is called -@samp{*Abbrevs*}, and is in Edit-Abbrevs mode. Type @kbd{C-c C-c} in -this buffer to install the abbrev definitions as specified in the -buffer---and delete any abbrev definitions not listed. - - The command @code{edit-abbrevs} is actually the same as -@code{list-abbrevs} except that it selects the buffer @samp{*Abbrevs*} -whereas @code{list-abbrevs} merely displays it in another window. - -@node Saving Abbrevs -@section Saving Abbrevs - - These commands allow you to keep abbrev definitions between editing -sessions. - -@table @kbd -@item M-x write-abbrev-file @key{RET} @var{file} @key{RET} -Write a file @var{file} describing all defined abbrevs. -@item M-x read-abbrev-file @key{RET} @var{file} @key{RET} -Read the file @var{file} and define abbrevs as specified therein. -@item M-x quietly-read-abbrev-file @key{RET} @var{file} @key{RET} -Similar but do not display a message about what is going on. -@item M-x define-abbrevs -Define abbrevs from definitions in current buffer. -@item M-x insert-abbrevs -Insert all abbrevs and their expansions into current buffer. -@end table - -@findex write-abbrev-file - @kbd{M-x write-abbrev-file} reads a file name using the minibuffer and -then writes a description of all current abbrev definitions into that -file. This is used to save abbrev definitions for use in a later -session. The text stored in the file is a series of Lisp expressions -that, when executed, define the same abbrevs that you currently have. - -@findex read-abbrev-file -@findex quietly-read-abbrev-file -@vindex abbrev-file-name - @kbd{M-x read-abbrev-file} reads a file name using the minibuffer -and then reads the file, defining abbrevs according to the contents of -the file. The function @code{quietly-read-abbrev-file} is similar -except that it does not display a message in the echo area; you cannot -invoke it interactively, and it is used primarily in the @file{.emacs} -file. If either of these functions is called with @code{nil} as the -argument, it uses the file name specified in the variable -@code{abbrev-file-name}, which is by default @code{"~/.abbrev_defs"}. -That file is your standard abbrev definition file, and Emacs loads -abbrevs from it automatically when it starts up. - -@vindex save-abbrevs - Emacs will offer to save abbrevs automatically if you have changed -any of them, whenever it offers to save all files (for @kbd{C-x s} or -@kbd{C-x C-c}). It saves them in the file specified by -@code{abbrev-file-name}. This feature can be inhibited by setting the -variable @code{save-abbrevs} to @code{nil}. - -@findex insert-abbrevs -@findex define-abbrevs - The commands @kbd{M-x insert-abbrevs} and @kbd{M-x define-abbrevs} are -similar to the previous commands but work on text in an Emacs buffer. -@kbd{M-x insert-abbrevs} inserts text into the current buffer after point, -describing all current abbrev definitions; @kbd{M-x define-abbrevs} parses -the entire current buffer and defines abbrevs accordingly. - -@node Dynamic Abbrevs -@section Dynamic Abbrev Expansion - - The abbrev facility described above operates automatically as you -insert text, but all abbrevs must be defined explicitly. By contrast, -@dfn{dynamic abbrevs} allow the meanings of abbreviations to be -determined automatically from the contents of the buffer, but dynamic -abbrev expansion happens only when you request it explicitly. - -@kindex M-/ -@kindex C-M-/ -@findex dabbrev-expand -@findex dabbrev-completion -@table @kbd -@item M-/ -Expand the word in the buffer before point as a @dfn{dynamic abbrev}, -by searching in the buffer for words starting with that abbreviation -(@code{dabbrev-expand}). - -@item C-M-/ -Complete the word before point as a dynamic abbrev -(@code{dabbrev-completion}). -@end table - -@vindex dabbrev-limit - For example, if the buffer contains @samp{does this follow } and you -type @kbd{f o M-/}, the effect is to insert @samp{follow} because that -is the last word in the buffer that starts with @samp{fo}. A numeric -argument to @kbd{M-/} says to take the second, third, etc.@: distinct -expansion found looking backward from point. Repeating @kbd{M-/} -searches for an alternative expansion by looking farther back. After -scanning all the text before point, it searches the text after point. -The variable @code{dabbrev-limit}, if non-@code{nil}, specifies how far -away in the buffer to search for an expansion. - -@vindex dabbrev-check-all-buffers - After scanning the current buffer, @kbd{M-/} normally searches other -buffers, unless you have set @code{dabbrev-check-all-buffers} to -@code{nil}. - -@vindex dabbrev-ignored-buffer-regexps - For finer control over which buffers to scan, customize the variable -@code{dabbrev-ignored-buffer-regexps}. Its value is a list of regular -expressions. If a buffer's name matches any of these regular -expressions, dynamic abbrev expansion skips that buffer. - - A negative argument to @kbd{M-/}, as in @kbd{C-u - M-/}, says to -search first for expansions after point, then other buffers, and -consider expansions before point only as a last resort. If you repeat -the @kbd{M-/} to look for another expansion, do not specify an -argument. Repeating @kbd{M-/} cycles through all the expansions after -point and then the expansions before point. - - After you have expanded a dynamic abbrev, you can copy additional -words that follow the expansion in its original context. Simply type -@kbd{@key{SPC} M-/} for each additional word you want to copy. The -spacing and punctuation between words is copied along with the words. - - The command @kbd{C-M-/} (@code{dabbrev-completion}) performs -completion of a dynamic abbrev. Instead of trying the possible -expansions one by one, it finds all of them, then inserts the text -that they have in common. If they have nothing in common, @kbd{C-M-/} -displays a list of completions, from which you can select a choice in -the usual manner. @xref{Completion}. - - Dynamic abbrev expansion is completely independent of Abbrev mode; the -expansion of a word with @kbd{M-/} is completely independent of whether -it has a definition as an ordinary abbrev. - -@node Dabbrev Customization -@section Customizing Dynamic Abbreviation - - Normally, dynamic abbrev expansion ignores case when searching for -expansions. That is, the expansion need not agree in case with the word -you are expanding. - -@vindex dabbrev-case-fold-search - This feature is controlled by the variable -@code{dabbrev-case-fold-search}. If it is @code{t}, case is ignored in -this search; if it is @code{nil}, the word and the expansion must match -in case. If the value of @code{dabbrev-case-fold-search} is -@code{case-fold-search}, which is true by default, then the variable -@code{case-fold-search} controls whether to ignore case while searching -for expansions. - -@vindex dabbrev-case-replace - Normally, dynamic abbrev expansion preserves the case pattern -@emph{of the dynamic abbrev you are expanding}, by converting the -expansion to that case pattern. - -@vindex dabbrev-case-fold-search - The variable @code{dabbrev-case-replace} controls whether to -preserve the case pattern of the dynamic abbrev. If it is @code{t}, -the dynamic abbrev's case pattern is preserved in most cases; if it is -@code{nil}, the expansion is always copied verbatim. If the value of -@code{dabbrev-case-replace} is @code{case-replace}, which is true by -default, then the variable @code{case-replace} controls whether to -copy the expansion verbatim. - - However, if the expansion contains a complex mixed case pattern, and -the dynamic abbrev matches this pattern as far as it goes, then the -expansion is always copied verbatim, regardless of those variables. -Thus, for example, if the buffer contains -@code{variableWithSillyCasePattern}, and you type @kbd{v a M-/}, it -copies the expansion verbatim including its case pattern. - -@vindex dabbrev-abbrev-char-regexp - The variable @code{dabbrev-abbrev-char-regexp}, if non-@code{nil}, -controls which characters are considered part of a word, for dynamic expansion -purposes. The regular expression must match just one character, never -two or more. The same regular expression also determines which -characters are part of an expansion. The value @code{nil} has a special -meaning: dynamic abbrevs are made of word characters, but expansions are -made of word and symbol characters. - -@vindex dabbrev-abbrev-skip-leading-regexp - In shell scripts and makefiles, a variable name is sometimes prefixed -with @samp{$} and sometimes not. Major modes for this kind of text can -customize dynamic abbrev expansion to handle optional prefixes by setting -the variable @code{dabbrev-abbrev-skip-leading-regexp}. Its value -should be a regular expression that matches the optional prefix that -dynamic abbrev expression should ignore. - -@ignore - arch-tag: 638e0079-9540-48ec-9166-414083e16445 -@end ignore