[Emacs-diffs] Changes to emacs/doc/lispref/abbrevs.texi,v

[Stefan Monnier]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Stefan Monnier <monnier>        07/10/28 02:41:00

Index: doc/lispref/abbrevs.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/lispref/abbrevs.texi,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- doc/lispref/abbrevs.texi    6 Sep 2007 04:27:43 -0000       1.2
+++ doc/lispref/abbrevs.texi    28 Oct 2007 02:40:55 -0000      1.3
@@ -47,6 +47,10 @@
 * Files: Abbrev Files.          Saving abbrevs in files.
 * Expansion: Abbrev Expansion.  Controlling expansion; expansion subroutines.
 * Standard Abbrev Tables::      Abbrev tables used by various major modes.
+* Abbrev Properties::           How to read and set abbrev properties.
+                                Which properties have which effect.
+* Abbrev Table Properties::     How to read and set abbrev table properties.
+                                Which properties have which effect.
 @end menu
 
 @node Abbrev Mode, Abbrev Tables, Abbrevs, Abbrevs
@@ -75,9 +79,14 @@
 
   This section describes how to create and manipulate abbrev tables.
 
address@hidden make-abbrev-table
address@hidden make-abbrev-table &rest props
 This function creates and returns a new, empty abbrev table---an obarray
-containing no symbols.  It is a vector filled with zeros.
+containing no symbols.  It is a vector filled with zeros.  @var{props}
+is a property list that is applied to the new table.
address@hidden defun
+
address@hidden abbrev-table-p table
+Return address@hidden is @var{table} is an abbrev table.
 @end defun
 
 @defun clear-abbrev-table table
@@ -92,15 +101,18 @@
 function sets the property lists of all copied abbrevs to 0.
 @end defun
 
address@hidden define-abbrev-table tabname definitions
address@hidden define-abbrev-table tabname definitions &optional docstring 
&rest props
 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}
address@hidden @var{usecount} @var{system-flag})}.  If an element of
address@hidden has length less than five, omitted elements default
-to @code{nil}.  A value of @code{nil} for @var{usecount} is equivalent
-to zero.  The return value is always @code{nil}.
address@hidden address@hidden)}.  These elements are passed as
+arguments to @code{define-abbrev}.  The return value is always
address@hidden
+
+The optional string @var{docstring} is the documentation string of the
+variable @var{tabname}.  The property list @var{props} is applied to
+the abbrev table (@pxref{Abbrev Table Properties}).
 
 If this function is called more than once for the same @var{tabname},
 subsequent calls add the definitions in @var{definitions} to
@@ -132,20 +144,17 @@
 @section Defining Abbrevs
   @code{define-abbrev} is the low-level basic function for defining an
 abbrev in a specified abbrev table.  When major modes predefine standard
-abbrevs, they should call @code{define-abbrev} and specify @code{t} for
address@hidden  Be aware that any saved non-``system'' abbrevs are
+abbrevs, they should call @code{define-abbrev} and specify a @code{t} for
+the @code{system-flag} property.
+Be aware that any saved non-``system'' abbrevs are 
 restored at startup, i.e. before some major modes are loaded.  Major modes
 should therefore not assume that when they are first loaded their abbrev
 tables are empty.
 
address@hidden define-abbrev table name expansion &optional hook count 
system-flag
address@hidden define-abbrev table name expansion &optional hook &rest props
 This function defines an abbrev named @var{name}, in @var{table}, to
-expand to @var{expansion} and call @var{hook}.  The return value is
address@hidden
-
-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.
+expand to @var{expansion} and call @var{hook}, with properties
address@hidden (@pxref{Abbrev Properties}).  The return value is @var{name}.
 
 The argument @var{name} should be a string.  The argument
 @var{expansion} is normally the desired expansion (a string), or
@@ -167,12 +176,6 @@
 returns @code{nil}, @code{expand-abbrev} also returns @code{nil}, as
 if expansion had not really occurred.
 
-If @var{system-flag} is address@hidden, that marks the abbrev as a
-``system'' abbrev with the @code{system-type} property.  Unless
address@hidden has the value @code{force}, a ``system'' abbrev will
-not overwrite an existing definition for a non-``system'' abbrev of the
-same name.
-
 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
@@ -329,20 +332,19 @@
 @code{expand-abbrev} for the sake of the @code{unexpand-abbrev} command.
 @end defvar
 
address@hidden Emacs 19 feature
address@hidden 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.
-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.  (Although you have to do this carefully.  See
-the example below.)
address@hidden abbrev-expand-functions
+This is a special hook run @emph{around} the @code{expand-abbrev}
+function.  Functions on this hook are called with a single argument
+which is a function that performs the normal abbrev expansion.
+The hook function can hence do anything it wants before and after
+performing the expansion.  It can also choose not to call its argument
+and thus override the default behavior, or it may even call it
+several times.  The function should return the abbrev symbol if
+expansion took place.
 @end defvar
 
   The following sample code shows a simple use of
address@hidden  It assumes that @code{foo-mode} is a
address@hidden  It assumes that @code{foo-mode} is a
 mode for editing certain files in which lines that start with @samp{#}
 are comments.  You want to use Text mode abbrevs for those lines.  The
 regular local abbrev table, @code{foo-mode-abbrev-table} is
@@ -351,30 +353,22 @@
 definitions of @code{local-abbrev-table} and @code{text-mode-abbrev-table}.
 
 @smallexample
-(defun foo-mode-pre-abbrev-expand ()
-  (when (save-excursion (forward-line 0) (eq (char-after) ?#))
-    (let ((local-abbrev-table text-mode-abbrev-table)
-         ;; Avoid infinite loop.
-         (pre-abbrev-expand-hook nil))
-      (expand-abbrev))
-    ;; We have already called `expand-abbrev' in this hook.
-    ;; Hence we want the "actual" call following this hook to be a no-op.
-    (setq abbrev-start-location (point-max)
-         abbrev-start-location-buffer (current-buffer))))
+(defun foo-mode-abbrev-expand-function (expand)
+  (if (not (save-excursion (forward-line 0) (eq (char-after) ?#)))
+      ;; Performs normal expansion.
+      (funcall expand)
+    ;; We're inside a comment: use the text-mode abbrevs.
+    (let ((local-abbrev-table text-mode-abbrev-table))
+      (funcall expand))))
 
 (add-hook 'foo-mode-hook
          #'(lambda ()
-             (add-hook 'pre-abbrev-expand-hook
-                       'foo-mode-pre-abbrev-expand
+             (add-hook 'abbrev-expand-functions
+                       'foo-mode-abbrev-expand-function
                        nil t)))
 @end smallexample
 
-Note that @code{foo-mode-pre-abbrev-expand} just returns @code{nil}
-without doing anything for lines not starting with @samp{#}.  Hence
-abbrevs expand normally using @code{foo-mode-abbrev-table} as local
-abbrev table for such lines.
-
address@hidden Standard Abbrev Tables,  , Abbrev Expansion, Abbrevs
address@hidden Standard Abbrev Tables, Abbrev Properties, Abbrev Expansion, 
Abbrevs
 @comment  node-name,  next,  previous,  up
 @section Standard Abbrev Tables
 
@@ -390,7 +384,16 @@
 
 @defvar local-abbrev-table
 The value of this buffer-local variable is the (mode-specific)
-abbreviation table of the current buffer.
+abbreviation table of the current buffer.  It can also be a list of
+such tables.
address@hidden defvar
+
address@hidden abbrev-minor-mode-table-alist
+The value of this variable is a list of elements of the form
address@hidden(@var{mode} . @var{abbrev-table})} where @var{mode} is the name
+of a variable: if the variable is bound to a address@hidden value,
+then the @var{abbrev-table} is active, otherwise it is ignored.
address@hidden can also be a list of abbrev tables.
 @end defvar
 
 @defvar fundamental-mode-abbrev-table
@@ -406,6 +409,105 @@
 This is the local abbrev table used in Lisp mode and Emacs Lisp mode.
 @end defvar
 
address@hidden Abbrev Properties, Abbrev Table Properties, Standard Abbrev 
Tables, Abbrevs
address@hidden Abbrev Properties
+
+Abbrevs have properties, some of which influence the way they work.
+They are usually set by providing the relevant arguments to
address@hidden and can be manipulated with the functions:
+
address@hidden abbrev-put abbrev prop val
+Set the property @var{prop} of abbrev @var{abbrev} to value @var{val}.
address@hidden defun
+
address@hidden abbrev-get abbrev prop
+Return the property @var{prop} of abbrev @var{abbrev}, or @code{nil}
+if the abbrev has no such property.
address@hidden defun
+
+The following properties have special meaning:
+
address@hidden @code
address@hidden count
+This property counts the number of times the abbrev has
+been expanded.  If not explicitly set, it is initialized to 0 by
address@hidden
+
address@hidden system-flag
+If address@hidden, this property marks the abbrev as a ``system''
+abbrev.  Such abbrevs will not be saved to @var{abbrev-file-name}.
+Also, unless @code{system-flag} has the value @code{force},
+a ``system'' abbrev will not overwrite an existing definition for
+a non-``system'' abbrev of the same name.
+
address@hidden :enable-function
+If address@hidden, this property should be set to a function of no
+arguments which returns @code{nil} if the abbrev should not be used
+and @code{t} otherwise.
+
address@hidden :case-fixed
+If address@hidden, this property indicates that the case of the
+abbrev's name is significant and should only match a text with the
+same capitalization.  It also disables the code that modifies the
+capitalization of the expansion.
+
address@hidden table
+
address@hidden Abbrev Table Properties,  , Abbrev Properties, Abbrevs
address@hidden Abbrev Table Properties
+
+Like abbrevs, abble tables have properties, some of which influence
+the way they work.  They are usually set by providing the relevant
+arguments to @code{define-abbrev-table} and can be manipulated with
+the functions:
+
address@hidden abbrev-table-put table prop val
+Set the property @var{prop} of abbrev table @var{table} to value @var{val}.
address@hidden defun
+
address@hidden abbrev-table-get table prop
+Return the property @var{prop} of abbrev table @var{table}, or @code{nil}
+if the abbrev has no such property.
address@hidden defun
+
+The following properties have special meaning:
+
address@hidden @code
address@hidden :enable-function
+If address@hidden, this property should be set to a function of no
+arguments which returns @code{nil} if the abbrev table should not be
+used and @code{t} otherwise.  This is like the @code{:enable-function}
+abbrev property except that it applies to all abbrevs in the table and
+is used even before trying to find the abbrev before point.
+
address@hidden :case-fixed
+If address@hidden, this property indicates that the case of the names
+is significant for all abbrevs in the table and should only match
+a text with the same capitalization.  It also disables the code that
+modifies the capitalization of the expansion.  This is like the
address@hidden:case-fixed} abbrev property except that it applies to all
+abbrevs in the table.
+
address@hidden :regexp
+If address@hidden, this property is a regular expression that
+indicates how to extract the name of the abbrev before point before
+looking it up in the table.  When the regular expression matches
+before point, the abbrev name is expected to be in submatch 1.
+If this property is nil, @code{expand-function} defaults to
address@hidden"\\<\\(\\w+\\)\\W"}.  This property allows the use of abbrevs
+whose name contains characters of non-word syntax.
+
address@hidden :parents
+This property holds the list of tables from which to inherit
+other abbrevs.
+
address@hidden :abbrev-table-modiff
+This property holds a counter incremented each time a new abbrev is
+added to the table.
+
address@hidden table
+
+
 @ignore
    arch-tag: 5ffdbe08-2cd4-48ec-a5a8-080f95756eec
 @end ignore