diff lispref/advice.texi @ 22138:d4ac295a98b3

*** empty log message ***

--- a/lispref/advice.texi	Tue May 19 03:41:25 1998 +0000
+++ b/lispref/advice.texi	Tue May 19 03:45:57 1998 +0000
@@ -8,25 +8,96 @@
 @cindex advising functions
 
   The @dfn{advice} feature lets you add to the existing definition of a
-function, by @dfn{advising the function}.  This a clean method for 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
-than redefining the function in the usual way.
+than redefining the whole function.
 
   Each piece of advice can be enabled or disabled explicitly.  The
 enabled pieces of advice for any given function actually take effect
 when you activate advice for that function, or when that function is
 subsequently defined or redefined.
 
+  @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.
+
 @menu
-* Defining Advice::
-* Computed Advice::
-* Activation of Advice::
-* Enabling Advice::
-* Preactivation::
-* Argument Access in Advice::
-* Combined Definition::
+* Simple Advice::           A simple example to explain the basics of advice.
+* Defining Advice::         Detailed description of @code{defadvice}.
+* Computed Advice::         ...is to @code{defadvice} as @code{fset} is to @code{defun}.
+* Activation of Advice::    Advice doesn't do anything until you activate it.
+* Enabling Advice::         You can enable or disable each piece of advice.
+* Preactivation::           Preactivation is a way of speeding up the
+                              loading of compiled advice.
+* Argument Access::         How advice can access the function's arguments.
+* Subr Arguments::          Accessing arguments when advising a primitive.
+* Combined Definition::     How advice is implemented.
 @end menu
 
+@node Simple Advice
+@section A Simple Advice Example
+
+  The command @code{next-line} moves point down vertically one or more
+lines; it is the standard binding of @kbd{C-n}.  When used on the last
+line of the buffer, this command inserts a newline to create a line to
+move to (if @code{next-line-add-newlines} is non-@code{nil}).
+
+  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?
+
+  You could do it by redefining the whole function, but that is not
+modular.  The advice feature provides a cleaner alternative: you can
+effectively add your code to the existing function definition, without
+actually changing or even seeing that definition.  Here is how to do
+this:
+
+@example
+(defadvice previous-line (before next-line-at-end (arg))
+  "Insert an empty line when moving up from the top line."
+  (if (and next-line-add-newlines (= arg 1)
+           (save-excursion (beginning-of-line) (bobp)))
+      (progn
+        (beginning-of-line)
+        (newline))))
+@end example
+
+@cindex piece of advice
+  This expression defines a @dfn{piece of advice} for the function
+@code{previous-line}.  This piece of advice is named
+@code{next-line-at-end}, and the symbol @code{before} says that it is
+@dfn{before-advice} which should run before the regular definition of
+@code{previous-line}.  @code{(arg)} specifies how the advice code can
+refer to the function's arguments.
+
+  When this piece of advice runs, it creates an additional line, in the
+situation where that is appropriate, but does not move point to that
+line.  This is the correct way to write the advice, because the normal
+definition will run afterward and will move back to the newly inserted
+line.
+
+  Defining the advice doesn't immediately change the function
+@code{previous-line}.  That happens when you @dfn{activate} the advice,
+like this:
+
+@example
+(ad-activate 'previous-line)
+@end example
+
+@noindent
+This is what actually begins to use the advice that has been defined so
+far for the function @code{previous-line}.  Henceforth, whenever that
+function is run, whether invoked by the user with @kbd{C-p} or
+@kbd{M-x}, or called from Lisp, it runs the advice first, and its
+regular definition second.
+
+  This example illustrates before-advice, which is one @dfn{class} of
+advice: it runs before the function's base definition.  There are two
+other advice classes: @dfn{after-advice}, which runs after the base
+definition, and @dfn{around-advice}, which lets you specify an
+expression to wrap around the invocation of the base definition.
+
 @node Defining Advice
 @section Defining Advice
 
@@ -50,16 +121,11 @@
 describing the entity being advised, but this always includes macros and
 special forms.
 
-The argument @var{name} is the name of the advice, a non-@code{nil}
-symbol.  The advice name uniquely identifies one piece of advice, within all
-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.
-
-Where an ordinary definition has an argument list, an advice definition
-needs several kinds of information.
-
-@var{class} specifies the class of the advice---one of @code{before},
+@cindex class of advice
+@cindex before-advice
+@cindex after-advice
+@cindex around-advice
+@var{class} specifies the @dfn{class} of the advice---one of @code{before},
 @code{after}, or @code{around}.  Before-advice runs before the function
 itself; after-advice runs after the function itself; around-advice is
 wrapped around the execution of the function itself.  After-advice and
@@ -75,6 +141,15 @@
 definition completely.  (It also overrides lower-positioned pieces of
 around-advice).
 
+The argument @var{name} is the name of the advice, a non-@code{nil}
+symbol.  The advice name uniquely identifies one piece of advice, within all
+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
@@ -84,35 +159,49 @@
 advice.
 
 The optional @var{arglist} can be used to define the argument list for
-the sake of advice.  This argument list should of course be compatible
-with the argument list of the original function, otherwise functions
-that call the advised function with the original argument list in mind
-will break.  If more than one piece of advice specifies an argument
+the sake of advice.  This becomes the argument list of the combined
+definition that is generated in order to run the advice (@pxref{Combined
+Definition}).  Therefore, the advice expressions can use the argument
+variables in this list to access argument values.
+
+This argument list must be compatible with the argument list of the
+original function, so that it can handle the ways the function is
+actually called.  If more than one piece of advice specifies an argument
 list, then the first one (the one with the smallest position) found in
-the list of all classes of advice will be used.
+the list of all classes of advice is used.  Numbers outside the range
+are mapped to the beginning or the end, whichever is closer.
 
-@var{flags} is a list of symbols that specify further information about
-how to use this piece of advice.  Here are the valid symbols and their
-meanings:
+The remaining elements, @var{flags}, is a list of symbols that specify
+further information about how to use this piece of advice.  Here are the
+valid symbols and their meanings:
 
 @table @code
 @item activate
-Activate all the advice for @var{function} after making this definition.
-This is ignored when @var{function} itself is not defined yet (which is
-known as @dfn{forward advice}).
+Activate the advice for @var{function} now.  Changes in a function's
+advice always take effect the next time you activate advice for the
+function; this flag says to do so, for @var{function}, immediately after
+defining this piece of advice.
+
+@cindex forward advice
+This flag has no effect if @var{function} itself is not defined yet (a
+situation known as @dfn{forward advice}), because it is impossible to
+activate an undefined function's advice.  However, defining
+@var{function} will automatically activate its advice.
 
 @item protect
 Protect this piece of advice against non-local exits and errors in
-preceding code and advice.
+preceding code and advice.  Protecting advice makes it a cleanup in an
+@code{unwind-protect} form, so that it will execute even if the
+previous code gets an error or uses @code{throw}.  @xref{Cleanups}.
 
 @item compile
-Says that the combined definition which implements advice should be
-byte-compiled.  This flag is ignored unless @code{activate} is also
-specified.
+Compile the combined definition that is used to run the advice.  This
+flag is ignored unless @code{activate} is also specified.
+@xref{Combined Definition}.
 
 @item disable
-Disable this piece of advice, so that it will not be used
-unless subsequently explicitly enabled.
+Initially disable this piece of advice, so that it will not be used
+unless subsequently explicitly enabled.  @xref{Enabling Advice}.
 
 @item preactivate
 Activate advice for @var{function} when this @code{defadvice} is
@@ -124,10 +213,10 @@
 @end table
 
 The optional @var{documentation-string} serves to document this piece of
-advice.  If the @code{documentation} function gets the documentation
-for @var{function} when its advice is active, the result will combine
-the documentation strings of all the advice with that of the original
-function.
+advice.  When advice is active for @var{function}, the documentation for
+@var{function} (as returned by @code{documentation}) combines the
+documentation strings of all the advice for @var{function} with the
+documentation string of its original function definition.
 
 The optional @var{interactive-form} form can be supplied to change the
 interactive behavior of the original function.  If more than one piece
@@ -162,7 +251,9 @@
 @end example
 
 Here @var{protected} and @var{enabled} are flags, and @var{definition}
-is an expression that says what the advice should do.
+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}).
 
 If @var{function} already has one or more pieces of advice in the
 specified @var{class}, then @var{position} specifies where in the list
@@ -194,11 +285,12 @@
 importantly, it permits defining advice for a function before that
 function is actually defined.
 
-When a function is first activated, its original definition is saved,
-and all enabled pieces of advice for that function are combined with the
-original definition to make a new definition.  This definition is
-installed, and optionally byte-compiled as well, depending on conditions
-described below.
+When a function's advice is first activated, the function's original
+definition is saved, and all enabled pieces of advice for that function
+are combined with the original definition to make a new definition.
+(Pieces of advice that are currently disabled are not used; see
+@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
@@ -208,9 +300,9 @@
 This command activates the advice for @var{function}.
 @end deffn
 
-To activate a function whose advice is already active is not a no-op.
-It is a useful operation which puts into effect any changes in advice
-since the previous activation of the same function.
+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
+advice since the previous activation of that function's advice.
 
 @deffn Command ad-deactivate function
 This command deactivates the advice for @var{function}.
@@ -239,7 +331,18 @@
 
 @deffn Command ad-update-regexp regexp &optional compile
 This command activates pieces of advice whose names match @var{regexp},
-but only those that are already activated.
+but only those for functions whose advice is already activated.
+
+Reactivating a function's advice is useful for putting into effect all
+the changes that have been made in its advice (including enabling and
+disabling specific pieces of advice; @pxref{Enabling Advice}) since the
+last time it was activated.
+@end deffn
+
+@deffn Command ad-start-advice
+Turn on automatic advice activation when a function is defined or
+redefined.  If you turn on this mode, then advice really does
+take effect immediately when defined.
 @end deffn
 
 @deffn Command ad-stop-advice
@@ -247,11 +350,6 @@
 redefined.
 @end deffn
 
-@deffn Command ad-start-advice
-Turn off automatic advice activation when a function is defined or
-redefined.
-@end deffn
-
 @defopt ad-default-compilation-action
 This variable controls whether to compile the combined definition
 that results from activating advice for a function.
@@ -275,8 +373,8 @@
 (ad-disable-advice 'foo 'before 'my-advice)
 @end example
 
-  This call by itself only changes the enable flag for this piece of
-advice.  To make this change take effect in the advised definition, you
+This function by itself only changes the enable flag for a piece of
+advice.  To make the change take effect in the advised definition, you
 must activate the advice for @code{foo} again:
 
 @example
@@ -293,8 +391,10 @@
 @var{class} on @var{function}.
 @end deffn
 
-  You can also disable many pieces of advice at once using a regular
-expression.
+  You can also disable many pieces of advice at once, for various
+functions, using a regular expression.  As always, the changes take real
+effect only when you next reactivate advice for the functions in
+question.
 
 @deffn Command ad-disable-regexp regexp
 This command disables all pieces of advice whose names match
@@ -322,12 +422,12 @@
 @code{defadvice} is compiled, that compiles the combined definition
 also.
 
-  When the function is subsequently activated, if the enabled advice for
-the function matches what was used to make this combined
-definition. then the existing combined definition is used, and there is
-no need to construct one.  Thus, preactivation never causes wrong
+  When the function's advice is subsequently activated, if the enabled
+advice for the function matches what was used to make this combined
+definition, then the existing combined definition is used, thus avoiding
+the need to construct one.  Thus, preactivation never causes wrong
 results---but it may fail to do any good, if the enabled advice at the
-time of activation doesn't match.
+time of activation doesn't match what was used for preactivation.
 
   Here are some symptoms that can indicate that a preactivation did not
 work properly, because of a mismatch.
@@ -351,8 +451,8 @@
 There is no elegant way to find out why preactivated advice is not being
 used.  What you can do is to trace the function
 @code{ad-cache-id-verification-code} (with the function
-@code{trace-function-background}) before the advised function is
-activated.  After activation, check the value returned by
+@code{trace-function-background}) before the advised function's advice
+is activated.  After activation, check the value returned by
 @code{ad-cache-id-verification-code} for that function: @code{verified}
 means that the preactivated advice was used, while other values give
 some information about why they were considered inappropriate.
@@ -376,6 +476,13 @@
 into the advice.  If the definition of the original function changes,
 the advice might break.
 
+  Another method is to specify an argument list in the advice itself.
+This avoids the need to know the original function definition's argument
+names, but it has a limitation: all the advice on any particular
+function must use the same argument list, because the argument list
+actually used for all the advice comes from the first piece of advice
+for that function.
+
   A more robust method is to use macros that are translated into the
 proper access forms at activation time, i.e., when constructing the
 advised definition.  Access macros access actual arguments by position
@@ -456,7 +563,8 @@
   These argument constructs are not really implemented as Lisp macros.
 Instead they are implemented specially by the advice mechanism.
 
-@subsection Definition of Subr Argument Lists
+@node Subr Arguments
+@section Definition of Subr Argument Lists
 
   When the advice facility constructs the combined definition, it needs
 to know the argument list of the original function.  This is not always