* 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.

9 files changed, 333 insertions, 866 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 2963ffc9a60..38427e56b9b 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,14 @@
+2014-01-10  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+        * 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  <ruediger@c-plusplus.de>
 
         * text.texi (Parsing HTML/XML): Document `shr-insert-document'.
diff --git a/doc/lispref/Makefile.in b/doc/lispref/Makefile.in
index 6f3320d029c..bb8d4f82884 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 c55f93d445f..00000000000
--- 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 9681c3c42a3..0b2154cdb5e 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 d203f1c824f..d86430a5ac0 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 a56edd9f498..01fe14944fd 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 50bbe2914ee..df0dd1a58e0 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 41e7e3d768f..65a2da7d542 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,3 +1,7 @@
+2014-01-10  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+        * cl.texi (Function Bindings): Fix incorrect description of cl-let.
+
 2014-01-09  Rüdiger Sonderfeld  <ruediger@c-plusplus.de>
 
         * 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  <n.goaziou@gmail.com>
 
@@ -80,7 +84,7 @@
 
 2014-01-02  Aidan Gauland  <aidalgol@amuri.net>
 
-        * eshell.texi (Command Basics): Removed `Command basics' chapter.
+        * eshell.texi (Command Basics): Remove `Command basics' chapter.
 
 2014-01-02  Aidan Gauland  <aidalgol@amuri.net>
 
@@ -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  <rick@rickster.com>
 
         * 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  <sacha@sachachua.com>  (tiny change)
@@ -640,8 +644,8 @@
 
 2013-11-12  Yasushi Shoji  <yashi@atmark-techno.com>
 
-        * 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  <michael.albinus@gmx.de>
 
@@ -882,8 +886,8 @@
 
 2013-07-29  Michael Albinus  <michael.albinus@gmx.de>
 
-        * 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  <tsdh@gnu.org>
 
@@ -927,8 +931,8 @@
 2013-07-08  Tassilo Horn  <tsdh@gnu.org>
 
         * 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  <larsi@gnus.org>
 
diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi
index 08f9610e594..0490cf639ac 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