[Emacs-diffs] /srv/bzr/emacs/trunk r107097: with-wrapper-hook doc clarifications

[Glenn Morris]

------------------------------------------------------------
revno: 107097
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Sat 2012-02-04 12:59:54 -0800
message:
  with-wrapper-hook doc clarifications
  
  * doc/lispref/modes.texi (Running Hooks): Try to clarify with-wrapper-hook.
  * lisp/subr.el (with-wrapper-hook): Doc fixes.
modified:
  doc/lispref/ChangeLog
  doc/lispref/modes.texi
  lisp/ChangeLog
  lisp/subr.el

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-02-04 19:48:06 +0000
+++ b/doc/lispref/ChangeLog     2012-02-04 20:59:54 +0000
@@ -1,5 +1,7 @@
 2012-02-04  Glenn Morris  <address@hidden>
 
+       * modes.texi (Running Hooks): Try to clarify with-wrapper-hook.
+
        * text.texi (Buffer Contents):
        Update filter-buffer-substring description.
 

=== modified file 'doc/lispref/modes.texi'
--- a/doc/lispref/modes.texi    2012-02-02 04:37:05 +0000
+++ b/doc/lispref/modes.texi    2012-02-04 20:59:54 +0000
@@ -135,21 +135,32 @@
 ``wrapper functions'' around the @var{body} forms.  The effect is
 similar to nested @code{around} advices (@pxref{Around-Advice}).
 
-Each hook function must accept an argument list consisting of a function
+Each hook function should accept an argument list consisting of a function
 @var{fun}, followed by the additional arguments listed in @var{args}.
-The function @var{fun} passed to the very first hook function in
address@hidden does the same as @var{body}, if it is called with arguments
address@hidden  The @var{fun} passed to each successive hook function is
+The first hook function is passed a function @var{fun} that, if it is
+called with arguments @var{args}, performs @var{body} (i.e., the default
+operation).  The @var{fun} passed to each successive hook function is
 constructed from all the preceding hook functions (and @var{body}); if
 this @var{fun} is called with arguments @var{args}, it does what the
 @code{with-wrapper-hook} call would if the preceding hook functions were
 the only ones in @var{hook}.
 
-In the function definition of the hook function, @var{fun} can be called
-any number of times (including not calling it at all).  This function
-definition is then used to construct the @var{fun} passed to the next
-hook function in @var{hook}, if any.  The last or ``outermost''
address@hidden is called once to produce the effect.
+Each hook function may call its @var{fun} argument as many times as it
+wishes, including never.  In that case, such a hook function acts to
+replace the default definition altogether, and any preceding hook
+functions.  Of course, a subsequent hook function may do the same thing.
+
+Each hook function definition is used to construct the @var{fun} passed
+to the next hook function in @var{hook}, if any.  The last or
+``outermost'' @var{fun} is called once to produce the overall effect.
+
+When might you want to use a wrapper hook?  The function
address@hidden illustrates a common case.  There is a
+basic functionality, performed by @var{body}---in this case, to extract
+a buffer-substring.  Then any number of hook functions can act in
+sequence to modify that string, before returning the final result.
+A wrapper-hook also allows for a hook function to completely replace the
+default definition (by not calling @var{fun}).
 @end defmac
 
 @node Setting Hooks

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2012-02-04 19:48:06 +0000
+++ b/lisp/ChangeLog    2012-02-04 20:59:54 +0000
@@ -1,5 +1,7 @@
 2012-02-04  Glenn Morris  <address@hidden>
 
+       * subr.el (with-wrapper-hook): Doc fixes.
+
        * simple.el (filter-buffer-substring-functions)
        (buffer-substring-filters, filter-buffer-substring): Doc fixes.
 

=== modified file 'lisp/subr.el'
--- a/lisp/subr.el      2012-02-02 02:57:26 +0000
+++ b/lisp/subr.el      2012-02-04 20:59:54 +0000
@@ -1373,16 +1373,19 @@
 Each hook function should accept an argument list consisting of a
 function FUN, followed by the additional arguments in ARGS.
 
-The FUN passed to the first hook function in HOOK performs BODY,
-if it is called with arguments ARGS.  The FUN passed to each
-successive hook function is defined based on the preceding hook
-functions; if called with arguments ARGS, it does what the
-`with-wrapper-hook' call would do if the preceding hook functions
-were the only ones present in HOOK.
-
-In the function definition of each hook function, FUN can be
-called any number of times (including not calling it at all).
-That function definition is then used to construct the FUN passed
+The first hook function in HOOK is passed a FUN that, if it is called
+with arguments ARGS, performs BODY (i.e., the default operation).
+The FUN passed to each successive hook function is defined based
+on the preceding hook functions; if called with arguments ARGS,
+it does what the `with-wrapper-hook' call would do if the
+preceding hook functions were the only ones present in HOOK.
+
+Each hook function may call its FUN argument as many times as it wishes,
+including never.  In that case, such a hook function acts to replace
+the default definition altogether, and any preceding hook functions.
+Of course, a subsequent hook function may do the same thing.
+
+Each hook function definition is used to construct the FUN passed
 to the next hook function, if any.  The last (or \"outermost\")
 FUN is then called once."
   (declare (indent 2) (debug (form sexp body)))