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 (@pxref{Defining Abbrevs}); 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}.
+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 (@pxref{Defining Abbrevs}); its property list cell
+typically contains the use count, the number of times the abbreviation
+has been expanded. (Alternatively, the use count is on the
+@code{count} property and the system-abbrev flag is on the
+@code{system-type} property.) 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}.
@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
-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 return value is always @code{nil}.
+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} @r{[}@var{system-flag}@r{]})}. The return
+value is always @code{nil}.
@end defun
@defvar abbrev-table-name-list
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.
+@code{add-abbrev} is used by commands that ask for information from
+the user. When major modes predefine standard abbrevs, they should
+call @code{define-abbrev} and specify @code{t} for @var{system-flag}.
@defun add-abbrev table type arg
This function adds an abbreviation to abbrev table @var{table} based on
the user. The argument @var{arg} is the number of words in the
expansion.
-
The return value is the symbol that 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 &optional hook count
+@defun define-abbrev table name expansion &optional hook count system-flag
This function defines an abbrev named @var{name}, in @var{table}, to
-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}.
+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}.
+
+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 argument @var{name} should be a string. The argument
@var{expansion} is normally the desired expansion (a string), or
@code{nil}, then the abbreviation ``expands'' solely by running
@var{hook}.
-
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} when @var{hook} is called.
+
+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.
+
+If @var{system-flag} is non-@code{nil}, that marks the abbrev as a
+``system'' abbrev with the @code{system-type} property.
+
+Normally the function @code{define-abbrev} sets the variable
+@code{abbrevs-changed} to @code{t}, if it actually changes the abbrev.
+(This is so that some commands will offer to save the abbrevs.) It
+does not do this for a ``system'' abbrev, since those won't be saved
+anyway.
@end defun
@defopt only-global-abbrevs
@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.
+This variable is set non-@code{nil} by defining or altering any
+abbrevs (except ``system'' abbrevs). This serves as a flag for
+various Emacs commands to offer to save your abbrevs.
@end defvar
@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. If @var{filename} is @code{nil} or omitted,
-@code{abbrev-file-name} is used. This function returns @code{nil}.
+Save all abbrev definitions (except ``system'' abbrevs), in all abbrev
+tables, in the file @var{filename}, in the form of a Lisp program that
+when loaded will 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
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.
-@end deffn
+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
Mark current point as the beginning of an abbrev. The next call to
HCoop / bpt / emacs.git / blobdiff