Mercurial > emacs

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/emacs/abbrevs.texi	Thu Sep 06 04:43:48 2007 +0000
@@ -0,0 +1,457 @@
+@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