From c3a2c35f1db8f2597b7f17e5806ff83a25345540 Mon Sep 17 00:00:00 2001 From: Alan Mackenzie Date: Mon, 15 Dec 2014 11:54:42 +0000 Subject: [PATCH] "Advice" is a mass noun. Amend text accordingly. functions.texi: (Advising Functions, Core Advising Primitives) (Advising Named Functions, Advice combinators) (Porting old advice): Replace, e.g., "an advice" with "advice". --- doc/lispref/ChangeLog | 7 ++++ doc/lispref/functions.texi | 79 ++++++++++++++++++++------------------ 2 files changed, 48 insertions(+), 38 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 0d8458fabd1..bc9e991bb10 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,10 @@ +2014-12-15 Alan Mackenzie + + "Advice" is a mass noun. Amend text accordingly. + * functions.texi: (Advising Functions, Core Advising Primitives) + (Advising Named Functions, Advice combinators) + (Porting old advice): Replace, e.g., "an advice" with "advice". + 2014-12-13 Lars Magne Ingebrigtsen * files.texi (Relative File Names): Mention `directory-name-p'. diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index 50849d4228c..0ac084b668e 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -1204,17 +1204,17 @@ behavior with: The arguments @code{:before} and @code{:around} used in the above examples specify how the two functions are composed, since there are many different -ways to do it. The added function is also called an @emph{advice}. +ways to do it. The added function is also called a piece of @emph{advice}. @menu * Core Advising Primitives:: Primitives to manipulate advice. * Advising Named Functions:: Advising named functions. * Advice combinators:: Ways to compose advice. -* Porting old advices:: Adapting code using the old defadvice. +* Porting old advice:: Adapting code using the old defadvice. @end menu @node Core Advising Primitives -@subsection Primitives to manipulate advices +@subsection Primitives to manipulate advice @defmac add-function where place function &optional props This macro is the handy way to add the advice @var{function} to the function @@ -1245,22 +1245,25 @@ identify which function to remove. Typically used when @var{function} is an anonymous function. @item depth -This specifies how to order the advices, in case several advices are present. -By default, the depth is 0. A depth of 100 indicates that this advice should -be kept as deep as possible, whereas a depth of -100 indicates that it -should stay as the outermost advice. When two advices specify the same depth, -the most recently added advice will be outermost. - -For a @code{:before} advice, being outermost means that this advice will be run -first, before any other advice, whereas being innermost means that it will run -right before the original function, with no other advice run between itself and -the original function. Similarly, for an @code{:after} advice innermost means -that it will run right after the original function, with no other advice run in -between, whereas outermost means that it will be run very last after all -other advices. An innermost @code{:override} advice will only override the -original function and other advices will apply to it, whereas an outermost -@code{:override} advice will override not only the original function but all -other advices applied to it as well. +This specifies how to order the advice, should several pieces of +advice be present. By default, the depth is 0. A depth of 100 +indicates that this piece of advice should be kept as deep as +possible, whereas a depth of -100 indicates that it should stay as the +outermost piece. When two pieces of advice specify the same depth, +the most recently added one will be outermost. + +For @code{:before} advice, being outermost means that this advice will +be run first, before any other advice, whereas being innermost means +that it will run right before the original function, with no other +advice run between itself and the original function. Similarly, for +@code{:after} advice innermost means that it will run right after the +original function, with no other advice run in between, whereas +outermost means that it will be run right at the end after all other +advice. An innermost @code{:override} piece of advice will only +override the original function and other pieces of advice will apply +to it, whereas an outermost @code{:override} piece of advice will +override not only the original function but all other advice applied +to it as well. @end table If @var{function} is not interactive, then the combined function will inherit @@ -1298,7 +1301,7 @@ function, it can also be the @code{name} of the piece of advice. @end defun @defun advice-function-mapc f function-def -Call the function @var{f} for every advice that was added to +Call the function @var{f} for every piece of advice that was added to @var{function-def}. @var{f} is called with two arguments: the advice function and its properties. @end defun @@ -1326,7 +1329,7 @@ instead. This separate set of functions to manipulate pieces of advice applied to named functions, offers the following extra features compared to @code{add-function}: they know how to deal with macros and autoloaded functions, they let @code{describe-function} preserve the original docstring as -well as document the added advice, and they let you add and remove advices +well as document the added advice, and they let you add and remove advice before a function is even defined. @code{advice-add} can be useful for altering the behavior of existing calls @@ -1361,7 +1364,7 @@ up in a confusing situation where some calls (occurring from Lisp code) obey the advice and other calls (from C code) do not. @defmac define-advice symbol (where lambda-list &optional name depth) &rest body -This macro defines an advice and adds it to the function named +This macro defines a piece of advice and adds it to the function named @var{symbol}. The advice is an anonymous function if @var{name} is nil or a function named @code{symbol@@name}. See @code{advice-add} for explanation of other arguments. @@ -1375,23 +1378,23 @@ Add the advice @var{function} to the named function @var{symbol}. @defun advice-remove symbol function Remove the advice @var{function} from the named function @var{symbol}. -@var{function} can also be the @code{name} of an advice. +@var{function} can also be the @code{name} of a piece of advice. @end defun @defun advice-member-p function symbol Return non-@code{nil} if the advice @var{function} is already in the named function @var{symbol}. @var{function} can also be the @code{name} of -an advice. +a piece of advice. @end defun @defun advice-mapc function symbol -Call @var{function} for every advice that was added to the named function -@var{symbol}. @var{function} is called with two arguments: the advice function -and its properties. +Call @var{function} for every piece of advice that was added to the +named function @var{symbol}. @var{function} is called with two +arguments: the advice function and its properties. @end defun @node Advice combinators -@subsection Ways to compose advices +@subsection Ways to compose advice Here are the different possible values for the @var{where} argument of @code{add-function} and @code{advice-add}, specifying how the advice @@ -1503,14 +1506,14 @@ More specifically, the composition of the two functions behaves like: @end table -@node Porting old advices +@node Porting old advice @subsection Adapting code using the old defadvice A lot of code uses the old @code{defadvice} mechanism, which is largely made obsolete by the new @code{advice-add}, whose implementation and semantics is significantly simpler. -An old advice such as: +An old piece of advice such as: @example (defadvice previous-line (before next-line-at-end @@ -1547,11 +1550,11 @@ whereas the new advice mechanism needs: Note that @code{ad-activate} had a global effect: it activated all pieces of advice enabled for that specified function. If you wanted to only activate or -deactivate a particular advice, you needed to @emph{enable} or @emph{disable} -that advice with @code{ad-enable-advice} and @code{ad-disable-advice}. +deactivate a particular piece, you needed to @emph{enable} or @emph{disable} +it with @code{ad-enable-advice} and @code{ad-disable-advice}. The new mechanism does away with this distinction. -An around advice such as: +Around advice such as: @example (defadvice foo (around foo-around) @@ -1577,12 +1580,12 @@ modify the function's arguments (e.g., with @code{ad-set-arg}), and that would affect the argument values seen by the original function, whereas in the new @code{:before}, modifying an argument via @code{setq} in the advice has no effect on the arguments seen by the original function. -When porting a @code{before} advice which relied on this behavior, you'll need -to turn it into a new @code{:around} or @code{:filter-args} advice instead. +When porting @code{before} advice which relied on this behavior, you'll need +to turn it into new @code{:around} or @code{:filter-args} advice instead. -Similarly an old @code{after} advice could modify the returned value by -changing @code{ad-return-value}, whereas a new @code{:after} advice cannot, so -when porting such an old @code{after} advice, you'll need to turn it into a new +Similarly old @code{after} advice could modify the returned value by +changing @code{ad-return-value}, whereas new @code{:after} advice cannot, so +when porting such old @code{after} advice, you'll need to turn it into new @code{:around} or @code{:filter-return} advice instead. @node Obsolete Functions -- 2.39.2