cl.texi flet clarification

* doc/misc/cl.texi (Function Bindings): Clarify that cl-flet is lexical.
(Obsolete Macros): Move example here from Function Bindings.

* etc/NEWS: Related edit.

doc/misc/ChangeLog

+2012-11-16  Glenn Morris  <rgm@gnu.org>
+
+	* cl.texi (Function Bindings): Clarify that cl-flet is lexical.
+	(Obsolete Macros): Move example here from Function Bindings.
+
 2012-11-13  Glenn Morris  <rgm@gnu.org>
 
 	* erc.texi: Use @code{nil} rather than just "nil".

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

etc/NEWS

@@ -320,6 +320,8 @@ provide the old non-prefixed names.  Some exceptions are listed below.
 +++
 *** `cl-flet' is not like `flet' (which is deprecated).
 Instead it obeys the behavior of Common-Lisp's `flet'.
+In particular, in cl-flet function definitions are lexically scoped,
+whereas in flet the scoping is dynamic.
 
 +++
 *** `cl-labels' is slightly different from `labels'.