1 files changed, 27 insertions, 21 deletions

diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi
index a50be1027f3..beefa3e9c40 100644
--- a/doc/misc/cl.texi
+++ b/doc/misc/cl.texi
@@ -1292,28 +1292,14 @@ 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 a
-function in a temporary fashion.  (Compare this with the idea
-of advising functions.
+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}.)
-This will even work on Emacs primitives, although note that some calls
-to primitive functions internal to Emacs are made without going
-through the symbol's function cell, and so will not be affected by
-@code{cl-flet}.  For example,
-
-@example
-(cl-flet ((message (&rest args) (push args saved-msgs)))
-    (do-something))
-@end example
 
-This code attempts to replace the built-in function @code{message}
-with a function that simply saves the messages in a list rather
-than displaying them.  The original definition of @code{message}
-will be restored after @code{do-something} exits.  This code will
-work fine on messages generated by other Lisp code, but messages
-generated directly inside Emacs will not be caught since they make
-direct C-language calls to the message routines rather than going
-through the Lisp @code{message} function.
+The bindings are lexical in scope.  This means that all references to
+the named functions must appear physically within the body of the
+@code{cl-flet} form.
 
 Functions defined by @code{cl-flet} may use the full Common Lisp
 argument notation supported by @code{cl-defun}; also, the function
@@ -1321,7 +1307,8 @@ body is enclosed in an implicit block as if by @code{cl-defun}.
 @xref{Program Structure}.
 
 Note that the @file{cl.el} version of this macro behaves slightly
-differently.  @xref{Obsolete Macros}.
+differently.  In particular, its binding is dynamic rather than
+lexical.  @xref{Obsolete Macros}.
 @end defmac
 
 @defmac cl-labels (bindings@dots{}) forms@dots{}
@@ -4863,6 +4850,25 @@ time before Emacs had lexical binding).  The result is
 that @code{flet} affects indirect calls to a function as well as calls
 directly inside the @code{flet} form itself.
 
+This will even work on Emacs primitives, although note that some calls
+to primitive functions internal to Emacs are made without going
+through the symbol's function cell, and so will not be affected by
+@code{flet}.  For example,
+
+@example
+(flet ((message (&rest args) (push args saved-msgs)))
+  (do-something))
+@end example
+
+This code attempts to replace the built-in function @code{message}
+with a function that simply saves the messages in a list rather
+than displaying them.  The original definition of @code{message}
+will be restored after @code{do-something} exits.  This code will
+work fine on messages generated by other Lisp code, but messages
+generated directly inside Emacs will not be caught since they make
+direct C-language calls to the message routines rather than going
+through the Lisp @code{message} function.
+
 @c Bug#411.
 Note that many primitives (e.g.@: @code{+}) have special byte-compile
 handling.  Attempts to redefine such functions using @code{flet} will