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.

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.
 

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

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.
 

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.
+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.
 
-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
+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)))