Commit 25dec365 authored by Chong Yidong's avatar Chong Yidong

Update Compilation and Advice chapters in Lisp manual.

* doc/lispref/advice.texi (Defining Advice): Clarify ad-unadvise.
(Activation of Advice): Specifying the ACTIVATE flag in defadvice
is not abnormal.
(Advising Primitives): Node deleted; ad-define-subr-args has been
removed.

* doc/lispref/compile.texi (Speed of Byte-Code): Use float-time in example.
(Compilation Functions): Note that the log uses Compilation mode.
Don't discuss the contents of byte-code function object here.
(Compilation Functions): De-document internal function byte-code.
(Docs and Compilation): Minor clarifications.

* doc/lispref/objects.texi (Byte-Code Type): Add xref to Byte-Code Function
Objects.

* lisp/emacs-lisp/advice.el: Update commentary to reflect deletion of
ad-define-subr-args
parent d7c5e162
...@@ -180,13 +180,13 @@ xresources.texi cyd ...@@ -180,13 +180,13 @@ xresources.texi cyd
** Check the Lisp manual. ** Check the Lisp manual.
abbrevs.texi abbrevs.texi
advice.texi advice.texi cyd
anti.texi anti.texi
back.texi back.texi
backups.texi backups.texi
buffers.texi buffers.texi
commands.texi commands.texi
compile.texi compile.texi cyd
control.texi cyd control.texi cyd
customize.texi cyd customize.texi cyd
debugging.texi debugging.texi
......
2012-02-10 Chong Yidong <cyd@gnu.org>
* advice.texi (Defining Advice): Clarify ad-unadvise.
(Activation of Advice): Specifying the ACTIVATE flag in defadvice
is not abnormal.
(Advising Primitives): Node deleted; ad-define-subr-args has been
removed.
* compile.texi (Speed of Byte-Code): Use float-time in example.
(Compilation Functions): Note that the log uses Compilation mode.
Don't discuss the contents of byte-code function object here.
(Compilation Functions): De-document internal function byte-code.
(Docs and Compilation): Minor clarifications.
* objects.texi (Byte-Code Type): Add xref to Byte-Code Function
Objects.
2012-02-10 Glenn Morris <rgm@gnu.org> 2012-02-10 Glenn Morris <rgm@gnu.org>
* text.texi (Checksum/Hash): Rename node from MD5 Checksum. * text.texi (Checksum/Hash): Rename node from MD5 Checksum.
......
...@@ -13,30 +13,35 @@ for a library to customize functions defined within Emacs---cleaner ...@@ -13,30 +13,35 @@ for a library to customize functions defined within Emacs---cleaner
than redefining the whole function. than redefining the whole function.
@cindex piece of advice @cindex piece of advice
Each function can have multiple @dfn{pieces of advice}, separately Each function can have multiple @dfn{pieces of advice}, each of
defined. Each defined piece of advice can be @dfn{enabled} or which can be separately defined and then @dfn{enabled} or
@dfn{disabled} explicitly. All the enabled pieces of advice for any given @dfn{disabled}. All the enabled pieces of advice for any given
function actually take effect when you @dfn{activate} advice for that function actually take effect when you @dfn{activate advice} for that
function, or when you define or redefine the function. Note that function, or when you define or redefine the function. Note that
enabling a piece of advice and activating advice for a function enabling a piece of advice and activating advice for a function are
are not the same thing. not the same thing.
@strong{Usage Note:} Advice is useful for altering the behavior of Advice is useful for altering the behavior of existing calls to an
existing calls to an existing function. If you want the new behavior existing function. If you want the new behavior for new function
for new calls, or for key bindings, you should define a new function calls or new key bindings, you should define a new function or
(or a new command) which uses the existing function. command, and have it use the existing function as a subroutine.
@strong{Usage note:} Advising a function can cause confusion in Advising a function can cause confusion in debugging, since people
debugging, since people who debug calls to the original function may who debug calls to the original function may not notice that it has
not notice that it has been modified with advice. Therefore, if you been modified with advice. Therefore, if you have the possibility to
have the possibility to change the code of that function (or ask change the code of that function to run a hook, please solve the
someone to do so) to run a hook, please solve the problem that way. problem that way. Advice should be reserved for the cases where you
Advice should be reserved for the cases where you cannot get the cannot get the function changed. In particular, Emacs' own source
function changed. files should not put advice on functions in Emacs. There are
currently a few exceptions to this convention, but we aim to correct
In particular, this means that a file in Emacs should not put advice them.
on a function in Emacs. There are currently a few exceptions to this
convention, but we aim to correct them. Unless you know what you are doing, do @emph{not} advise a primitive
(@pxref{What Is a Function}). Some primitives are used by the advice
mechanism; advising them could cause an infinite recursion. Also,
many primitives are called directly from C code. Calls to the
primitive from Lisp code will take note of the advice, but calls from
C code will ignore the advice.
@menu @menu
* Simple Advice:: A simple example to explain the basics of advice. * Simple Advice:: A simple example to explain the basics of advice.
...@@ -48,7 +53,6 @@ convention, but we aim to correct them. ...@@ -48,7 +53,6 @@ convention, but we aim to correct them.
* Preactivation:: Preactivation is a way of speeding up the * Preactivation:: Preactivation is a way of speeding up the
loading of compiled advice. loading of compiled advice.
* Argument Access in Advice:: How advice can access the function's arguments. * Argument Access in Advice:: How advice can access the function's arguments.
* Advising Primitives:: Accessing arguments when advising a primitive.
* Combined Definition:: How advice is implemented. * Combined Definition:: How advice is implemented.
@end menu @end menu
...@@ -258,7 +262,7 @@ All subroutines used by the advice need to be available when the byte ...@@ -258,7 +262,7 @@ All subroutines used by the advice need to be available when the byte
compiler expands the macro. compiler expands the macro.
@deffn Command ad-unadvise function @deffn Command ad-unadvise function
This command deletes the advice from @var{function}. This command deletes all pieces of advice from @var{function}.
@end deffn @end deffn
@deffn Command ad-unadvise-all @deffn Command ad-unadvise-all
...@@ -355,13 +359,13 @@ replaced with the new one. ...@@ -355,13 +359,13 @@ replaced with the new one.
@cindex advice, activating @cindex advice, activating
By default, advice does not take effect when you define it---only when By default, advice does not take effect when you define it---only when
you @dfn{activate} advice for the function that was advised. However, you @dfn{activate} advice for the function. However, the advice will
the advice will be activated automatically if you define or redefine be activated automatically if you define or redefine the function
the function later. You can request the activation of advice for a later. You can request the activation of advice for a function when
function when you define the advice, by specifying the @code{activate} you define the advice, by specifying the @code{activate} flag in the
flag in the @code{defadvice}. But normally you activate the advice @code{defadvice}; or you can activate the advice separately by calling
for a function by calling the function @code{ad-activate} or one of the function @code{ad-activate} or one of the other activation
the other activation commands listed below. commands listed below.
Separating the activation of advice from the act of defining it permits Separating the activation of advice from the act of defining it permits
you to add several pieces of advice to one function efficiently, without you to add several pieces of advice to one function efficiently, without
...@@ -680,39 +684,6 @@ will be 3, and @var{r} will be @code{(2 1 0)} inside the body of ...@@ -680,39 +684,6 @@ will be 3, and @var{r} will be @code{(2 1 0)} inside the body of
These argument constructs are not really implemented as Lisp macros. These argument constructs are not really implemented as Lisp macros.
Instead they are implemented specially by the advice mechanism. Instead they are implemented specially by the advice mechanism.
@node Advising Primitives
@section Advising Primitives
@cindex advising primitives
Advising a primitive function (@pxref{What Is a Function}) is risky.
Some primitive functions are used by the advice mechanism; advising
them could cause an infinite recursion. Also, many primitive
functions are called directly from C code. Calls to the primitive
from Lisp code will take note of the advice, but calls from C code
will ignore the advice.
When the advice facility constructs the combined definition, it needs
to know the argument list of the original function. This is not
always possible for primitive functions. When advice cannot determine
the argument list, it uses @code{(&rest ad-subr-args)}, which always
works but is inefficient because it constructs a list of the argument
values. You can use @code{ad-define-subr-args} to declare the proper
argument names for a primitive function:
@defun ad-define-subr-args function arglist
This function specifies that @var{arglist} should be used as the
argument list for function @var{function}.
@end defun
For example,
@example
(ad-define-subr-args 'fset '(sym newdef))
@end example
@noindent
specifies the argument list for the function @code{fset}.
@node Combined Definition @node Combined Definition
@section The Combined Definition @section The Combined Definition
......
...@@ -32,9 +32,6 @@ variable binding for @code{no-byte-compile} into it, like this: ...@@ -32,9 +32,6 @@ variable binding for @code{no-byte-compile} into it, like this:
;; -*-no-byte-compile: t; -*- ;; -*-no-byte-compile: t; -*-
@end example @end example
@xref{Compilation Errors}, for how to investigate errors occurring in
byte compilation.
@menu @menu
* Speed of Byte-Code:: An example of speedup from byte compilation. * Speed of Byte-Code:: An example of speedup from byte compilation.
* Compilation Functions:: Byte compilation functions. * Compilation Functions:: Byte compilation functions.
...@@ -56,18 +53,16 @@ Here is an example: ...@@ -56,18 +53,16 @@ Here is an example:
@example @example
@group @group
(defun silly-loop (n) (defun silly-loop (n)
"Return time before and after N iterations of a loop." "Return the time, in seconds, to run N iterations of a loop."
(let ((t1 (current-time-string))) (let ((t1 (float-time)))
(while (> (setq n (1- n)) (while (> (setq n (1- n)) 0))
0)) (- (float-time) t1)))
(list t1 (current-time-string))))
@result{} silly-loop @result{} silly-loop
@end group @end group
@group @group
(silly-loop 50000000) (silly-loop 50000000)
@result{} ("Wed Mar 11 21:10:19 2009" @result{} 10.235304117202759
"Wed Mar 11 21:10:41 2009") ; @r{22 seconds}
@end group @end group
@group @group
...@@ -77,18 +72,17 @@ Here is an example: ...@@ -77,18 +72,17 @@ Here is an example:
@group @group
(silly-loop 50000000) (silly-loop 50000000)
@result{} ("Wed Mar 11 21:12:26 2009" @result{} 3.705854892730713
"Wed Mar 11 21:12:32 2009") ; @r{6 seconds}
@end group @end group
@end example @end example
In this example, the interpreted code required 22 seconds to run, In this example, the interpreted code required 10 seconds to run,
whereas the byte-compiled code required 6 seconds. These results are whereas the byte-compiled code required less than 4 seconds. These
representative, but actual results will vary greatly. results are representative, but actual results may vary.
@node Compilation Functions @node Compilation Functions
@comment node-name, next, previous, up @comment node-name, next, previous, up
@section The Compilation Functions @section Byte-Compilation Functions
@cindex compilation functions @cindex compilation functions
You can byte-compile an individual function or macro definition with You can byte-compile an individual function or macro definition with
...@@ -96,43 +90,36 @@ the @code{byte-compile} function. You can compile a whole file with ...@@ -96,43 +90,36 @@ the @code{byte-compile} function. You can compile a whole file with
@code{byte-compile-file}, or several files with @code{byte-compile-file}, or several files with
@code{byte-recompile-directory} or @code{batch-byte-compile}. @code{byte-recompile-directory} or @code{batch-byte-compile}.
The byte compiler produces error messages and warnings about each file Sometimes, the byte compiler produces warning and/or error messages
in a buffer called @samp{*Compile-Log*}. These report things in your (@pxref{Compiler Errors}, for details). These messages are recorded
program that suggest a problem but are not necessarily erroneous. in a buffer called @samp{*Compile-Log*}, which uses Compilation mode.
@xref{Compilation Mode,,,emacs, The GNU Emacs Manual}.
@cindex macro compilation @cindex macro compilation
Be careful when writing macro calls in files that you may someday Be careful when writing macro calls in files that you intend to
byte-compile. Macro calls are expanded when they are compiled, so the byte-compile. Since macro calls are expanded when they are compiled,
macros must already be defined for proper compilation. For more the macros need to be loaded into Emacs or the byte compiler will not
details, see @ref{Compiling Macros}. If a program does not work the do the right thing. The usual way to handle this is with
same way when compiled as it does when interpreted, erroneous macro @code{require} forms which specify the files containing the needed
definitions are one likely cause (@pxref{Problems with Macros}). macro definitions (@pxref{Named Features}). Normally, the
Inline (@code{defsubst}) functions are less troublesome; if you byte compiler does not evaluate the code that it is compiling, but it
handles @code{require} forms specially, by loading the specified
libraries. To avoid loading the macro definition files when someone
@emph{runs} the compiled program, write @code{eval-when-compile}
around the @code{require} calls (@pxref{Eval During Compile}). For
more details, @xref{Compiling Macros}.
Inline (@code{defsubst}) functions are less troublesome; if you
compile a call to such a function before its definition is known, the compile a call to such a function before its definition is known, the
call will still work right, it will just run slower. call will still work right, it will just run slower.
Normally, compiling a file does not evaluate the file's contents or
load the file. But it does execute any @code{require} calls at top
level in the file. One way to ensure that necessary macro definitions
are available during compilation is to require the file that defines
them (@pxref{Named Features}). To avoid loading the macro definition files
when someone @emph{runs} the compiled program, write
@code{eval-when-compile} around the @code{require} calls (@pxref{Eval
During Compile}).
@defun byte-compile symbol @defun byte-compile symbol
This function byte-compiles the function definition of @var{symbol}, This function byte-compiles the function definition of @var{symbol},
replacing the previous definition with the compiled one. The function replacing the previous definition with the compiled one. The function
definition of @var{symbol} must be the actual code for the function; definition of @var{symbol} must be the actual code for the function;
i.e., the compiler does not follow indirection to another symbol. @code{byte-compile} does not handle function indirection. The return
@code{byte-compile} returns the new, compiled definition of value is the byte-code function object which is the compiled
@var{symbol}. definition of @var{symbol} (@pxref{Byte-Code Objects}).
If @var{symbol}'s definition is a byte-code function object,
@code{byte-compile} does nothing and returns @code{nil}. Lisp records
only one function definition for any symbol, and if that is already
compiled, non-compiled code is not available anywhere. So there is no
way to ``compile the same definition again.''
@example @example
@group @group
...@@ -153,16 +140,15 @@ way to ``compile the same definition again.'' ...@@ -153,16 +140,15 @@ way to ``compile the same definition again.''
@end group @end group
@end example @end example
@noindent If @var{symbol}'s definition is a byte-code function object,
The result is a byte-code function object. The string it contains is @code{byte-compile} does nothing and returns @code{nil}. It does not
the actual byte-code; each character in it is an instruction or an ``compile the symbol's definition again'', since the original
operand of an instruction. The vector contains all the constants, (non-compiled) code has already been replaced in the symbol's function
variable names and function names used by the function, except for cell by the byte-compiled code.
certain primitives that are coded as special instructions.
The argument to @code{byte-compile} can also be a @code{lambda}
If the argument to @code{byte-compile} is a @code{lambda} expression, expression. In that case, the function returns the corresponding
it returns the corresponding compiled code, but does not store compiled code but does not store it anywhere.
it anywhere.
@end defun @end defun
@deffn Command compile-defun &optional arg @deffn Command compile-defun &optional arg
...@@ -252,19 +238,6 @@ files that have an up-to-date @samp{.elc} file. ...@@ -252,19 +238,6 @@ files that have an up-to-date @samp{.elc} file.
@end example @end example
@end defun @end defun
@defun byte-code code-string data-vector max-stack
@cindex byte-code interpreter
This function actually interprets byte-code. A byte-compiled function
is actually defined with a body that calls @code{byte-code}. Don't call
this function yourself---only the byte compiler knows how to generate
valid calls to this function.
In Emacs version 18, byte-code was always executed by way of a call to
the function @code{byte-code}. Nowadays, byte-code is usually executed
as part of a byte-code function object, and only rarely through an
explicit call to @code{byte-code}.
@end defun
@node Docs and Compilation @node Docs and Compilation
@section Documentation Strings and Compilation @section Documentation Strings and Compilation
@cindex dynamic loading of documentation @cindex dynamic loading of documentation
...@@ -290,33 +263,11 @@ then further access to documentation strings in this file will ...@@ -290,33 +263,11 @@ then further access to documentation strings in this file will
probably give nonsense results. probably give nonsense results.
@end itemize @end itemize
If your site installs Emacs following the usual procedures, these @noindent
problems will never normally occur. Installing a new version uses a new These problems normally occur only if you build Emacs yourself and use
directory with a different name; as long as the old version remains it from the directory where you built it, and you happen to edit
installed, its files will remain unmodified in the places where they are and/or recompile the Lisp source files. They can be easily cured by
expected to be. reloading each file after recompiling it.
However, if you have built Emacs yourself and use it from the
directory where you built it, you will experience this problem
occasionally if you edit and recompile Lisp files. When it happens, you
can cure the problem by reloading the file after recompiling it.
You can turn off this feature at compile time by setting
@code{byte-compile-dynamic-docstrings} to @code{nil}; this is useful
mainly if you expect to change the file, and you want Emacs processes
that have already loaded it to keep working when the file changes.
You can do this globally, or for one source file by specifying a
file-local binding for the variable. One way to do that is by adding
this string to the file's first line:
@example
-*-byte-compile-dynamic-docstrings: nil;-*-
@end example
@defvar byte-compile-dynamic-docstrings
If this is non-@code{nil}, the byte compiler generates compiled files
that are set up for dynamic loading of documentation strings.
@end defvar
@cindex @samp{#@@@var{count}} @cindex @samp{#@@@var{count}}
@cindex @samp{#$} @cindex @samp{#$}
...@@ -328,6 +279,23 @@ string.'' It is usually best not to use these constructs in Lisp source ...@@ -328,6 +279,23 @@ string.'' It is usually best not to use these constructs in Lisp source
files, since they are not designed to be clear to humans reading the files, since they are not designed to be clear to humans reading the
file. file.
You can disable the dynamic documentation string feature at compile
time by setting @code{byte-compile-dynamic-docstrings} to @code{nil};
this is useful mainly if you expect to change the file, and you want
Emacs processes that have already loaded it to keep working when the
file changes. You can do this globally, or for one source file by
specifying a file-local binding for the variable. One way to do that
is by adding this string to the file's first line:
@example
-*-byte-compile-dynamic-docstrings: nil;-*-
@end example
@defvar byte-compile-dynamic-docstrings
If this is non-@code{nil}, the byte compiler generates compiled files
that are set up for dynamic loading of documentation strings.
@end defvar
@node Dynamic Loading @node Dynamic Loading
@section Dynamic Loading of Individual Functions @section Dynamic Loading of Individual Functions
...@@ -541,17 +509,16 @@ one you intend to suppress. ...@@ -541,17 +509,16 @@ one you intend to suppress.
@cindex byte-code function @cindex byte-code function
Byte-compiled functions have a special data type: they are Byte-compiled functions have a special data type: they are
@dfn{byte-code function objects}. @dfn{byte-code function objects}. Whenever such an object appears as
a function to be called, Emacs uses the byte-code interpreter to
execute the byte-code.
Internally, a byte-code function object is much like a vector; Internally, a byte-code function object is much like a vector; its
however, the evaluator handles this data type specially when it appears elements can be accessed using @code{aref}. Its printed
as a function to be called. The printed representation for a byte-code representation is like that for a vector, with an additional @samp{#}
function object is like that for a vector, with an additional @samp{#} before the opening @samp{[}. It must have at least four elements;
before the opening @samp{[}. there is no maximum number, but only the first six elements have any
normal use. They are:
A byte-code function object must have at least four elements; there is
no maximum number, but only the first six elements have any normal use.
They are:
@table @var @table @var
@item arglist @item arglist
...@@ -588,7 +555,7 @@ representation. It is the definition of the command ...@@ -588,7 +555,7 @@ representation. It is the definition of the command
[arg 1 forward-sexp] [arg 1 forward-sexp]
2 2
254435 254435
"p"] "^p"]
@end example @end example
The primitive way to create a byte-code object is with The primitive way to create a byte-code object is with
...@@ -604,10 +571,6 @@ function yourself, because if they are inconsistent, Emacs may crash ...@@ -604,10 +571,6 @@ function yourself, because if they are inconsistent, Emacs may crash
when you call the function. Always leave it to the byte compiler to when you call the function. Always leave it to the byte compiler to
create these objects; it makes the elements consistent (we hope). create these objects; it makes the elements consistent (we hope).
You can access the elements of a byte-code object using @code{aref};
you can also use @code{vconcat} to create a vector with the same
elements.
@node Disassembly @node Disassembly
@section Disassembled Byte-Code @section Disassembled Byte-Code
@cindex disassembled byte-code @cindex disassembled byte-code
......
...@@ -548,7 +548,6 @@ Advising Emacs Lisp Functions ...@@ -548,7 +548,6 @@ Advising Emacs Lisp Functions
* Preactivation:: Preactivation is a way of speeding up the * Preactivation:: Preactivation is a way of speeding up the
loading of compiled advice. loading of compiled advice.
* Argument Access in Advice:: How advice can access the function's arguments. * Argument Access in Advice:: How advice can access the function's arguments.
* Advising Primitives:: Accessing arguments when advising a primitive.
* Combined Definition:: How advice is implemented. * Combined Definition:: How advice is implemented.
Debugging Lisp Programs Debugging Lisp Programs
......
...@@ -1323,11 +1323,11 @@ with the name of the subroutine. ...@@ -1323,11 +1323,11 @@ with the name of the subroutine.
@node Byte-Code Type @node Byte-Code Type
@subsection Byte-Code Function Type @subsection Byte-Code Function Type
The byte compiler produces @dfn{byte-code function objects}. @dfn{Byte-code function objects} are produced by byte-compiling Lisp
Internally, a byte-code function object is much like a vector; however, code (@pxref{Byte Compilation}). Internally, a byte-code function
the evaluator handles this data type specially when it appears as a object is much like a vector; however, the evaluator handles this data
function to be called. @xref{Byte Compilation}, for information about type specially when it appears in a function call. @xref{Byte-Code
the byte compiler. Objects}.
The printed representation and read syntax for a byte-code function The printed representation and read syntax for a byte-code function
object is like that for a vector, with an additional @samp{#} before the object is like that for a vector, with an additional @samp{#} before the
......
...@@ -568,7 +568,6 @@ Advising Emacs Lisp Functions ...@@ -568,7 +568,6 @@ Advising Emacs Lisp Functions
* Preactivation:: Preactivation is a way of speeding up the * Preactivation:: Preactivation is a way of speeding up the
loading of compiled advice. loading of compiled advice.
* Argument Access in Advice:: How advice can access the function's arguments. * Argument Access in Advice:: How advice can access the function's arguments.
* Advising Primitives:: Accessing arguments when advising a primitive.
* Combined Definition:: How advice is implemented. * Combined Definition:: How advice is implemented.
Debugging Lisp Programs Debugging Lisp Programs
......
...@@ -567,7 +567,6 @@ Advising Emacs Lisp Functions ...@@ -567,7 +567,6 @@ Advising Emacs Lisp Functions
* Preactivation:: Preactivation is a way of speeding up the * Preactivation:: Preactivation is a way of speeding up the
loading of compiled advice. loading of compiled advice.
* Argument Access in Advice:: How advice can access the function's arguments. * Argument Access in Advice:: How advice can access the function's arguments.
* Advising Primitives:: Accessing arguments when advising a primitive.
* Combined Definition:: How advice is implemented. * Combined Definition:: How advice is implemented.
Debugging Lisp Programs Debugging Lisp Programs
......
...@@ -348,10 +348,7 @@ ...@@ -348,10 +348,7 @@
;; first argument list defined in the list of before/around/after advices. ;; first argument list defined in the list of before/around/after advices.
;; The values of <arglist> variables can be accessed/changed in the body of ;; The values of <arglist> variables can be accessed/changed in the body of
;; an advice by simply referring to them by their original name, however, ;; an advice by simply referring to them by their original name, however,
;; more portable argument access macros are also provided (see below). For ;; more portable argument access macros are also provided (see below).
;; subrs/special-forms for which neither explicit argument list definitions
;; are available, nor their documentation strings contain such definitions
;; (as they do v19s), `(&rest ad-subr-args)' will be used.
;; <advised-docstring> is an optional, special documentation string which will ;; <advised-docstring> is an optional, special documentation string which will
;; be expanded into a proper documentation string upon call of `documentation'. ;; be expanded into a proper documentation string upon call of `documentation'.
...@@ -491,17 +488,15 @@ ...@@ -491,17 +488,15 @@
;; @@@ Argument list mapping: ;; @@@ Argument list mapping:
;; ========================== ;; ==========================
;; Because `defadvice' allows the specification of the argument list of the ;; Because `defadvice' allows the specification of the argument list
;; advised function we need a mapping mechanism that maps this argument list ;; of the advised function we need a mapping mechanism that maps this
;; onto that of the original function. For example, somebody might specify ;; argument list onto that of the original function. Hence SYM and
;; `(sym newdef)' as the argument list of `fset', while advice might use ;; NEWDEF have to be properly mapped onto the &rest variable when the
;; `(&rest ad-subr-args)' as the argument list of the original function ;; original definition is called. Advice automatically takes care of
;; (depending on what Emacs version is used). Hence SYM and NEWDEF have to ;; that mapping, hence, the advice programmer can specify an argument
;; be properly mapped onto the &rest variable when the original definition is ;; list without having to know about the exact structure of the
;; called. Advice automatically takes care of that mapping, hence, the advice ;; original argument list as long as the new argument list takes a
;; programmer can specify an argument list without having to know about the ;; compatible number/magnitude of actual arguments.
;; exact structure of the original argument list as long as the new argument
;; list takes a compatible number/magnitude of actual arguments.
;; @@ Activation and deactivation: ;; @@ Activation and deactivation:
;; =============================== ;; ===============================
...@@ -884,9 +879,6 @@ ...@@ -884,9 +879,6 @@
;; @@ Summary of forms with special meanings when used within an advice: ;; @@ Summary of forms with special meanings when used within an advice:
;; ===================================================================== ;; =====================================================================
;; ad-return-value name of the return value variable (get/settable)