[Emacs-diffs] emacs-24 r117158: Doc updates re abbrev-expand-function

[Glenn Morris]

------------------------------------------------------------
revno: 117158
revision-id: address@hidden
parent: address@hidden
committer: Glenn Morris <address@hidden>
branch nick: emacs-24
timestamp: Mon 2014-05-26 18:09:45 -0700
message:
  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.
modified:
  doc/emacs/ChangeLog            changelog-20091113204419-o5vbwnq5f7feedwu-6227
  doc/emacs/abbrevs.texi         
abbrevs.texi-20091113204419-o5vbwnq5f7feedwu-6229
  doc/lispref/ChangeLog          changelog-20091113204419-o5vbwnq5f7feedwu-6155
  doc/lispref/abbrevs.texi       
abbrevs.texi-20091113204419-o5vbwnq5f7feedwu-6158
  doc/lispref/functions.texi     
functions.texi-20091113204419-o5vbwnq5f7feedwu-6182
  lisp/ChangeLog                 changelog-20091113204419-o5vbwnq5f7feedwu-1432
  lisp/abbrev.el                 abbrev.el-20091113204419-o5vbwnq5f7feedwu-281

=== modified file 'doc/emacs/ChangeLog'
--- a/doc/emacs/ChangeLog       2014-05-21 16:35:31 +0000
+++ b/doc/emacs/ChangeLog       2014-05-27 01:09:45 +0000
@@ -1,3 +1,7 @@
+2014-05-27  Glenn Morris  <address@hidden>
+
+       * abbrevs.texi (Expanding Abbrevs): Update re abbrev-expand-function.
+
 2014-05-21  Eli Zaretskii  <address@hidden>
 
        * frames.texi (Fonts): Clarify which frames are affected by

=== modified file 'doc/emacs/abbrevs.texi'
--- a/doc/emacs/abbrevs.texi    2014-01-01 07:43:34 +0000
+++ b/doc/emacs/abbrevs.texi    2014-05-27 01:09:45 +0000
@@ -206,8 +206,9 @@
 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}.
 

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2014-05-17 08:58:17 +0000
+++ b/doc/lispref/ChangeLog     2014-05-27 01:09:45 +0000
@@ -1,3 +1,8 @@
+2014-05-27  Glenn Morris  <address@hidden>
+
+       * abbrevs.texi (Abbrev Expansion): Update for expand-abbrev changes.
+       * functions.texi (Advising Functions): Standardize menu case.
+
 2014-05-17  Eli Zaretskii  <address@hidden>
 
        * display.texi (Invisible Text): Clarify the description of

=== modified file 'doc/lispref/abbrevs.texi'
--- a/doc/lispref/abbrevs.texi  2014-01-01 07:43:34 +0000
+++ b/doc/lispref/abbrevs.texi  2014-05-27 01:09:45 +0000
@@ -257,13 +257,16 @@
 
 @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.
+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.
 
-If the abbrev symbol has a hook function that is a symbol whose
address@hidden property is address@hidden, and if the hook
-function returns @code{nil} as its value, then @code{expand-abbrev}
-returns @code{nil} even though expansion did occur.
+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
address@hidden, 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 @@
 @code{expand-abbrev} for the sake of the @code{unexpand-abbrev} command.
 @end defvar
 
address@hidden abbrev-expand-functions
-This is a wrapper hook (@pxref{Running Hooks}) run around the
address@hidden 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.
address@hidden 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
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
 appropriate for all other lines.  @xref{Standard Abbrev Tables}, for the
 definitions of @code{local-abbrev-table} and @code{text-mode-abbrev-table}.
address@hidden Functions}, for details of @code{add-function}.
 
 @smallexample
 (defun foo-mode-abbrev-expand-function (expand)
@@ -361,9 +361,8 @@
 
 (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

=== modified file 'doc/lispref/functions.texi'
--- a/doc/lispref/functions.texi        2014-05-10 20:07:01 +0000
+++ b/doc/lispref/functions.texi        2014-05-27 01:09:45 +0000
@@ -1207,10 +1207,10 @@
 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

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2014-05-26 15:48:28 +0000
+++ b/lisp/ChangeLog    2014-05-27 01:09:45 +0000
@@ -1,3 +1,8 @@
+2014-05-27  Glenn Morris  <address@hidden>
+
+       * abbrev.el (abbrev-expand-functions, abbrev-expand-function)
+       (expand-abbrev, abbrev--default-expand): Doc fixes.
+
 2014-05-26  Paul Eggert  <address@hidden>
 
        Include sources used to create macuvs.h.

=== modified file 'lisp/abbrev.el'
--- a/lisp/abbrev.el    2014-02-10 01:34:22 +0000
+++ b/lisp/abbrev.el    2014-05-27 01:09:45 +0000
@@ -824,23 +824,28 @@
     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