(Top): Update node listing.

[bpt/emacs.git] / doc / lispref / advice.texi

diff --git a/doc/lispref/advice.texi b/doc/lispref/advice.texi
index 7eb89d7..bb65d29 100644 (file)
--- a/doc/lispref/advice.texi
+++ b/doc/lispref/advice.texi
@@ -1,7 +1,7 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
 @c Copyright (C) 1998, 1999, 2001, 2002, 2003, 2004,
-@c   2005, 2006, 2007  Free Software Foundation, Inc.
+@c   2005, 2006, 2007, 2008, 2009  Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../../info/advising
 @node Advising Functions, Debugging, Byte Compilation, Top
@@ -314,26 +314,36 @@ using the function @code{ad-add-advice}.
 
 @defun ad-add-advice function advice class position
 Calling @code{ad-add-advice} adds @var{advice} as a piece of advice to
-@var{function} in class @var{class}.  The argument @var{advice}  has
+@var{function} in class @var{class}.  The argument @var{advice} has
 this form:
 
 @example
 (@var{name} @var{protected} @var{enabled} @var{definition})
 @end example
 
-Here @var{protected} and @var{enabled} are flags, and @var{definition}
-is the expression that says what the advice should do.  If @var{enabled}
-is @code{nil}, this piece of advice is initially disabled
-(@pxref{Enabling Advice}).
+@noindent
+Here, @var{protected} and @var{enabled} are flags; if @var{protected}
+is non-@code{nil}, the advice is protected against non-local exits
+(@pxref{Defining Advice}), and if @var{enabled} is @code{nil} the
+advice is initially disabled (@pxref{Enabling Advice}).
+@var{definition} should have the form
+
+@example
+(advice . @var{lambda})
+@end example
 
-If @var{function} already has one or more pieces of advice in the
-specified @var{class}, then @var{position} specifies where in the list
-to put the new piece of advice.  The value of @var{position} can either
-be @code{first}, @code{last}, or a number (counting from 0 at the
-beginning of the list).  Numbers outside the range are mapped to the
-beginning or the end of the range, whichever is closer.  The
-@var{position} value is ignored when redefining an existing piece of
-advice.
+@noindent
+where @var{lambda} is a lambda expression; this lambda expression is
+called in order to perform the advice.  @xref{Lambda Expressions}.
+
+If the @var{function} argument to @code{ad-add-advice} already has one
+or more pieces of advice in the specified @var{class}, then
+@var{position} specifies where in the list to put the new piece of
+advice.  The value of @var{position} can either be @code{first},
+@code{last}, or a number (counting from 0 at the beginning of the
+list).  Numbers outside the range are mapped to the beginning or the
+end of the range, whichever is closer.  The @var{position} value is
+ignored when redefining an existing piece of advice.
 
 If @var{function} already has a piece of @var{advice} with the same
 name, then the position argument is ignored and the old advice is
@@ -448,7 +458,7 @@ that results from activating advice for a function.
 A value of @code{always} specifies to compile unconditionally.
 A value of @code{never} specifies never compile the advice.
 
-A value of @code{maybe} specifies to compile if the byte-compiler is
+A value of @code{maybe} specifies to compile if the byte compiler is
 already loaded.  A value of @code{like-original} specifies to compile
 the advice if the original definition of the advised function is
 compiled or a built-in function.
@@ -545,11 +555,11 @@ work properly, because of a mismatch.
 Activation of the advised
 function takes longer than usual.
 @item
-The byte-compiler gets
+The byte compiler gets
 loaded while an advised function gets activated.
 @item
 @code{byte-compile} is included in the value of @code{features} even
-though you did not ever explicitly use the byte-compiler.
+though you did not ever explicitly use the byte compiler.
 @end itemize
 
 Compiled preactivated advice works properly even if the function itself