(Advising Functions): Don't imply one part of Emacs

should advise another part.  Markup changes.
(Defining Advice): Move transitional para.
(Activation of Advice): Cleanup.
Explain if COMPILE is nil or negative.

1 files changed, 17 insertions, 16 deletions

diff --git a/lispref/advice.texi b/lispref/advice.texi
index ae22fecc1fb..2006474fc61 100644
--- a/lispref/advice.texi
+++ b/lispref/advice.texi
@@ -7,15 +7,15 @@
 @chapter Advising Emacs Lisp Functions
 @cindex advising functions
 
-  The @dfn{advice} feature lets you add to the existing definition of a
-function, by @dfn{advising the function}.  This is a clean method for a
-library to customize functions defined by other parts of Emacs---cleaner
+  The @dfn{advice} feature lets you add to the existing definition of
+a function, by @dfn{advising the function}.  This is a clean method
+for a library to customize functions defined within Emacs---cleaner
 than redefining the whole function.
 
 @cindex piece of advice
   Each function can have multiple @dfn{pieces of advice}, separately
 defined.  Each defined piece of advice can be @dfn{enabled} or
-disabled explicitly.  All the enabled pieces of advice for any given
+@dfn{disabled} explicitly.  All the enabled pieces of advice for any given
 function actually take effect when you @dfn{activate} advice for that
 function, or when you define or redefine the function.  Note that
 enabling a piece of advice and activating advice for a function
@@ -129,6 +129,9 @@ form) to be advised.  From now on, we will write just ``function'' when
 describing the entity being advised, but this always includes macros and
 special forms.
 
+  In place of the argument list in an ordinary definition, an advice
+definition calls for several different pieces of information.
+
 @cindex class of advice
 @cindex before-advice
 @cindex after-advice
@@ -154,9 +157,6 @@ the pieces of advice in a particular class for a particular
 @var{function}.  The name allows you to refer to the piece of
 advice---to redefine it, or to enable or disable it.
 
-In place of the argument list in an ordinary definition, an advice
-definition calls for several different pieces of information.
-
 The optional @var{position} specifies where, in the current list of
 advice of the specified @var{class}, this new advice should be placed.
 It should be either @code{first}, @code{last} or a number that specifies
@@ -332,9 +332,9 @@ replaced with the new one.
 @cindex advice, activating
 
 By default, advice does not take effect when you define it---only when
-you @dfn{activate} advice for the function that was advised.  However
-the advice will be automatically activated if the function is defined
-or redefined later.  You can request the activation of advice for a
+you @dfn{activate} advice for the function that was advised.  However,
+the advice will be activated automatically if you define or redefine
+the function later.  You can request the activation of advice for a
 function when you define the advice, by specifying the @code{activate}
 flag in the @code{defadvice}.  But normally you activate the advice
 for a function by calling the function @code{ad-activate} or one of
@@ -353,9 +353,11 @@ are combined with the original definition to make a new definition.
 @ref{Enabling Advice}.)  This definition is installed, and optionally
 byte-compiled as well, depending on conditions described below.
 
-In all of the commands to activate advice, if @var{compile} is @code{t},
-the command also compiles the combined definition which implements the
-advice.
+In all of the commands to activate advice, if @var{compile} is
+@code{t} (or anything but @code{nil} or a negative number), the
+command also compiles the combined definition which implements the
+advice.  If it is @code{nil} or a negative number, what happens
+depends on @code{ad-default-compilation-action} as described below.
 
 @deffn Command ad-activate function &optional compile
 This command activates all the advice defined for @var{function}.
@@ -438,9 +440,8 @@ the advice if the original definition of the advised function is
 compiled or a built-in function.
 
 This variable takes effect only if the @var{compile} argument of
-@code{ad-activate} (or any of the above functions) was supplied as
-@code{nil}.  If that argument is non-@code{nil}, that means
-to compile the advice regardless.
+@code{ad-activate} (or any of the above functions) did not force
+compilation.
 @end defopt
 
   If the advised definition was constructed during ``preactivation''