From 122ff675df692bab3b5b6409044b0f0e66bad82f Mon Sep 17 00:00:00 2001 From: Stefan Monnier Date: Fri, 10 Jan 2014 14:40:32 -0500 Subject: [PATCH] * doc/lispref/functions.texi (Advising Functions): New section. * doc/lispref/modes.texi (Running Hooks): Don't document with-wrapper-hook and run-hook-wrapped any more. (Hooks): Link to the new Advising Functions node. * doc/lispref/elisp.texi (Top): Don't include advice.texi. * doc/lispref/advice.texi: Remove. * doc/lispref/makefile.w32-in (srcs): * doc/lispref/Makefile.in (srcs): Adjust accordingly. * doc/misc/cl.texi (Function Bindings): Fix incorrect description of cl-let. --- admin/FOR-RELEASE | 1 - doc/lispref/ChangeLog | 11 + doc/lispref/Makefile.in | 1 - doc/lispref/advice.texi | 749 ------------------------------------ doc/lispref/elisp.texi | 15 - doc/lispref/functions.texi | 274 ++++++++++++- doc/lispref/makefile.w32-in | 1 - doc/lispref/modes.texi | 51 +-- doc/misc/ChangeLog | 88 +++-- doc/misc/cl.texi | 9 +- etc/NEWS | 1 + 11 files changed, 334 insertions(+), 867 deletions(-) delete mode 100644 doc/lispref/advice.texi diff --git a/admin/FOR-RELEASE b/admin/FOR-RELEASE index 8470e7151c..8b6bddbbd2 100644 --- a/admin/FOR-RELEASE +++ b/admin/FOR-RELEASE @@ -218,7 +218,6 @@ xresources.texi cyd ** Check the Lisp manual. abbrevs.texi rgm -advice.texi cyd anti.texi rgm back.texi rgm backups.texi cyd diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 2963ffc9a6..38427e56b9 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,14 @@ +2014-01-10 Stefan Monnier + + * functions.texi (Advising Functions): New section. + * modes.texi (Running Hooks): Don't document with-wrapper-hook and + run-hook-wrapped any more. + (Hooks): Link to the new Advising Functions node. + * elisp.texi (Top): Don't include advice.texi. + * advice.texi: Remove. + * makefile.w32-in (srcs): + * Makefile.in (srcs): Adjust accordingly. + 2014-01-09 Rüdiger Sonderfeld * text.texi (Parsing HTML/XML): Document `shr-insert-document'. diff --git a/doc/lispref/Makefile.in b/doc/lispref/Makefile.in index 6f3320d029..bb8d4f8288 100644 --- a/doc/lispref/Makefile.in +++ b/doc/lispref/Makefile.in @@ -76,7 +76,6 @@ srcs = \ $(srcdir)/elisp.texi \ $(emacsdir)/emacsver.texi \ $(srcdir)/abbrevs.texi \ - $(srcdir)/advice.texi \ $(srcdir)/anti.texi \ $(srcdir)/backups.texi \ $(srcdir)/buffers.texi \ diff --git a/doc/lispref/advice.texi b/doc/lispref/advice.texi deleted file mode 100644 index c55f93d445..0000000000 --- a/doc/lispref/advice.texi +++ /dev/null @@ -1,749 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1998-1999, 2001-2014 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Advising Functions -@chapter Advising Emacs Lisp Functions -@cindex advising functions - -@cindex piece of advice - The @dfn{advice} feature lets you add to the existing definition of -a function, by @dfn{advising the function}. A function can have -multiple @dfn{pieces of advice}, each of which can be separately -defined, and separately enabled or disabled (@pxref{Activation of -Advice}). Each piece of advice can alter almost anything about the -function, including its argument list, what the function does when it -runs, and the value it returns. - - Advice can be useful for altering the behavior of an existing -function without having to redefine the whole function. However, it -can be a source of bugs, since existing callers to the function may -assume the old behavior, and work incorrectly when the behavior is -changed by advice. Advice can also cause confusion in debugging, if -the person doing the debugging does not notice or remember that the -function has been modified by advice. - - For these reasons, advice should be reserved for the cases where you -cannot modify a function's behavior in any other way. If it is -possible to do the same thing via a hook, that is preferable -(@pxref{Hooks}). If you simply want to change what a particular key -does, it may be better to write a new command, and remap the old -command's key bindings to the new one (@pxref{Remapping Commands}). -In particular, Emacs's own source files should not put advice on -functions in Emacs. (There are currently a few exceptions to this -convention, but we aim to correct them.) - - Macros can also be advised, in much the same way as functions. -However, special forms (@pxref{Special Forms}) cannot be advised. - - It is possible to advise a primitive (@pxref{What Is a Function}), -but one should typically @emph{not} do so, for two reasons. Firstly, -some primitives are used by the advice mechanism, and advising them -could cause an infinite recursion. Secondly, many primitives are -called directly from C, and such calls ignore advice; hence, one ends -up in a confusing situation where some calls (occurring from Lisp -code) obey the advice and other calls (from C code) do not. - -@menu -* Simple Advice:: A simple example to explain the basics of advice. -* Defining Advice:: Detailed description of @code{defadvice}. -* Around-Advice:: Wrapping advice around a function's definition. -* 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 in Advice:: How advice can access the function's arguments. -* 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} (its default -is @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 (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 -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 - (&optional arg try-vscroll)) - "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 - - 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{(&optional arg try-vscroll)} 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 -@cindex defining advice -@cindex advice, defining - - To define a piece of advice, use the macro @code{defadvice}. A call -to @code{defadvice} has the following syntax, which is based on the -syntax of @code{defun} and @code{defmacro}, but adds more: - -@findex defadvice -@example -(defadvice @var{function} (@var{class} @var{name} - @r{[}@var{position}@r{]} @r{[}@var{arglist}@r{]} - @var{flags}...) - @r{[}@var{documentation-string}@r{]} - @r{[}@var{interactive-form}@r{]} - @var{body-forms}...) -@end example - -@noindent -Here, @var{function} is the name of the function (or macro) to be -advised. From now on, we will write just ``function'' when describing -the entity being advised, but this always includes macros. - - 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 -@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 -around-advice can override the return value by setting -@code{ad-return-value}. - -@defvar ad-return-value -While advice is executing, after the function's original definition has -been executed, this variable holds its return value, which will -ultimately be returned to the caller after finishing all the advice. -After-advice and around-advice can arrange to return some other value -by storing it in this variable. -@end defvar - -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. - -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 -a zero-based position (@code{first} is equivalent to 0). If no position -is specified, the default is @code{first}. Position values outside the -range of existing positions in this class 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. - -The optional @var{arglist} can be used to define the argument list for -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. - -The argument list used in advice need not be the same as the argument -list used in the original function, but must be compatible with it, so -that it can handle the ways the function is actually called. If two -pieces of advice for a function both specify an argument list, they must -specify the same argument list. - -@xref{Argument Access in Advice}, for more information about argument -lists and advice, and a more flexible way for advice to access the -arguments. - -The remaining elements, @var{flags}, are 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 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 immediate 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. Protecting advice places it as 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 -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 -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 -compiled or macroexpanded. This generates a compiled advised definition -according to the current advice state, which will be used during -activation if appropriate. @xref{Preactivation}. - -This is useful only if this @code{defadvice} is byte-compiled. -@end table - -The optional @var{documentation-string} serves to document this piece of -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 -of advice has an @var{interactive-form}, then the first one (the one -with the smallest position) found among all the advice takes precedence. - -The possibly empty list of @var{body-forms} specifies the body of the -advice. The body of an advice can access or change the arguments, the -return value, the binding environment, and perform any other kind of -side effect. - -@strong{Warning:} When you advise a macro, keep in mind that macros are -expanded when a program is compiled, not when a compiled program is run. -All subroutines used by the advice need to be available when the byte -compiler expands the macro. - -@deffn Command ad-unadvise function -This command deletes all pieces of advice from @var{function}. -@end deffn - -@deffn Command ad-unadvise-all -This command deletes all pieces of advice from all functions. -@end deffn - -@node Around-Advice -@section Around-Advice - - Around-advice lets you ``wrap'' a Lisp expression ``around'' the -original function definition. You specify where the original function -definition should go by means of the special symbol @code{ad-do-it}. -Where this symbol occurs inside the around-advice body, it is replaced -with a @code{progn} containing the forms of the surrounded code. Here -is an example: - -@example -(defadvice foo (around foo-around) - "Ignore case in `foo'." - (let ((case-fold-search t)) - ad-do-it)) -@end example - -@noindent -Its effect is to make sure that case is ignored in -searches when the original definition of @code{foo} is run. - -@defvar ad-do-it -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 -the original function definition. This provides a way to override the -original definition completely. (It also overrides lower-positioned -pieces of around-advice). - -If the around-advice uses @code{ad-do-it} more than once, the original -definition is run at each place. In this way, around-advice can execute -the original definition (and lower-positioned pieces of around-advice) -several times. Another way to do that is by using @code{ad-do-it} -inside of a loop. - -@node Computed Advice -@section Computed Advice - -The macro @code{defadvice} resembles @code{defun} in that the code for -the advice, and all other information about it, are explicitly stated in -the source code. You can also create advice whose details are computed, -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 -this form: - -@example -(@var{name} @var{protected} @var{enabled} @var{definition}) -@end example - -@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 - -@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 -replaced with the new one. -@end defun - -@node Activation of Advice -@section Activation of Advice -@cindex activating advice -@cindex advice, activating - -By default, advice does not take effect when you define it---only when -you @dfn{activate} advice for the function. 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}; or you can activate the advice separately by calling -the function @code{ad-activate} or one of the other activation -commands listed below. - -Separating the activation of advice from the act of defining it permits -you to add several pieces of advice to one function efficiently, without -redefining the function over and over as each advice is added. More -importantly, it permits defining advice for a function before that -function is actually defined. - -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} (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 - - 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}. -@cindex deactivating advice -@c @cindex advice, deactivating "advice, activating" is just above -@end deffn - -@deffn Command ad-update function &optional compile -This command activates the advice for @var{function} -if its advice is already activated. This is useful -if you change the advice. -@end deffn - -@deffn Command ad-activate-all &optional compile -This command activates the advice for all functions. -@end deffn - -@deffn Command ad-deactivate-all -This command deactivates the advice for all functions. -@end deffn - -@deffn Command ad-update-all &optional compile -This command activates the advice for all functions -whose advice is already activated. This is useful -if you change the advice of some functions. -@end deffn - -@deffn Command ad-activate-regexp regexp &optional compile -This command activates all pieces of advice whose names match -@var{regexp}. More precisely, it activates all advice for any function -which has at least one piece of advice that matches @var{regexp}. -@end deffn - -@deffn Command ad-deactivate-regexp regexp -This command deactivates all pieces of advice whose names match -@var{regexp}. More precisely, it deactivates all advice for any -function which has at least one piece of advice that matches -@var{regexp}. -@end deffn - -@deffn Command ad-update-regexp regexp &optional compile -This command activates pieces of advice whose names match @var{regexp}, -but only those for functions whose advice is already activated. -@cindex reactivating advice - -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. This is the default mode. -@end deffn - -@deffn Command ad-stop-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. - -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 -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. - -This variable takes effect only if the @var{compile} argument of -@code{ad-activate} (or any of the above functions) did not force -compilation. -@end defopt - - If the advised definition was constructed during ``preactivation'' -(@pxref{Preactivation}), then that definition must already be compiled, -because it was constructed during byte-compilation of the file that -contained the @code{defadvice} with the @code{preactivate} flag. - -@node Enabling Advice -@section Enabling and Disabling Advice -@cindex enabling advice -@cindex advice, enabling and disabling -@cindex disabling advice - - Each piece of advice has a flag that says whether it is enabled or -not. By enabling or disabling a piece of advice, you can turn it on -and off without having to undefine and redefine it. For example, here is -how to disable a particular piece of advice named @code{my-advice} for -the function @code{foo}: - -@example -(ad-disable-advice 'foo 'before 'my-advice) -@end example - - 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 -(ad-activate 'foo) -@end example - -@deffn Command ad-disable-advice function class name -This command disables the piece of advice named @var{name} in class -@var{class} on @var{function}. -@end deffn - -@deffn Command ad-enable-advice function class name -This command enables the piece of advice named @var{name} in class -@var{class} on @var{function}. -@end deffn - - 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 -@var{regexp}, in all classes, on all functions. -@end deffn - -@deffn Command ad-enable-regexp regexp -This command enables all pieces of advice whose names match -@var{regexp}, in all classes, on all functions. -@end deffn - -@node Preactivation -@section Preactivation -@cindex preactivating advice -@cindex advice, preactivating - - Constructing a combined definition to execute advice is moderately -expensive. When a library advises many functions, this can make loading -the library slow. In that case, you can use @dfn{preactivation} to -construct suitable combined definitions in advance. - - To use preactivation, specify the @code{preactivate} flag when you -define the advice with @code{defadvice}. This @code{defadvice} call -creates a combined definition which embodies this piece of advice -(whether enabled or not) plus any other currently enabled advice for the -same function, and the function's own definition. If the -@code{defadvice} is compiled, that compiles the combined definition -also. - - 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 what was used for preactivation. - - Here are some symptoms that can indicate that a preactivation did not -work properly, because of a mismatch. - -@itemize @bullet -@item -Activation of the advised -function takes longer than usual. -@item -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. -@end itemize - -Compiled preactivated advice works properly even if the function itself -is not defined until later; however, the function needs to be defined -when you @emph{compile} the preactivated advice. - -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'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. - - @strong{Warning:} There is one known case that can make preactivation -fail, in that a preconstructed combined definition is used even though -it fails to match the current state of advice. This can happen when two -packages define different pieces of advice with the same name, in the -same class, for the same function. But you should avoid that anyway. - -@node Argument Access in Advice -@section Argument Access in Advice - - The simplest way to access the arguments of an advised function in the -body of a piece of advice is to use the same names that the function -definition uses. To do this, you need to know the names of the argument -variables of the original function. - - While this simple method is sufficient in many cases, it has a -disadvantage: it is not robust, because it hard-codes the argument names -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 their -(zero-based) position, regardless of how these actual arguments get -distributed onto the argument variables of a function. This is robust -because in Emacs Lisp the meaning of an argument is strictly -determined by its position in the argument list. - -@defmac ad-get-arg position -This returns the actual argument that was supplied at @var{position}. -@end defmac - -@defmac ad-get-args position -This returns the list of actual arguments supplied starting at -@var{position}. -@end defmac - -@defmac ad-set-arg position value -This sets the value of the actual argument at @var{position} to -@var{value} -@end defmac - -@defmac ad-set-args position value-list -This sets the list of actual arguments starting at @var{position} to -@var{value-list}. -@end defmac - - Now an example. Suppose the function @code{foo} is defined as - -@example -(defun foo (x y &optional z &rest r) ...) -@end example - -@noindent -and is then called with - -@example -(foo 0 1 2 3 4 5 6) -@end example - -@noindent -which means that @var{x} is 0, @var{y} is 1, @var{z} is 2 and @var{r} is -@code{(3 4 5 6)} within the body of @code{foo}. Here is what -@code{ad-get-arg} and @code{ad-get-args} return in this case: - -@example -(ad-get-arg 0) @result{} 0 -(ad-get-arg 1) @result{} 1 -(ad-get-arg 2) @result{} 2 -(ad-get-arg 3) @result{} 3 -(ad-get-args 2) @result{} (2 3 4 5 6) -(ad-get-args 4) @result{} (4 5 6) -@end example - - Setting arguments also makes sense in this example: - -@example -(ad-set-arg 5 "five") -@end example - -@noindent -has the effect of changing the sixth argument to @code{"five"}. If this -happens in advice executed before the body of @code{foo} is run, then -@var{r} will be @code{(3 4 "five" 6)} within that body. - - Here is an example of setting a tail of the argument list: - -@example -(ad-set-args 0 '(5 4 3 2 1 0)) -@end example - -@noindent -If this happens in advice executed before the body of @code{foo} is run, -then within that body, @var{x} will be 5, @var{y} will be 4, @var{z} -will be 3, and @var{r} will be @code{(2 1 0)} inside the body of -@code{foo}. - - These argument constructs are not really implemented as Lisp macros. -Instead they are implemented specially by the advice mechanism. - -@node Combined Definition -@section The Combined Definition - - Suppose that a function has @var{n} pieces of before-advice -(numbered from 0 through @var{n}@minus{}1), @var{m} pieces of -around-advice and @var{k} pieces of after-advice. Assuming no piece -of advice is protected, the combined definition produced to implement -the advice for a function looks like this: - -@example -(lambda @var{arglist} - @r{[} @r{[}@var{advised-docstring}@r{]} @r{[}(interactive ...)@r{]} @r{]} - (let (ad-return-value) - @r{before-0-body-form}... - .... - @r{before-@var{n}@minus{}1-body-form}... - @r{around-0-body-form}... - @r{around-1-body-form}... - .... - @r{around-@var{m}@minus{}1-body-form}... - (setq ad-return-value - @r{apply original definition to @var{arglist}}) - @r{end-of-around-@var{m}@minus{}1-body-form}... - .... - @r{end-of-around-1-body-form}... - @r{end-of-around-0-body-form}... - @r{after-0-body-form}... - .... - @r{after-@var{k}@minus{}1-body-form}... - ad-return-value)) -@end example - -Macros are redefined as macros, which means adding @code{macro} to -the beginning of the combined definition. - -The interactive form is present if the original function or some piece -of advice specifies one. When an interactive primitive function is -advised, advice uses a special method: it calls the primitive with -@code{call-interactively} so that it will read its own arguments. -In this case, the advice cannot access the arguments. - -The body forms of the various advice in each class are assembled -according to their specified order. The forms of around-advice @var{l} -are included in one of the forms of around-advice @var{l} @minus{} 1. - -The innermost part of the around advice onion is - -@display -apply original definition to @var{arglist} -@end display - -@noindent -whose form depends on the type of the original function. The variable -@code{ad-return-value} is set to whatever this returns. The variable is -visible to all pieces of advice, which can access and modify it before -it is actually returned from the advised function. - -The semantic structure of advised functions that contain protected -pieces of advice is the same. The only difference is that -@code{unwind-protect} forms ensure that the protected advice gets -executed even if some previous piece of advice had an error or a -non-local exit. If any around-advice is protected, then the whole -around-advice onion is protected as a result. diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index 9681c3c42a..0b2154cdb5 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -194,7 +194,6 @@ To view this manual in other formats, click * Loading:: Reading files of Lisp code into Lisp. * Byte Compilation:: Compilation makes programs run faster. -* Advising Functions:: Adding to the definition of a function. * Debugging:: Tools and tips for debugging Lisp programs. * Read and Print:: Converting Lisp objects to text and back. @@ -614,19 +613,6 @@ Byte Compilation * Byte-Code Objects:: The data type used for byte-compiled functions. * Disassembly:: Disassembling byte-code; how to read byte-code. -Advising Emacs Lisp Functions - -* Simple Advice:: A simple example to explain the basics of advice. -* Defining Advice:: Detailed description of @code{defadvice}. -* Around-Advice:: Wrapping advice around a function's definition. -* 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 in Advice:: How advice can access the function's arguments. -* Combined Definition:: How advice is implemented. - Debugging Lisp Programs * Debugger:: A debugger for the Emacs Lisp evaluator. @@ -1561,7 +1547,6 @@ Object Internals @include customize.texi @include loading.texi @include compile.texi -@include advice.texi @c This includes edebug.texi. @include debugging.texi diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index d203f1c824..d86430a5ac 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -21,6 +21,7 @@ define them. * Function Cells:: Accessing or setting the function definition of a symbol. * Closures:: Functions that enclose a lexical environment. +* Advising Functions:: Adding to the definition of a function. * Obsolete Functions:: Declaring functions obsolete. * Inline Functions:: Functions that the compiler will expand inline. * Declare Form:: Adding additional information about a function. @@ -1077,12 +1078,10 @@ This function stores @var{definition} in the function cell of this is not checked. The argument @var{symbol} is an ordinary evaluated argument. -The primary use of this function is as a subroutine by constructs that -define or alter functions, like @code{defadvice} (@pxref{Advising -Functions}). (If @code{defun} were not a primitive, it could be -written as a Lisp macro using @code{fset}.) You can also use it to -give a symbol a function definition that is not a list, e.g., a -keyboard macro (@pxref{Keyboard Macros}): +The primary use of this function is as a subroutine by constructs that define +or alter functions, like @code{defun} or @code{advice-add} (@pxref{Advising +Functions}). You can also use it to give a symbol a function definition that +is not a function, e.g., a keyboard macro (@pxref{Keyboard Macros}): @example ;; @r{Define a named keyboard macro.} @@ -1133,6 +1132,269 @@ However, the fact that the internal structure of a closure is implementation detail. For this reason, we recommend against directly examining or altering the structure of closure objects. +@node Advising Functions +@section Advising Emacs Lisp Functions +@cindex advising functions +@cindex piece of advice + +Any variable or object field which holds a function can be modified with the +appropriate setter function, such as @code{set-process-filter}, @code{fset}, or +@code{setq}, but those can be too blunt, completely throwing away the +previous value. + +In order to modify such hooks in a more controlled way, Emacs provides the +macros @code{add-function} and @code{remove-function}, which let you modify the +existing function value by composing it with another function. + +For example, in order to trace the calls to a process filter, you can use: + +@example +(add-function :before (process-filter proc) #'my-tracing-function) +@end example + +This will cause the process's output to be passed first to +@code{my-tracing-function} and then to the original process filter. +When you're done with it, you can revert to the untraced behavior with: + +@example +(remove-function (process-filter proc) #'my-tracing-function) +@end example + +The argument @code{:before} specifies how the two functions are composed, since +there are many different ways to do it. The added function is also called an +@emph{advice}. + +The function cell of a symbol can be manipulated similarly, but since it can +contain other things than a plain function, you have to use @var{advice-add} +and @var{advice-remove} instead, which +@c use @var{add-function} and @var{remove-function} internally, but +know how to handle cases such as when the function cell holds a macro rather +than function, or when the function is autoloaded so the advice's activation +needs to be postponed. + +@menu +* Advising Primitives:: Primitives to Manipulate Advices +* Advising Named Functions:: Advising Named Functions +@end menu + +@node Advising Primitives +@subsection Primitives to manipulate advice + +@defmac add-function where place function &optional props +This macro is the handy way to add the advice @var{function} to the function +stored in @var{place} (@pxref{Generalized Variables}). + +@var{where} determines how @var{function} is composed with the +existing function. It can be one of the following: + +@table @code +@item :before +Call @var{function} before the old function. Both functions receive the +same arguments, and the return value of the composition is the return value of +the old function. More specifically, the composition of the two functions +behaves like: +@example +(lambda (&rest r) (apply @var{function} r) (apply @var{oldfun} r)) +@end example +This is similar to @code{(add-hook @var{hook} @var{function})}, except that it +applies to single-function hooks rather than normal hooks. + +@item :after +Call @var{function} after the old function. Both functions receive the +same arguments, and the return value of the composition is the return value of +the old function. More specifically, the composition of the two functions +behaves like: +@example +(lambda (&rest r) (prog1 (apply @var{oldfun} r) (apply @var{function} r))) +@end example +This is similar to @code{(add-hook @var{hook} @var{function} nil 'append)}, +except that it applies to single-function hooks rather than normal hooks. + +@item :override +This completely replaces the old function with the new one. The old function +can of course be recovered if you later call @code{remove-function}. + +@item :around +Call @var{function} instead of the old function, but provide the old function +as an extra argument to @var{function}. This is the most flexible composition. +For example, it lets you call the old function with different arguments, or +within a let-binding, or you can sometimes delegate the work to the old +function and sometimes override it completely. More specifically, the +composition of the two functions behaves like: +@example +(lambda (&rest r) (apply @var{function} @var{oldfun} r)) +@end example + +@item :before-while +Call @var{function} before the old function and don't call the old +function if @var{function} returns @code{nil}. Both functions receive the +same arguments, and the return value of the composition is the return value of +the old function. More specifically, the composition of the two functions +behaves like: +@example +(lambda (&rest r) (and (apply @var{function} r) (apply @var{oldfun} r))) +@end example +This is reminiscent of @code{(add-hook @var{hook} @var{function})}, when +@var{hook} is run via @code{run-hook-with-args-until-failure}. + +@item :before-until +Call @var{function} before the old function and only call the old function if +@var{function} returns @code{nil}. More specifically, the composition of the +two functions behaves like: +@example +(lambda (&rest r) (or (apply @var{function} r) (apply @var{oldfun} r))) +@end example +This is reminiscent of @code{(add-hook @var{hook} @var{function})}, when +@var{hook} is run via @code{run-hook-with-args-until-success}. + +@item :after-while +Call @var{function} after the old function and only if the old function +returned non-@code{nil}. Both functions receive the same arguments, and the +return value of the composition is the return value of @var{function}. +More specifically, the composition of the two functions behaves like: +@example +(lambda (&rest r) (and (apply @var{oldfun} r) (apply @var{function} r))) +@end example +This is reminiscent of @code{(add-hook @var{hook} @var{function} nil 'append)}, +when @var{hook} is run via @code{run-hook-with-args-until-failure}. + +@item :after-until +Call @var{function} after the old function and only if the old function +returned @code{nil}. More specifically, the composition of the two functions +behaves like: +@example +(lambda (&rest r) (or (apply @var{oldfun} r) (apply @var{function} r))) +@end example +This is reminiscent of @code{(add-hook @var{hook} @var{function} nil 'append)}, +when @var{hook} is run via @code{run-hook-with-args-until-success}. + +@item :filter-args +Call @var{function} first and use the result (which should be a list) as the +new arguments to pass to the old function. More specifically, the composition +of the two functions behaves like: +@example +(lambda (&rest r) (apply @var{oldfun} (funcall @var{function} r))) +@end example + +@item :filter-return +Call the old function first and pass the result to @var{function}. +More specifically, the composition of the two functions behaves like: +@example +(lambda (&rest r) (funcall @var{function} (apply @var{oldfun} r))) +@end example +@end table + +When modifying a variable (whose name will usually end with @code{-function}), +you can choose whether @var{function} is used globally or only in the current +buffer: if @var{place} is just a symbol, then @var{function} is added to the +global value of @var{place}. Whereas if @var{place} is of the form +@code{(local @var{symbol})}, where @var{symbol} is an expression which returns +the variable name, then @var{function} will only be added in the +current buffer. + +Every function added with @code{add-function} can be accompanied by an +association list of properties @var{props}. Currently only two of those +properties have a special meaning: + +@table @code +@item name +This gives a name to the advice, which @code{remove-function} can use to +identify which function to remove. Typically used when @var{function} is an +anonymous function. + +@item depth +This specifies where to place the advice, in case several advices are present. +By default, the depth is 0. A depth of 100 indicates that this advice should +be kept as deep as possible, whereas a depth of -100 indicates that it +should stay as the outermost advice. When two advices specify the same depth, +the most recently added advice will be outermost. +@end table +@end defmac + +@defmac remove-function place function +This macro removes @var{function} from the function stored in +@var{place}. This only works if @var{function} was added to @var{place} +using @code{add-function}. + +@var{function} is compared with functions added to @var{place} using +@code{equal}, to try and make it work also with lambda expressions. It is +additionally compared also with the @code{name} property of the functions added +to @var{place}, which can be more reliable than comparing lambda expressions +using @code{equal}. +@end defmac + +@defun advice-function-member-p advice function-def +Return non-@code{nil} if @var{advice} is already in @var{function-def}. +Like for @code{remove-function} above, instead of @var{advice} being the actual +function, it can also be the @code{name} of the piece of advice. +@end defun + +@defun advice-function-mapc f function-def +Call the function @var{f} for every advice that was added to +@var{function-def}. @var{f} is called with two arguments: the advice function +and its properties. +@end defun + +@node Advising Named Functions +@subsection Advising Named Functions + +A common use of advice is for named functions and macros. +Since @var{add-function} does not know how to deal with macros and autoloaded +functions, Emacs provides a separate set of functions to manipulate pieces of +advice applied to named functions. + + Advice can be useful for altering the behavior of an existing +function without having to redefine the whole function. However, it +can be a source of bugs, since existing callers to the function may +assume the old behavior, and work incorrectly when the behavior is +changed by advice. Advice can also cause confusion in debugging, if +the person doing the debugging does not notice or remember that the +function has been modified by advice. + + For these reasons, advice should be reserved for the cases where you +cannot modify a function's behavior in any other way. If it is +possible to do the same thing via a hook, that is preferable +(@pxref{Hooks}). If you simply want to change what a particular key +does, it may be better to write a new command, and remap the old +command's key bindings to the new one (@pxref{Remapping Commands}). +In particular, Emacs's own source files should not put advice on +functions in Emacs. (There are currently a few exceptions to this +convention, but we aim to correct them.) + + Macros can also be advised, in much the same way as functions. +However, special forms (@pxref{Special Forms}) cannot be advised. + + It is possible to advise a primitive (@pxref{What Is a Function}), +but one should typically @emph{not} do so, for two reasons. Firstly, +some primitives are used by the advice mechanism, and advising them +could cause an infinite recursion. Secondly, many primitives are +called directly from C, and such calls ignore advice; hence, one ends +up in a confusing situation where some calls (occurring from Lisp +code) obey the advice and other calls (from C code) do not. + +@defun advice-add symbol where function &optional props +Add the advice @var{function} to the named function @var{symbol}. +@var{where} and @var{props} have the same meaning as for @code{add-function} +(@pxref{Advising Primitives}). +@end defun + +@defun advice-remove symbol function +Remove the advice @var{function} from the named function @var{symbol}. +@var{function} can also be the @code{name} of an advice. +@end defun + +@defun advice-member-p function symbol +Return non-@code{nil} if the advice @var{function} is already in the named +function @var{symbol}. @var{function} can also be the @code{name} of +an advice. +@end defun + +@defun advice-mapc function symbol +Call @var{function} for every advice that was added to the named function +@var{symbol}. @var{function} is called with two arguments: the advice function +and its properties. +@end defun + @node Obsolete Functions @section Declaring Functions Obsolete @cindex obsolete functions diff --git a/doc/lispref/makefile.w32-in b/doc/lispref/makefile.w32-in index a56edd9f49..01fe14944f 100644 --- a/doc/lispref/makefile.w32-in +++ b/doc/lispref/makefile.w32-in @@ -49,7 +49,6 @@ texinputdir = $(srcdir)\..\..\nt\envadd.bat \ srcs = \ $(emacsdir)/emacsver.texi \ $(srcdir)/abbrevs.texi \ - $(srcdir)/advice.texi \ $(srcdir)/anti.texi \ $(srcdir)/backups.texi \ $(srcdir)/buffers.texi \ diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index 50bbe2914e..df0dd1a58e 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -69,11 +69,13 @@ functions are called with arguments, or their return values are used in some way. The hook's documentation says how the functions are called. You can use @code{add-hook} to add a function to an abnormal hook, but you must write the function to follow the hook's calling -convention. +convention. By convention, abnormal hook names end in @samp{-functions}. - By convention, abnormal hook names end in @samp{-functions}. If the -variable's name ends in @samp{-function}, then its value is just a single -function, not a list of functions. +@cindex single-function hook +If the variable's name ends in @samp{-function}, then its value is +just a single function, not a list of functions. @code{add-hook} cannot be +used to modify such a @emph{single function hook}, and you have to use +@code{add-function} instead (@pxref{Advising Functions}). @menu * Running Hooks:: How to run a hook. @@ -129,47 +131,6 @@ non-@code{nil} value, it returns that value; otherwise it returns @code{nil}. @end defun -@defmac with-wrapper-hook hook args &rest body -This macro runs the abnormal hook @code{hook} as a series of nested -``wrapper functions'' around the @var{body} forms. The effect is -similar to nested @code{around} advices (@pxref{Around-Advice}). - -Each hook function should accept an argument list consisting of a function -@var{fun}, followed by the additional arguments listed in @var{args}. -The first hook function is passed a function @var{fun} that, if it is -called with arguments @var{args}, performs @var{body} (i.e., the default -operation). The @var{fun} passed to each successive hook function is -constructed from all the preceding hook functions (and @var{body}); if -this @var{fun} is called with arguments @var{args}, it does what the -@code{with-wrapper-hook} call would if the preceding hook functions were -the only ones in @var{hook}. - -Each hook function may call its @var{fun} argument as many times as it -wishes, including never. In that case, such a hook function acts to -replace the default definition altogether, and any preceding hook -functions. Of course, a subsequent hook function may do the same thing. - -Each hook function definition is used to construct the @var{fun} passed -to the next hook function in @var{hook}, if any. The last or -``outermost'' @var{fun} is called once to produce the overall effect. - -When might you want to use a wrapper hook? The function -@code{filter-buffer-substring} illustrates a common case. There is a -basic functionality, performed by @var{body}---in this case, to extract -a buffer-substring. Then any number of hook functions can act in -sequence to modify that string, before returning the final result. -A wrapper-hook also allows for a hook function to completely replace the -default definition (by not calling @var{fun}). -@end defmac - -@defun run-hook-wrapped hook wrap-function &rest args -This function is similar to @code{run-hook-with-args-until-success}. -Like that function, it runs the functions on the abnormal hook -@code{hook}, stopping at the first one that returns non-@code{nil}. -Instead of calling the hook functions directly, though, it actually -calls @code{wrap-function} with arguments @code{fun} and @code{args}. -@end defun - @node Setting Hooks @subsection Setting Hooks diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog index 41e7e3d768..65a2da7d54 100644 --- a/doc/misc/ChangeLog +++ b/doc/misc/ChangeLog @@ -1,3 +1,7 @@ +2014-01-10 Stefan Monnier + + * cl.texi (Function Bindings): Fix incorrect description of cl-let. + 2014-01-09 Rüdiger Sonderfeld * Makefile.in: Add eww.texi. @@ -18,8 +22,8 @@ (Advanced configuration) (Header arguments in Org mode properties): Spelling fixes. (Special blocks): Add #+BEGIN_ABSTRACT as another example. - (@LaTeX{} specific attributes): New index entries. Use - #+BEGIN_ABSTRACT in the example. + (@LaTeX{} specific attributes): New index entries. + Use #+BEGIN_ABSTRACT in the example. 2013-01-07 Nicolas Goaziou @@ -80,7 +84,7 @@ 2014-01-02 Aidan Gauland - * eshell.texi (Command Basics): Removed `Command basics' chapter. + * eshell.texi (Command Basics): Remove `Command basics' chapter. 2014-01-02 Aidan Gauland @@ -200,8 +204,8 @@ * org.texi (Orgstruct mode): Fix suggested setting of `orgstruct-heading-prefix-regexp'. - * org.texi (Export settings): Document - `org-export-allow-bind-keywords'. + * org.texi (Export settings): + Document `org-export-allow-bind-keywords'. * org.texi (History and Acknowledgments): Small rephrasing. @@ -209,8 +213,8 @@ in a year datetree. * org.texi (Beamer export, @LaTeX{} and PDF export) - (Header and sectioning, @LaTeX{} specific attributes): Enhance - style. + (Header and sectioning, @LaTeX{} specific attributes): + Enhance style. * org.texi (Agenda commands): Add a footnote about dragging agenda lines: it does not persist and it does not change the .org files. @@ -229,15 +233,15 @@ * org.texi (Other built-in back-ends): New section. - * org.texi (Editing source code): Document - `org-edit-src-auto-save-idle-delay' and + * org.texi (Editing source code): + Document `org-edit-src-auto-save-idle-delay' and `org-edit-src-turn-on-auto-save'. * org.texi (External links): Document contributed link types separately. - * org.texi (Closing items): Document - `org-closed-keep-when-no-todo'. + * org.texi (Closing items): + Document `org-closed-keep-when-no-todo'. * org.texi (Export back-ends): Rename from "Export formats". (The Export Dispatcher): Remove reference to @@ -273,8 +277,8 @@ (Agenda commands): Move details about filtering commands to the new section, only include a summary here. (Customizing tables in ODT export) - (System-wide header arguments, Conflicts, Dynamic blocks): Use - spaces for indentation. + (System-wide header arguments, Conflicts, Dynamic blocks): + Use spaces for indentation. * org.texi (Emphasis and monospace): Mention `org-emphasis-alist'. @@ -331,8 +335,8 @@ (In-buffer settings): Update to reflect changes from the new export engine. - * org.texi (Matching tags and properties): More examples. Explain - group tags expansion as regular expressions. + * org.texi (Matching tags and properties): More examples. + Explain group tags expansion as regular expressions. * org.texi (Tag groups): New section. @@ -357,8 +361,8 @@ * org.texi (Org syntax): New section. - * org.texi (Orgstruct mode): Document - `orgstruct-heading-prefix-regexp'. + * org.texi (Orgstruct mode): + Document `orgstruct-heading-prefix-regexp'. * org.texi (Speeding up your agendas): New section. @@ -382,8 +386,8 @@ * org.texi: Update the list contributions. * org.texi (Agenda commands): Exporting the agenda to an .org file - will not copy the subtrees and the inherited tags. Document - `org-agenda-filter-by-regexp'. + will not copy the subtrees and the inherited tags. + Document `org-agenda-filter-by-regexp'. * org.texi (Publishing action, Complex example): Fix names of publishing functions. @@ -397,8 +401,8 @@ * org.texi (Capture): Mention that org-remember.el is not supported anymore. - * org.texi (Top, Exporting, Beamer class export): Delete - references to the TaskJuggler export. + * org.texi (Top, Exporting, Beamer class export): + Delete references to the TaskJuggler export. (History and Acknowledgments): Mention that the TaskJuggler has been rewritten by Nicolas and now lives in the contrib/ directory of Org's distribution. Mention that Jambunathan rewrote the HTML @@ -415,16 +419,16 @@ (@LaTeX{} and PDF export, Header and sectioning) (Publishing options): Fix LaTeX options names. - * org.texi (Export options, CSS support, In-buffer settings): Fix - references to HTML_LINK_* and HTML_STYLE keywords. + * org.texi (Export options, CSS support, In-buffer settings): + Fix references to HTML_LINK_* and HTML_STYLE keywords. * org.texi (Export options, In-buffer settings): Fix references to #+SELECT_TAGS and #+EXCLUDE_TAGS and remove reference to #+XSLT. * org.texi (Top, Markup, Initial text, Images and tables) (@LaTeX{} fragments, @LaTeX{} fragments, Exporting) - (Export options, JavaScript support, Beamer class export): Remove - references to the DocBook export, which has been deleted. + (Export options, JavaScript support, Beamer class export): + Remove references to the DocBook export, which has been deleted. (History and Acknowledgments): Mention that DocBook has been deleted, suggest to use the Texinfo exporter instead, then to convert the .texi to DocBook with makeinfo. @@ -433,8 +437,8 @@ * org.texi (Deadlines and scheduling): Add a variable to the index. Add documentation about delays for scheduled tasks. - * org.texi (Emphasis and monospace): Mention - `org-fontify-emphasized-text' and + * org.texi (Emphasis and monospace): + Mention `org-fontify-emphasized-text' and `org-emphasis-regexp-components'. * org.texi (References): Small enhancement. @@ -491,7 +495,7 @@ * org.texi (Extracting source code): Mention the prefix argument to org-babel-tangle. - (noweb): Removed erroneous negative. + (noweb): Remove erroneous negative. (Specific header arguments): Document new header arguments. Documentation for new tangle-mode header argument. (Top): Documentation for new tangle-mode header argument. @@ -595,8 +599,8 @@ * org.texi (Header and sectioning): Add a footnote about the different between LATEX_HEADER_EXTRA and LATEX_HEADER. - * org.texi (The Export Dispatcher): Document - `org-export-in-background'. + * org.texi (The Export Dispatcher): + Document `org-export-in-background'. * org.texi (Footnotes): Export back-ends do not use `org-footnote-normalize' anymore. @@ -618,19 +622,19 @@ * org.texi (Include files): Remove reference to :prefix1 and :prefix. Give more details for :minlevel. - * org.texi (Macro replacement): Fix macro name. Update - documentation about possible locations and escaping mechanism. + * org.texi (Macro replacement): Fix macro name. + Update documentation about possible locations and escaping mechanism. - * org.texi (Table of contents): Update documentation. Document - lists of listings and lists of tables. Add documentation for + * org.texi (Table of contents): Update documentation. + Document lists of listings and lists of tables. Add documentation for optional title and #+TOC: keyword. 2013-11-12 Rick Frankel * org.texi (results): Add Format section, broken out of Type section to match code. - (hlines, colnames): Remove incorrect Emacs Lisp exception. Note - that the actual default handling (at least for python and + (hlines, colnames): Remove incorrect Emacs Lisp exception. + Note that the actual default handling (at least for python and emacs-lisp) does not seem to match the description. 2013-11-12 Sacha Chua (tiny change) @@ -640,8 +644,8 @@ 2013-11-12 Yasushi Shoji - * org.texi (Resolving idle time): Document - `org-clock-x11idle-program-name'. + * org.texi (Resolving idle time): + Document `org-clock-x11idle-program-name'. 2013-10-24 Michael Albinus @@ -882,8 +886,8 @@ 2013-07-29 Michael Albinus - * tramp.texi (Frequently Asked Questions): Mention - `tramp-use-ssh-controlmaster-options'. + * tramp.texi (Frequently Asked Questions): + Mention `tramp-use-ssh-controlmaster-options'. 2013-07-26 Tassilo Horn @@ -927,8 +931,8 @@ 2013-07-08 Tassilo Horn * gnus.texi (lines): Correct description of - `gnus-registry-track-extra's default value. Mention - `gnus-registry-remove-extra-data'. + `gnus-registry-track-extra's default value. + Mention `gnus-registry-remove-extra-data'. 2013-07-06 Lars Ingebrigtsen diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi index 08f9610e59..0490cf639a 100644 --- a/doc/misc/cl.texi +++ b/doc/misc/cl.texi @@ -1282,13 +1282,8 @@ cells of symbols rather than on the value cells. Each @var{binding} must be a list of the form @samp{(@var{name} @var{arglist} @var{forms}@dots{})}, which defines a function exactly as if it were a @code{cl-defun} form. The function @var{name} is defined -accordingly for the duration of the body of the @code{cl-flet}; then -the old function definition, or lack thereof, is restored. - -You can use @code{cl-flet} to disable or modify the behavior of -functions (including Emacs primitives) in a temporary, localized fashion. -(Compare this with the idea of advising functions. -@xref{Advising Functions,,,elisp,GNU Emacs Lisp Reference Manual}.) +accordingly but only within the body of the @code{cl-flet}, hiding any external +definition if applicable. The bindings are lexical in scope. This means that all references to the named functions must appear physically within the body of the diff --git a/etc/NEWS b/etc/NEWS index c8088e17bb..9817115918 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -905,6 +905,7 @@ It is only available if Emacs is compiled with libxml2 support. symbol_words as a single word, similar to what `subword-mode' does and using the same internal functions. ++++ ** New package nadvice.el offers lighter-weight advice facilities. It is layered as: - add-function/remove-function which can be used to add/remove code on any -- 2.39.2