Commit c7291ad9 authored by Glenn Morris's avatar Glenn Morris
Browse files

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.
parent 3723ec07
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.
......
......@@ -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
......
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.
......
......@@ -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)))
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment