diff options
Diffstat (limited to 'lispref/abbrevs.texi')
-rw-r--r-- | lispref/abbrevs.texi | 331 |
1 files changed, 0 insertions, 331 deletions
diff --git a/lispref/abbrevs.texi b/lispref/abbrevs.texi deleted file mode 100644 index 59e1995a4d5..00000000000 --- a/lispref/abbrevs.texi +++ /dev/null @@ -1,331 +0,0 @@ -@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 |