@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1998, 1999 Free Software Foundation, Inc.
+@c Copyright (C) 1998, 1999, 2002, 2003, 2004,
+@c 2005 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/advising
@node Advising Functions, Debugging, Byte Compilation, Top
@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 cleaner 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
@strong{Usage Note:} Advice is useful for altering the behavior of
existing calls to an existing function. If you want the new behavior
-for new calls, or for key bindings, it is cleaner to define a new
-function (or a new command) which uses the existing function.
+for new calls, or for key bindings, you should define a new function
+(or a new command) which uses the existing function.
+
+ @strong{Usage note:} Advising a function can cause confusion in
+debugging, since people who debug calls to the original function may
+not notice that it has been modified with advice. Therefore, if you
+have the possibility to change the code of that function (or ask
+someone to do so) to run a hook, please solve the problem that way.
+Advice should be reserved for the cases where you cannot get the
+function changed.
+
+ In particular, this means that a file in Emacs should not put advice
+on a function in Emacs. There are currently a few exceptions to this
+convention, but we aim to correct them.
@menu
* Simple Advice:: A simple example to explain the basics of advice.
Suppose you wanted to add a similar feature to @code{previous-line},
which would insert a new line at the beginning of the buffer for the
-command to move to. How could you do this?
+command to move to (when @code{next-line-add-newlines} is
+non-@code{nil}). How could you do this?
You could do it by redefining the whole function, but that is not
modular. The advice feature provides a cleaner alternative: you can
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
@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
searches when the original definition of @code{foo} is run.
@defvar ad-do-it
-This is not really a variable, but it is somewhat used like one
-in around-advice. It specifies the place to run the function's
-original definition and other ``earlier'' around-advice.
+This is not really a variable, rather a place-holder that looks like a
+variable. You use it in around-advice to specify the place to run the
+function's original definition and other ``earlier'' around-advice.
@end defvar
If the around-advice does not use @code{ad-do-it}, then it does not run
@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
@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}.
@end deffn
-To activate advice for a function whose advice is already active is not
-a no-op. It is a useful operation which puts into effect any changes in
-that function's advice since the previous activation of advice for that
-function.
+ Activating advice does nothing if @var{function}'s advice is already
+active. But if there is new advice, added since the previous time you
+activated advice for @var{function}, it activates the new advice.
@deffn Command ad-deactivate function
This command deactivates the advice for @var{function}.
that results from activating advice for a function.
A value of @code{always} specifies to compile unconditionally.
-A value of @code{nil} specifies never compile the advice.
+A value of @code{never} specifies never compile the advice.
A value of @code{maybe} specifies to compile if the byte-compiler is
already loaded. A value of @code{like-original} specifies to compile
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''