Merge from emacs-24; up to 2012-04-20T05:47:55Z!eliz@gnu.org

[bpt/emacs.git] / doc / emacs / abbrevs.texi

diff --git a/doc/emacs/abbrevs.texi b/doc/emacs/abbrevs.texi
index 1dc4f62..d3c914d 100644 (file)
--- a/doc/emacs/abbrevs.texi
+++ b/doc/emacs/abbrevs.texi
@@ -1,6 +1,6 @@
 @c This is part of the Emacs manual.
 @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, 2008 Free Software Foundation, Inc.
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2012
+@c   Free Software Foundation, Inc.

 @c See file emacs.texi for copying conditions.
 @node Abbrevs
 @chapter Abbrevs
 @c See file emacs.texi for copying conditions.
 @node Abbrevs
 @chapter Abbrevs


@@ -37,25 +37,22 @@ Automatic Typing}.
 @node Abbrev Concepts
 @section Abbrev Concepts
 
 @node Abbrev Concepts
 @section Abbrev Concepts
 

-  An @dfn{abbrev} is a word which has been defined to @dfn{expand} into
+  An @dfn{abbrev} is a word that 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
 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 .}.
+expanding to @samp{find outer otter}, then typing @kbd{f o o .} will
+insert @samp{find outer otter.}.

 
 @findex abbrev-mode
 
 @findex abbrev-mode

-@vindex abbrev-mode

 @cindex Abbrev mode
 @cindex mode, Abbrev
 @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 expand only when Abbrev mode, a buffer-local 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}.

 
   Abbrevs can have @dfn{mode-specific} definitions, active only in one major
 mode.  Abbrevs can also have @dfn{global} definitions that are active in
 
   Abbrevs can have @dfn{mode-specific} definitions, active only in one major
 mode.  Abbrevs can also have @dfn{global} definitions that are active in


@@ -63,10 +60,10 @@ 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.
 
 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.
+  You can define abbrevs interactively during the editing session,
+irrespective of whether Abbrev mode is enabled.  You can also save
+lists of abbrev definitions in files, which you can the reload for use
+in later sessions.

 
 @node Defining Abbrevs
 @section Defining Abbrevs
 
 @node Defining Abbrevs
 @section Defining Abbrevs


@@ -108,22 +105,18 @@ 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
 @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}.
+defines a mode-specific abbrev for the current major mode.  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
 
 @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).
+  @kbd{C-x a i g} (@code{inverse-add-global-abbrev}) and @kbd{C-x a i
+l} (@code{inverse-add-mode-abbrev}) perform the opposite task: if the
+abbrev text is already in the buffer, you use these commands to define
+an abbrev by specifying the expansion in the minibuffer.  These
+commands will expand the abbrev text used for the definition.

 
 @findex define-mode-abbrev
 @findex define-global-abbrev
 
 @findex define-mode-abbrev
 @findex define-global-abbrev


@@ -132,8 +125,8 @@ 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.
 
 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
+  To change the definition of an abbrev, just make a new definition.
+When an abbrev has a prior definition, the abbrev definition commands

 ask for confirmation before replacing it.
 
 @findex kill-all-abbrevs
 ask for confirmation before replacing it.
 
 @findex kill-all-abbrevs


@@ -155,11 +148,11 @@ 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
 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}).
+  Abbrev expansion preserves case: @samp{foo} expands to @samp{find
+outer otter}, and @samp{Foo} to @samp{Find outer otter}.  @samp{FOO}
+expands to @samp{Find Outer Otter} by default, but if you change the
+variable @code{abbrev-all-caps} to a non-@code{nil} value, it expands
+to @samp{FIND OUTER OTTER}.

 
   These commands are used to control abbrev expansion:
 
 
   These commands are used to control abbrev expansion:
 


@@ -196,14 +189,14 @@ punctuation with @kbd{C-q}.  Thus, @kbd{foo C-q ,} leaves @samp{foo,} in
 the buffer, not expanding it.
 
 @findex unexpand-abbrev
 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.
+  If you expand an abbrev by mistake, you can undo the expansion by
+typing @kbd{C-/} (@code{undo}).  @xref{Undo}.  This undoes the
+insertion of the abbrev expansion and brings back the abbrev text.  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
 
 @findex expand-region-abbrevs
   @kbd{M-x expand-region-abbrevs} searches through the region for defined


@@ -213,10 +206,11 @@ 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.
 
 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}).
+  Expanding any abbrev runs @code{abbrev-expand-functions}, a special
+hook.  Functions in this special hook can make arbitrary changes to
+the abbrev expansion.  @xref{Abbrev Expansion,,, elisp, The Emacs Lisp
+Reference Manual}.

 
 

-@need 1500

 @node Editing Abbrevs
 @section Examining and Editing Abbrevs
 
 @node Editing Abbrevs
 @section Examining and Editing Abbrevs
 


@@ -234,9 +228,9 @@ Edit a list of abbrevs; you can add, alter or remove definitions.
 @example
 @var{various other tables@dots{}}
 (lisp-mode-abbrev-table)
 @example
 @var{various other tables@dots{}}
 (lisp-mode-abbrev-table)

-"dk"          0    "define-key"
+"dk"          0    "define-key"

 (global-abbrev-table)
 (global-abbrev-table)

-"dfn"         0    "definition"
+"dfn"         0    "definition"

 @end example
 
 @noindent
 @end example
 
 @noindent


@@ -266,12 +260,12 @@ expands to itself, and save it to your abbrev file.
   @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
   @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
+@file{*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
 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*}
+@code{list-abbrevs} except that it selects the buffer @file{*Abbrevs*}

 whereas @code{list-abbrevs} merely displays it in another window.
 
 @node Saving Abbrevs
 whereas @code{list-abbrevs} merely displays it in another window.
 
 @node Saving Abbrevs


@@ -285,8 +279,6 @@ sessions.
 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.
 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
 @item M-x define-abbrevs
 Define abbrevs from definitions in current buffer.
 @item M-x insert-abbrevs


@@ -303,16 +295,19 @@ that, when executed, define the same abbrevs that you currently have.
 @findex read-abbrev-file
 @findex quietly-read-abbrev-file
 @vindex abbrev-file-name
 @findex read-abbrev-file
 @findex quietly-read-abbrev-file
 @vindex abbrev-file-name

+@cindex abbrev file

   @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
   @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.
+invoke it interactively, and it is used primarily in your init file
+(@pxref{Init File}).  If either of these functions is called with
+@code{nil} as the argument, it uses the file given by the variable
+@code{abbrev-file-name}, which is @file{~/.emacs.d/abbrev_defs} by
+default.  This is your standard abbrev definition file, and Emacs
+loads abbrevs from it automatically when it starts up.  (As an
+exception, Emacs does not load the abbrev file when it is started in
+batch mode.  @xref{Initial Options}, for a description of batch mode.)

 
 @vindex save-abbrevs
   Emacs will offer to save abbrevs automatically if you have changed
 
 @vindex save-abbrevs
   Emacs will offer to save abbrevs automatically if you have changed


@@ -407,12 +402,11 @@ you are expanding.
 
 @vindex dabbrev-case-fold-search
   This feature is controlled by the variable
 
 @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.
+@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 is @code{case-fold-search} (the default),
+then the variable @code{case-fold-search} controls whether to ignore
+case while searching for expansions (@pxref{Search Case}).

 
 @vindex dabbrev-case-replace
   Normally, dynamic abbrev expansion preserves the case pattern
 
 @vindex dabbrev-case-replace
   Normally, dynamic abbrev expansion preserves the case pattern


@@ -423,10 +417,10 @@ expansion to that case pattern.
   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
   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.
+@code{nil}, the expansion is always copied verbatim.  If the value is
+@code{case-replace} (the default), then the variable
+@code{case-replace} controls whether to copy the expansion verbatim
+(@pxref{Replacement and Case}).

 
   However, if the expansion contains a complex mixed case pattern, and
 the dynamic abbrev matches this pattern as far as it goes, then the
 
   However, if the expansion contains a complex mixed case pattern, and
 the dynamic abbrev matches this pattern as far as it goes, then the


@@ -451,7 +445,3 @@ 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.
 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