@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1999
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/abbrevs
@node Abbrevs, Processes, Syntax Tables, Top
-@chapter Abbrevs And Abbrev Expansion
+@chapter Abbrevs and Abbrev Expansion
@cindex abbrev
@cindex abbrev table
If the value is @code{nil}, abbrevs may be defined, but they are not
expanded automatically.
-This variable automatically becomes local when set in any fashion.
+This variable automatically becomes buffer-local when set in any fashion.
@end defvar
@defvar default-abbrev-mode
@defun clear-abbrev-table table
This function undefines all the abbrevs in abbrev table @var{table},
-leaving it empty. The function returns @code{nil}.
+leaving it empty. It always returns @code{nil}.
@end defun
@defun define-abbrev-table tabname definitions
existing abbrev.
@end defun
-@defun define-abbrev table name expansion hook
+@defun define-abbrev table name expansion &optional hook count
This function defines an abbrev named @var{name}, in @var{table}, to
-expand to @var{expansion} and call @var{hook}. The return value is a
-symbol that represents the abbrev inside Emacs; its name is @var{name}.
+expand to @var{expansion} and call @var{hook}. The value of
+@var{count}, if specified, initializes the abbrev's usage-count. If
+@var{count} is not specified or @code{nil}, the use count is initialized
+to zero. The return value is a symbol that represents the abbrev inside
+Emacs; its name is @var{name}.
The argument @var{name} should be a string. The argument
@var{expansion} is normally the desired expansion (a string), or
replaced with @var{expansion}; point is located at the end of
@var{expansion} when @var{hook} is called.
-The use count of the abbrev is initialized to zero.
+If @var{hook} is a non-nil symbol whose @code{no-self-insert} property
+is non-@code{nil}, @var{hook} can explicitly control whether to insert
+the self-inserting input character that triggered the expansion. If
+@var{hook} returns non-@code{nil} in this case, that inhibits insertion
+of the character. By contrast, if @var{hook} returns @code{nil},
+@code{expand-abbrev} also returns @code{nil}, as if expansion had not
+really occurred.
@end defun
@defopt only-global-abbrevs
This is the default file name for reading and saving abbrevs.
@end defopt
-@defun quietly-read-abbrev-file filename
+@defun quietly-read-abbrev-file &optional filename
This function reads abbrev definitions from a file named @var{filename},
previously written with @code{write-abbrev-file}. If @var{filename} is
-@code{nil}, the file specified in @code{abbrev-file-name} is used.
-@code{save-abbrevs} is set to @code{t} so that changes will be saved.
+omitted or @code{nil}, the file specified in @code{abbrev-file-name} is
+used. @code{save-abbrevs} is set to @code{t} so that changes will be
+saved.
This function does not display any messages. It returns @code{nil}.
@end defun
save your abbrevs.
@end defvar
-@deffn Command write-abbrev-file filename
+@deffn Command write-abbrev-file &optional filename
Save all abbrev definitions, in all abbrev tables, in the file
@var{filename}, in the form of a Lisp program that when loaded will
-define the same abbrevs. This function returns @code{nil}.
+define the same abbrevs. If @var{filename} is @code{nil} or omitted,
+@code{abbrev-file-name} is used. This function returns @code{nil}.
@end deffn
@node Abbrev Expansion, Standard Abbrev Tables, Abbrev Files, Abbrevs
@end defun
@deffn Command expand-abbrev
-This command expands the abbrev before point, if any.
-If point does not follow an abbrev, this command does nothing.
-The command returns @code{t} if it did expansion, @code{nil} otherwise.
+This command expands the abbrev before point, if any. If point does not
+follow an abbrev, this command does nothing. The command returns the
+abbrev symbol if it did expansion, @code{nil} otherwise.
+
+If the abbrev symbol has a hook function which is a symbol whose
+@code{no-self-insert} property is non-@code{nil}, and if the hook
+function returns @code{nil} as its value, then @code{expand-abbrev}
+returns @code{nil} even though expansion did occur.
@end deffn
@deffn Command abbrev-prefix-mark &optional arg
before any expansion of an abbrev. @xref{Hooks}. Since it is a normal
hook, the hook functions receive no arguments. However, they can find
the abbrev to be expanded by looking in the buffer before point.
+Running the hook is the first thing that @code{expand-abbrev} does, and
+so a hook function can be used to change the current abbrev table before
+abbrev lookup happens.
@end defvar
The following sample code shows a simple use of
This is the local abbrev table used in Text mode.
@end defvar
-@defvar c-mode-abbrev-table
-This is the local abbrev table used in C mode.
-@end defvar
-
@defvar lisp-mode-abbrev-table
This is the local abbrev table used in Lisp mode and Emacs Lisp mode.
@end defvar
+