diff options
author | Glenn Morris <rgm@gnu.org> | 2014-05-26 18:09:45 -0700 |
---|---|---|
committer | Glenn Morris <rgm@gnu.org> | 2014-05-26 18:09:45 -0700 |
commit | e38a5ebe6b225ecb31008cafcbd51d85c2305618 (patch) | |
tree | 6454216bb8f7e3cd6249d0ea80b3cc6b2741a95d | |
parent | cf2f54c4e3d8adb26e3f4b8e9e51364165877444 (diff) |
Doc updates re abbrev-expand-function
* doc/emacs/abbrevs.texi (Expanding Abbrevs): Update re abbrev-expand-function.
* doc/lispref/abbrevs.texi (Abbrev Expansion): Update for expand-abbrev changes.
* doc/lispref/functions.texi (Advising Functions): Standardize menu case.
* lisp/abbrev.el (abbrev-expand-functions, abbrev-expand-function)
(expand-abbrev, abbrev--default-expand): Doc fixes.
-rw-r--r-- | doc/emacs/ChangeLog | 4 | ||||
-rw-r--r-- | doc/emacs/abbrevs.texi | 5 | ||||
-rw-r--r-- | doc/lispref/ChangeLog | 5 | ||||
-rw-r--r-- | doc/lispref/abbrevs.texi | 39 | ||||
-rw-r--r-- | doc/lispref/functions.texi | 8 | ||||
-rw-r--r-- | lisp/ChangeLog | 5 | ||||
-rw-r--r-- | lisp/abbrev.el | 13 |
7 files changed, 49 insertions, 30 deletions
diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog index c97ef31572..2452119110 100644 --- a/doc/emacs/ChangeLog +++ b/doc/emacs/ChangeLog @@ -1,3 +1,7 @@ +2014-05-27 Glenn Morris <rgm@gnu.org> + + * abbrevs.texi (Expanding Abbrevs): Update re abbrev-expand-function. + 2014-05-21 Eli Zaretskii <eliz@gnu.org> * frames.texi (Fonts): Clarify which frames are affected by diff --git a/doc/emacs/abbrevs.texi b/doc/emacs/abbrevs.texi index 80a98ac316..04349454fe 100644 --- a/doc/emacs/abbrevs.texi +++ b/doc/emacs/abbrevs.texi @@ -206,8 +206,9 @@ to turn on Abbrev mode first. It may also be useful together with a special set of abbrev definitions for making several global replacements at once. This command is effective even if Abbrev mode is not enabled. - Expanding any abbrev runs @code{abbrev-expand-functions}, a special -hook. Functions in this special hook can make arbitrary changes to + The function @code{expand-abbrev} peforms the expansion by calling +the function that @code{abbrev-expand-function} specifies. By +changing this function you can make arbitrary changes to the abbrev expansion. @xref{Abbrev Expansion,,, elisp, The Emacs Lisp Reference Manual}. diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 87f2d85cc4..7593356073 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,8 @@ +2014-05-27 Glenn Morris <rgm@gnu.org> + + * abbrevs.texi (Abbrev Expansion): Update for expand-abbrev changes. + * functions.texi (Advising Functions): Standardize menu case. + 2014-05-17 Eli Zaretskii <eliz@gnu.org> * display.texi (Invisible Text): Clarify the description of diff --git a/doc/lispref/abbrevs.texi b/doc/lispref/abbrevs.texi index 45c2c4c17f..73a3f5f1e0 100644 --- a/doc/lispref/abbrevs.texi +++ b/doc/lispref/abbrevs.texi @@ -257,13 +257,16 @@ as in @code{abbrev-symbol}. @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 the -abbrev symbol if it did expansion, @code{nil} otherwise. - -If the abbrev symbol has a hook function that 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. +follow an abbrev, this command does nothing. To do the expansion, it +calls the function that is the value of the @code{abbrev-expand-function} +variable, with no arguments, and returns whatever that function does. + +The default expansion function returns the abbrev symbol if it did +expansion, and @code{nil} otherwise. If the abbrev symbol has a hook +function that 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 the default expansion function returns @code{nil}, +even though expansion did occur. @end deffn @defun abbrev-insert abbrev &optional name start end @@ -331,24 +334,21 @@ has already been unexpanded. This contains information left by @code{expand-abbrev} for the sake of the @code{unexpand-abbrev} command. @end defvar -@defvar abbrev-expand-functions -This is a wrapper hook (@pxref{Running Hooks}) run around the -@code{expand-abbrev} function. Each function on this hook is called -with a single argument: 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, thus overriding the default behavior; or it may even -call it several times. The function should return the abbrev symbol -if expansion took place. +@defvar abbrev-expand-function +The value of this variable is a function that @code{expand-abbrev} +will call with no arguments to do the expansion. The function can do +anything it wants before and after performing the expansion. +It should return the abbrev symbol if expansion took place. @end defvar The following sample code shows a simple use of -@code{abbrev-expand-functions}. It assumes that @code{foo-mode} is a +@code{abbrev-expand-function}. 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 appropriate for all other lines. @xref{Standard Abbrev Tables}, for the definitions of @code{local-abbrev-table} and @code{text-mode-abbrev-table}. +@xref{Advising Functions}, for details of @code{add-function}. @smallexample (defun foo-mode-abbrev-expand-function (expand) @@ -361,9 +361,8 @@ definitions of @code{local-abbrev-table} and @code{text-mode-abbrev-table}. (add-hook 'foo-mode-hook #'(lambda () - (add-hook 'abbrev-expand-functions - 'foo-mode-abbrev-expand-function - nil t))) + (add-function :around (local 'abbrev-expand-function) + #'foo-mode-abbrev-expand-function))) @end smallexample @node Standard Abbrev Tables diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index 9888411667..019c75ba02 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -1207,10 +1207,10 @@ specify how the two functions are composed, since there are many different ways to do it. The added function is also called an @emph{advice}. @menu -* Core Advising Primitives:: Primitives to Manipulate Advices -* Advising Named Functions:: Advising Named Functions -* Advice combinators:: Ways to compose advices -* Porting old advices:: Adapting code using the old defadvice +* Core Advising Primitives:: Primitives to manipulate advice. +* Advising Named Functions:: Advising named functions. +* Advice combinators:: Ways to compose advices. +* Porting old advices:: Adapting code using the old defadvice. @end menu @node Core Advising Primitives diff --git a/lisp/ChangeLog b/lisp/ChangeLog index 9d1e62baf8..60b684fd8a 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,3 +1,8 @@ +2014-05-27 Glenn Morris <rgm@gnu.org> + + * abbrev.el (abbrev-expand-functions, abbrev-expand-function) + (expand-abbrev, abbrev--default-expand): Doc fixes. + 2014-05-26 Paul Eggert <eggert@cs.ucla.edu> Include sources used to create macuvs.h. diff --git a/lisp/abbrev.el b/lisp/abbrev.el index 43b6a5583e..9e11adadfc 100644 --- a/lisp/abbrev.el +++ b/lisp/abbrev.el @@ -824,23 +824,28 @@ see `define-abbrev' for details." value)) (defvar abbrev-expand-functions nil - "Wrapper hook around `expand-abbrev'.") + "Wrapper hook around `abbrev--default-expand'.") (make-obsolete-variable 'abbrev-expand-functions 'abbrev-expand-function "24.4") (defvar abbrev-expand-function #'abbrev--default-expand - "Function to perform abbrev expansion. + "Function that `expand-abbrev' uses to perform abbrev expansion. Takes no argument and should return the abbrev symbol if expansion took place.") (defun expand-abbrev () "Expand the abbrev before point, if there is an abbrev there. Effective when explicitly called even when `abbrev-mode' is nil. -Returns the abbrev symbol, if expansion took place. (The actual -return value is that of `abbrev-insert'.)" +Before doing anything else, runs `pre-abbrev-expand-hook'. +Calls `abbrev-expand-function' with no argument to do the work, +and returns whatever it does. (This should be the abbrev symbol +if expansion occurred, else nil.)" (interactive) (run-hooks 'pre-abbrev-expand-hook) (funcall abbrev-expand-function)) (defun abbrev--default-expand () + "Default function to use for `abbrev-expand-function'. +This respects the wrapper hook `abbrev-expand-functions'. +Calls `abbrev-insert' to insert any expansion, and returns what it does." (with-wrapper-hook abbrev-expand-functions () (pcase-let ((`(,sym ,name ,wordstart ,wordend) (abbrev--before-point))) (when sym |