Initial revision

1 files changed, 331 insertions, 0 deletions

diff --git a/lispref/abbrevs.texi b/lispref/abbrevs.texi
new file mode 100644
index 00000000000..59e1995a4d5
--- /dev/null
+++ b/lispref/abbrevs.texi
@@ -0,0 +1,331 @@
+@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 See the file elisp.texi for copying conditions.
+@setfilename ../info/abbrevs
+@node Abbrevs, Processes, Syntax Tables, Top
+@chapter Abbrevs And Abbrev Expansion
+@cindex abbrev
+@cindex abbrev table
+
+  An abbreviation or @dfn{abbrev} is a string of characters that may be
+expanded to a longer string.  The user can insert the abbrev string and
+find it replaced automatically with the expansion of the abbrev.  This
+saves typing.
+
+  The set of abbrevs currently in effect is recorded in an @dfn{abbrev
+table}.  Each buffer has a local abbrev table, but normally all buffers
+in the same major mode share one abbrev table.  There is also a global
+abbrev table.  Normally both are used.
+
+  An abbrev table is represented as an obarray containing a symbol for
+each abbreviation.  The symbol's name is the abbreviation.  Its value is
+the expansion; its function definition is the hook function to do the
+expansion (if any); its property list cell contains the use count, the
+number of times the abbreviation has been expanded.  Because these
+symbols are not interned in the usual obarray, they will never appear as
+the result of reading a Lisp expression; in fact, normally they are
+never used except by the code that handles abbrevs.  Therefore, it is
+safe to use them in an extremely nonstandard way.  @xref{Creating
+Symbols}.
+
+  For the user-level commands for abbrevs, see @ref{Abbrevs,, Abbrev
+Mode, emacs, The GNU Emacs Manual}.
+
+@menu
+* Abbrev Mode::                 Setting up Emacs for abbreviation.
+* Tables: Abbrev Tables.        Creating and working with abbrev tables.
+* Defining Abbrevs::            Specifying abbreviations and their expansions.
+* Files: Abbrev Files.          Saving abbrevs in files.
+* Expansion: Abbrev Expansion.  Controlling expansion; expansion subroutines.
+* Standard Abbrev Tables::      Abbrev tables used by various major modes.
+@end menu
+
+@node Abbrev Mode, Abbrev Tables, Abbrevs, Abbrevs
+@comment  node-name,  next,  previous,  up
+@section Setting Up Abbrev Mode    
+
+  Abbrev mode is a minor mode controlled by the value of the variable
+@code{abbrev-mode}.
+
+@defvar abbrev-mode
+A non-@code{nil} value of this variable turns on the automatic expansion
+of abbrevs when their abbreviations are inserted into a buffer.
+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.
+@end defvar
+
+@defvar default-abbrev-mode
+This is the value @code{abbrev-mode} for buffers that do not override it.
+This is the same as @code{(default-value 'abbrev-mode)}.
+@end defvar
+
+@node Abbrev Tables, Defining Abbrevs, Abbrev Mode, Abbrevs
+@section Abbrev Tables
+
+  This section describes how to create and manipulate abbrev tables.
+
+@defun make-abbrev-table
+This function creates and returns a new, empty abbrev table---an obarray
+containing no symbols.  It is a vector filled with zeros.
+@end defun
+
+@defun clear-abbrev-table table
+This function undefines all the abbrevs in abbrev table @var{table},
+leaving it empty.  The function returns @code{nil}.
+@end defun
+
+@defun define-abbrev-table tabname definitions
+This function defines @var{tabname} (a symbol) as an abbrev table name,
+i.e., as a variable whose value is an abbrev table.  It defines abbrevs
+in the table according to @var{definitions}, a list of elements of the
+form @code{(@var{abbrevname} @var{expansion} @var{hook}
+@var{usecount})}.  The value is always @code{nil}.
+@end defun
+
+@defvar abbrev-table-name-list
+This is a list of symbols whose values are abbrev tables.
+@code{define-abbrev-table} adds the new abbrev table name to this list.
+@end defvar
+
+@defun insert-abbrev-table-description name &optional human
+This function inserts before point a description of the abbrev table
+named @var{name}.  The argument @var{name} is a symbol whose value is an
+abbrev table.  The value is always @code{nil}.
+
+If @var{human} is non-@code{nil}, the description is human-oriented.
+Otherwise the description is a Lisp expression---a call to
+@code{define-abbrev-table} which would define @var{name} exactly as it
+is currently defined.
+@end defun
+
+@node Defining Abbrevs, Abbrev Files, Abbrev Tables, Abbrevs
+@comment  node-name,  next,  previous,  up
+@section Defining Abbrevs
+
+  These functions define an abbrev in a specified abbrev table.
+@code{define-abbrev} is the low-level basic function, while
+@code{add-abbrev} is used by commands that ask for information from the
+user.
+
+@defun add-abbrev table type arg
+This function adds an abbreviation to abbrev table @var{table}.  The
+argument @var{type} is a string describing in English the kind of abbrev
+this will be (typically, @code{"global"} or @code{"mode-specific"});
+this is used in prompting the user.  The argument @var{arg} is the
+number of words in the expansion.
+
+The return value is the symbol which internally represents the new
+abbrev, or @code{nil} if the user declines to confirm redefining an
+existing abbrev.
+@end defun
+
+@defun define-abbrev table name expansion hook
+This function defines an abbrev in @var{table} named @var{name}, to
+expand to @var{expansion}, and call @var{hook}.  The return value is an
+uninterned symbol which represents the abbrev inside Emacs; its name is
+@var{name}.
+
+The argument @var{name} should be a string.  The argument
+@var{expansion} should be a string, or @code{nil}, to undefine the
+abbrev.
+
+The argument @var{hook} is a function or @code{nil}.  If @var{hook} is
+non-@code{nil}, then it is called with no arguments after the abbrev is
+replaced with @var{expansion}; point is located at the end of
+@var{expansion}.
+
+The use count of the abbrev is initialized to zero.
+@end defun
+
+@defopt only-global-abbrevs
+If this variable is non-@code{nil}, it means that the user plans to use
+global abbrevs only.  This tells the commands that define mode-specific
+abbrevs to define global ones instead.  This variable does not alter the
+functioning of the functions in this section; it is examined by their
+callers.
+@end defopt
+
+@node Abbrev Files, Abbrev Expansion, Defining Abbrevs, Abbrevs
+@section Saving Abbrevs in Files
+
+  A file of saved abbrev definitions is actually a file of Lisp code.
+The abbrevs are saved in the form of a Lisp program to define the same
+abbrev tables with the same contents.  Therefore, you can load the file
+with @code{load} (@pxref{How Programs Do Loading}).  However, the
+function @code{quietly-read-abbrev-file} is provided as a more
+convenient interface.
+
+  User-level facilities such as @code{save-some-buffers} can save
+abbrevs in a file automatically, under the control of variables
+described here.
+
+@defopt abbrev-file-name
+This is the default file name for reading and saving abbrevs.
+@end defopt
+
+@defun quietly-read-abbrev-file 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.
+
+This function does not display any messages.  It returns @code{nil}.
+@end defun
+
+@defopt save-abbrevs
+A non-@code{nil} value for @code{save-abbrev} means that Emacs should
+save abbrevs when files are saved.  @code{abbrev-file-name} specifies
+the file to save the abbrevs in.
+@end defopt
+
+@defvar abbrevs-changed
+This variable is set non-@code{nil} by defining or altering any 
+abbrevs.  This serves as a flag for various Emacs commands to offer to
+save your abbrevs.
+@end defvar
+
+@deffn Command write-abbrev-file filename
+Save all abbrev definitions, in all abbrev tables, in the file
+@var{filename}, in the form of a Lisp program which when loaded will
+define the same abbrevs.  This function returns @code{nil}.
+@end deffn
+
+@node Abbrev Expansion, Standard Abbrev Tables, Abbrev Files, Abbrevs
+@comment  node-name,  next,  previous,  up
+@section Looking Up and Expanding Abbreviations
+
+  Abbrevs are usually expanded by commands for interactive use,
+including @code{self-insert-command}.  This section describes the
+subroutines used in writing such functions, as well as the variables
+they use for communication.
+
+@defun abbrev-symbol abbrev &optional table
+This function returns the symbol representing the abbrev named
+@var{abbrev}.  The value returned is @code{nil} if that abbrev is not
+defined.  The optional second argument @var{table} is the abbrev table
+to look it up in.  If @var{table} is @code{nil}, this function tries
+first the current buffer's local abbrev table, and second the global
+abbrev table.
+@end defun
+
+@defopt abbrev-all-caps
+When this is set non-@code{nil}, an abbrev entered entirely in upper
+case is expanded using all upper case.  Otherwise, an abbrev entered
+entirely in upper case is expanded by capitalizing each word of the
+expansion.
+@end defopt
+
+@defun abbrev-expansion abbrev &optional table
+This function returns the string that @var{abbrev} would expand into (as
+defined by the abbrev tables used for the current buffer).  The optional
+argument @var{table} specifies the abbrev table to use; if it is
+specified, the abbrev is looked up in that table only.
+@end defun
+
+@defvar abbrev-start-location
+This is the buffer position for @code{expand-abbrev} to use as the start
+of the next abbrev to be expanded.  (@code{nil} means use the word
+before point instead.)  @code{abbrev-start-location} is set to
+@code{nil} each time @code{expand-abbrev} is called.  This variable is
+also set by @code{abbrev-prefix-mark}.
+@end defvar
+
+@defvar abbrev-start-location-buffer
+The value of this variable is the buffer for which
+@code{abbrev-start-location} has been set.  Trying to expand an abbrev
+in any other buffer clears @code{abbrev-start-location}.  This variable
+is set by @code{abbrev-prefix-mark}.
+@end defvar
+
+@defvar last-abbrev
+This is the @code{abbrev-symbol} of the last abbrev expanded.  This
+information is left by @code{expand-abbrev} for the sake of the
+@code{unexpand-abbrev} command.
+@end defvar
+
+@defvar last-abbrev-location
+This is the location of the last abbrev expanded.  This contains
+information left by @code{expand-abbrev} for the sake of the
+@code{unexpand-abbrev} command.
+@end defvar
+
+@defvar last-abbrev-text
+This is the exact expansion  text of the last abbrev expanded, as
+results from case conversion.  Its value is
+@code{nil} if the abbrev has already been unexpanded.  This
+contains information left by @code{expand-abbrev} for the sake of the
+@code{unexpand-abbrev} command.
+@end defvar
+
+@c Emacs 19 feature
+@defvar pre-abbrev-expand-hook
+This is a normal hook whose functions are executed, in sequence, just
+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.
+@end defvar
+
+  The following sample code shows a simple use of
+@code{pre-abbrev-expand-hook}.  If the user terminates an abbrev with a
+punctuation character, the hook function asks for confirmation.  Thus,
+this hook allows the user to decide whether to expand the abbrev, and
+aborts expansion if it is not confirmed.
+
+@smallexample
+(add-hook 'pre-abbrev-expand-hook 'query-if-not-space)
+
+;; @r{This is the function invoked by @code{pre-abbrev-expand-hook}.}
+
+;; @r{If the user terminated the abbrev with a space, the function does}
+;; @r{nothing (that is, it returns so that the abbrev can expand).  If the}
+;; @r{user entered some other character, this function asks whether}
+;; @r{expansion should continue.}
+
+;; @r{If the user enters the prompt with @kbd{y}, the function returns}
+;; @r{@code{nil} (because of the @code{not} function), but that is}
+;; @r{acceptable; the return value has no effect on expansion.}
+
+(defun query-if-not-space ()
+  (if (/= ?\  (preceding-char))
+      (if (not (y-or-n-p "Do you want to expand this abbrev? "))
+          (error "Not expanding this abbrev"))))
+@end smallexample
+
+@node Standard Abbrev Tables,  , Abbrev Expansion, Abbrevs
+@comment  node-name,  next,  previous,  up
+@section Standard Abbrev Tables
+
+  Here we list the variables that hold the abbrev tables for the
+preloaded major modes of Emacs.
+
+@defvar global-abbrev-table
+This is the abbrev table for mode-independent abbrevs.  The abbrevs
+defined in it apply to all buffers.  Each buffer may also have a local
+abbrev table, whose abbrev definitions take precedence over those in the
+global table.
+@end defvar
+
+@defvar local-abbrev-table
+The value of this buffer-local variable is the (mode-specific)
+abbreviation table of the current buffer.
+@end defvar
+
+@defvar fundamental-mode-abbrev-table
+This is the local abbrev table used in Fundamental mode.  It is the
+local abbrev table in all buffers in Fundamental mode.
+@end defvar
+
+@defvar text-mode-abbrev-table
+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