[Emacs-diffs] master c3a2c35 1/3: "Advice" is a mass noun. Amend text accordingly.

[Alan Mackenzie]

branch: master
commit c3a2c35f1db8f2597b7f17e5806ff83a25345540
Author: Alan Mackenzie <address@hidden>
Commit: Alan Mackenzie <address@hidden>

    "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 0d8458f..bc9e991 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,10 @@
+2014-12-15  Alan Mackenzie  <address@hidden>
+
+       "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  <address@hidden>
 
        * files.texi (Relative File Names): Mention `directory-name-p'.
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 50849d4..0ac084b 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
address@hidden Primitives to manipulate advices
address@hidden 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
address@hidden: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
address@hidden: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}.
address@hidden can also be the @code{name} of an advice.
address@hidden can also be the @code{name} of a piece of advice.
 @end defun
 
 @defun advice-member-p function symbol
 Return address@hidden 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
address@hidden  @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
address@hidden Ways to compose advices
address@hidden 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
 
 
address@hidden Porting old advices
address@hidden 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