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.

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index ddc459cc50e39b0c1152fed17de6811a7d40a709..54dbdb9c9b208ef2c59373fa1c01c64aa0ae675e 100644 (file)
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,5 +1,7 @@
 2012-02-04  Glenn Morris  <rgm@gnu.org>
 
+       * modes.texi (Running Hooks): Try to clarify with-wrapper-hook.
+
        * text.texi (Buffer Contents):
        Update filter-buffer-substring description.
 

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 0eda905f82fecded25ca225ef3d45a23be7ea337..638ab89e37fcc937be96a7421febdb44c718b38b 100644 (file)
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -135,21 +135,32 @@ This macro runs the abnormal hook @code{hook} as a series of nested
 ``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
-@var{hook} does the same as @var{body}, if it is called with arguments
-@var{args}.  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''
-@var{fun} 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
+@code{filter-buffer-substring} 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

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 89ce0f67408e037c4449834e2df2d09a4703d3ab..2d618c6454cdbf383531347c31e2b927e4e54e88 100644 (file)
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,5 +1,7 @@
 2012-02-04  Glenn Morris  <rgm@gnu.org>
 
+       * subr.el (with-wrapper-hook): Doc fixes.
+
        * simple.el (filter-buffer-substring-functions)
        (buffer-substring-filters, filter-buffer-substring): Doc fixes.
 

diff --git a/lisp/subr.el b/lisp/subr.el
index 36bca654208daef42717b7867d5d337b5616fc6b..e735fd9577db0b46b76338062b07acc707a5e78d 100644 (file)
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -1373,16 +1373,19 @@ around the preceding ones, like a set of nested `around' advices.
 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)))